Application Load Balancer API, gRPC: VirtualHostService
A set of methods for managing virtual hosts of HTTP routers.
Call | Description |
---|---|
Get | Returns the specified virtual host. |
List | Lists virtual hosts of the specified HTTP router. |
Create | Creates a virtual host in the specified HTTP router. |
Update | Updates the specified virtual host of the specified HTTP router. |
Delete | Deletes the specified virtual host. |
RemoveRoute | Deletes the specified route from the specified virtual host. |
UpdateRoute | Updates the specified route of the specified virtual host. |
Calls VirtualHostService
Get
Returns the specified virtual host.
To get the list of all virtual hosts of an HTTP router, make a List request.
rpc Get (GetVirtualHostRequest) returns (VirtualHost)
GetVirtualHostRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router that the virtual host belongs to. To get the HTTP router ID, make a HttpRouterService.List request. |
virtual_host_name | string Required. Name of the virtual host to return. To get the virtual host name, make a VirtualHostService.List request. Value must match the regular expression ([a-z]([-a-z0-9]{0,61}[a-z0-9])?)? . |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
List
Lists virtual hosts of the specified HTTP router.
rpc List (ListVirtualHostsRequest) returns (ListVirtualHostsResponse)
ListVirtualHostsRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to list virtual hosts in. To get the HTTP router ID, make a HttpRouterService.List request. |
page_size | int64 The maximum number of results per page to return. If the number of available results is larger than page_size , the service returns a ListVirtualHostsResponse.next_page_token that can be used to get the next page of results in subsequent list requests. Default value: 100. The maximum value is 1000. |
page_token | string Page token. To get the next page of results, set page_token to the ListVirtualHostsResponse.next_page_token returned by a previous list request. The maximum string length in characters is 100. |
ListVirtualHostsResponse
Field | Description |
---|---|
virtual_hosts[] | VirtualHost List of virtual hosts of the specified HTTP router. |
next_page_token | string Token for getting the next page of the list. If the number of results is greater than the specified ListVirtualHostsRequest.page_size, use next_page_token as the value for the ListVirtualHostsRequest.page_token parameter in the next list request. Each subsequent page will have its own next_page_token to continue paging through the results. |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
Create
Creates a virtual host in the specified HTTP router.
rpc Create (CreateVirtualHostRequest) returns (operation.Operation)
Metadata and response of Operation:
Operation.metadata:CreateVirtualHostMetadata
Operation.response:VirtualHost
CreateVirtualHostRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to create a virtual host in. To get the HTTP router ID, make a HttpRouterService.List request. |
name | string Name of the virtual host. The name must be unique within the HTTP router and cannot be changed after creation. Value must match the regular expression ([a-z]([-a-z0-9]{0,61}[a-z0-9])?)? . |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Modifications that are made to the headers of incoming HTTP requests before they are forwarded to backends. |
modify_response_headers[] | HeaderModification Modifications that are made to the headers of HTTP responses received from backends before responses are forwarded to clients. |
route_options | RouteOptions Route options for the virtual host. |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
Operation
Field | Description |
---|---|
id | string ID of the operation. |
description | string Description of the operation. 0-256 characters long. |
created_at | google.protobuf.Timestamp Creation timestamp. |
created_by | string ID of the user or service account who initiated the operation. |
modified_at | google.protobuf.Timestamp The time when the Operation resource was last modified. |
done | bool If the value is false , it means the operation is still in progress. If true , the operation is completed, and either error or response is available. |
metadata | google.protobuf.Any Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. |
result | oneof: error or response The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true , exactly one of error or response is set. |
error | google.rpc.Status The error result of the operation in case of failure or cancellation. |
response | google.protobuf.Any if operation finished successfully. |
CreateVirtualHostMetadata
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router that the virtual host is being created in. |
virtual_host_name | string Name of the virtual host that is being created. |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Update
Updates the specified virtual host of the specified HTTP router.
rpc Update (UpdateVirtualHostRequest) returns (operation.Operation)
Metadata and response of Operation:
Operation.metadata:UpdateVirtualHostMetadata
Operation.response:VirtualHost
UpdateVirtualHostRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to update a virtual host in. To get the HTTP router ID, make a HttpRouterService.List request. |
virtual_host_name | string Required. Name of the virtual host. Used only to refer to the virtual host. The name of a host cannot be changed. To get the virtual host name, make a VirtualHostService.List request. |
update_mask | google.protobuf.FieldMask Field mask that specifies which attributes of the virtual host should be updated. |
authority[] | string New list of domains to attribute to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. Existing list of domains is completely replaced by the specified list. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route New list of routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. Existing list of routes is completely replaced by the specified list, so if you just want to remove a route, make a VirtualHostService.RemoveRoute request. |
modify_request_headers[] | HeaderModification New list of modifications that are made to the headers of incoming HTTP requests before they are forwarded to backends. Existing list of modifications is completely replaced by the specified list. |
modify_response_headers[] | HeaderModification New list of modifications that are made to the headers of HTTP responses received from backends before responses are forwarded to clients. Existing list of modifications is completely replaced by the specified list. |
route_options | RouteOptions New route options for the virtual host. |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
Operation
Field | Description |
---|---|
id | string ID of the operation. |
description | string Description of the operation. 0-256 characters long. |
created_at | google.protobuf.Timestamp Creation timestamp. |
created_by | string ID of the user or service account who initiated the operation. |
modified_at | google.protobuf.Timestamp The time when the Operation resource was last modified. |
done | bool If the value is false , it means the operation is still in progress. If true , the operation is completed, and either error or response is available. |
metadata | google.protobuf.Any Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. |
result | oneof: error or response The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true , exactly one of error or response is set. |
error | google.rpc.Status The error result of the operation in case of failure or cancellation. |
response | google.protobuf.Any if operation finished successfully. |
UpdateVirtualHostMetadata
Field | Description |
---|---|
http_router_id | string ID of the HTTP router that the virtual host is being updated in. |
virtual_host_name | string Name of the virtual host that is being updated. |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Delete
Deletes the specified virtual host.
rpc Delete (DeleteVirtualHostRequest) returns (operation.Operation)
Metadata and response of Operation:
Operation.metadata:DeleteVirtualHostMetadata
Operation.response:google.protobuf.Empty
DeleteVirtualHostRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to delete a virtual host from. To get the HTTP router ID, make a HttpRouterService.List request. |
virtual_host_name | string Required. Name of the virtual host to delete. To get the virtual host name, make a VirtualHostService.List request. Value must match the regular expression ([a-z]([-a-z0-9]{0,61}[a-z0-9])?)? . |
Operation
Field | Description |
---|---|
id | string ID of the operation. |
description | string Description of the operation. 0-256 characters long. |
created_at | google.protobuf.Timestamp Creation timestamp. |
created_by | string ID of the user or service account who initiated the operation. |
modified_at | google.protobuf.Timestamp The time when the Operation resource was last modified. |
done | bool If the value is false , it means the operation is still in progress. If true , the operation is completed, and either error or response is available. |
metadata | google.protobuf.Any Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. |
result | oneof: error or response The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true , exactly one of error or response is set. |
error | google.rpc.Status The error result of the operation in case of failure or cancellation. |
response | google.protobuf.Any if operation finished successfully. |
DeleteVirtualHostMetadata
Field | Description |
---|---|
http_router_id | string ID of the HTTP router that the virtual host is being deleted from. |
virtual_host_name | string Name of the virtual host that is being deleted. |
RemoveRoute
Deletes the specified route from the specified virtual host.
rpc RemoveRoute (RemoveRouteRequest) returns (operation.Operation)
Metadata and response of Operation:
Operation.metadata:RemoveRouteMetadata
Operation.response:VirtualHost
RemoveRouteRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to delete a route from. To get the HTTP router ID, make a HttpRouterService.List request. |
virtual_host_name | string Required. Name of the virtual host to delete a route from. To get the virtual host name, make a VirtualHostService.List request. |
route_name | string Required. Name of the route to delete. To get the route name, make a VirtualHostService.Get request. |
Operation
Field | Description |
---|---|
id | string ID of the operation. |
description | string Description of the operation. 0-256 characters long. |
created_at | google.protobuf.Timestamp Creation timestamp. |
created_by | string ID of the user or service account who initiated the operation. |
modified_at | google.protobuf.Timestamp The time when the Operation resource was last modified. |
done | bool If the value is false , it means the operation is still in progress. If true , the operation is completed, and either error or response is available. |
metadata | google.protobuf.Any Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. |
result | oneof: error or response The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true , exactly one of error or response is set. |
error | google.rpc.Status The error result of the operation in case of failure or cancellation. |
response | google.protobuf.Any if operation finished successfully. |
RemoveRouteMetadata
Field | Description |
---|---|
http_router_id | string ID of the HTTP router that the route is being deleted from. |
virtual_host_name | string Name of the virtual host that the route is being deleted from. |
route_name | string Name of the route that is being deleted. |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
UpdateRoute
Updates the specified route of the specified virtual host.
rpc UpdateRoute (UpdateRouteRequest) returns (operation.Operation)
Metadata and response of Operation:
Operation.metadata:UpdateRouteMetadata
Operation.response:VirtualHost
UpdateRouteRequest
Field | Description |
---|---|
http_router_id | string Required. ID of the HTTP router to update a route in. To get the HTTP router ID, make a HttpRouterService.List request. |
virtual_host_name | string Required. Name of the virtual host to update a route in. To get the virtual host name, make a VirtualHostService.List request. |
route_name | string Required. Name of the route to update. To get the route name, make a VirtualHostService.Get request. |
update_mask | google.protobuf.FieldMask Field mask that specifies which attributes of the route should be updated. |
route | oneof: http or grpc New settings of the route. |
http | HttpRoute New settings of the HTTP route. |
grpc | GrpcRoute New settings of the gRPC route. |
route_options | RouteOptions New route options for the route. |
HttpRoute
Field | Description |
---|---|
match | HttpRouteMatch Condition (predicate) used to select the route. |
action | oneof: route , redirect or direct_response Action performed on the request if the route is selected. |
route | HttpRouteAction Forwards the request to a backend group for processing as configured. |
redirect | RedirectAction Redirects the request as configured. |
direct_response | DirectResponseAction Instructs the load balancer to respond directly as configured. |
HttpRouteMatch
Field | Description |
---|---|
http_method[] | string HTTP method specified in the request. |
path | StringMatch Match settings for the path specified in the request. If not specified, the route matches all paths. |
StringMatch
Field | Description |
---|---|
match | oneof: exact_match , prefix_match or regex_match Match string for either exact or prefix match. |
exact_match | string Exact match string. |
prefix_match | string Prefix match string. |
regex_match | string Regular expression match string. |
HttpRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. Stream (TCP) backend groups are not supported. |
timeout | google.protobuf.Duration Overall timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events (EventSource interface) etc. If a connection times out, the load balancer responds to the client with a 504 Gateway Timeout status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
prefix_rewrite | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and prefix_rewrite value is /bar , a request with /foobaz path is forwarded with /barbaz path. For StringMatch.exact_match, the whole path is replaced. If not specified, the path is not changed. |
upgrade_types[] | string Supported values for HTTP Upgrade header. E.g. websocket . |
RedirectAction
Field | Description |
---|---|
replace_scheme | string URI scheme replacement. If http or https scheme is to be replaced and 80 or 443 port is specified in the original URI, the port is also removed. If not specified, the original scheme and port are used. |
replace_host | string URI host replacement. If not specified, the original host is used. |
replace_port | int64 URI host replacement. If not specified, the original host is used. |
path | oneof: replace_path or replace_prefix URI path replacement. If not specified, the original path is used. |
replace_path | string Replacement for the whole path. |
replace_prefix | string Replacement for the path prefix matched by StringMatch. For instance, if StringMatch.prefix_match value is /foo and replace_prefix value is /bar , a request with https://example.com/foobaz URI is redirected to https://example.com/barbaz . For StringMatch.exact_match, the whole path is replaced. |
remove_query | bool Removes URI query. |
response_code | enum RedirectResponseCode HTTP status code to use in redirect responses.
|
DirectResponseAction
Field | Description |
---|---|
status | int64 HTTP status code to use in responses. Acceptable values are 100 to 599, inclusive. |
body | Payload Response body. |
Payload
Field | Description |
---|---|
payload | oneof: text Payload. |
text | string Payload text. The string length in characters must be greater than 0. |
GrpcRoute
Field | Description |
---|---|
match | GrpcRouteMatch Condition (predicate) used to select the route. |
action | oneof: route or status_response Action performed on the request if the route is selected. |
route | GrpcRouteAction Forwards the request to a backend group for processing as configured. |
status_response | GrpcStatusResponseAction Instructs the load balancer to respond directly with a specified status. |
GrpcRouteMatch
Field | Description |
---|---|
fqmn | StringMatch Match settings for gRPC service method called in the request. A match string must be a fully qualified method name, e.g. foo.bar.v1.BazService/Get , or a prefix of such. If not specified, the route matches all methods. |
GrpcRouteAction
Field | Description |
---|---|
backend_group_id | string Required. Backend group to forward requests to. |
max_timeout | google.protobuf.Duration Overall timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is kept alive for, regardless of whether data is transferred over it. If a client specifies a lower timeout in HTTP grpc-timeout header, the max_timeout value is ignored. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. Default value: 60 . |
idle_timeout | google.protobuf.Duration Idle timeout for an underlying HTTP connection between a load balancer node an a backend from the backend group: the maximum time the connection is allowed to be idle, i.e. without any data transferred over it. Specifying meaningful values for both max_timeout and idle_timeout is useful for implementing server-push mechanisms such as long polling, server-sent events etc. If a connection times out, the load balancer responds to the client with an UNAVAILABLE status code. If not specified, no idle timeout is used, and an alive connection may be idle for any duration (see max_timeout ). |
host_rewrite_specifier | oneof: host_rewrite or auto_host_rewrite Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. If not specified, the host is not changed. |
host_rewrite | string Host replacement. |
auto_host_rewrite | bool Automatically replaces the host with that of the target. |
GrpcStatusResponseAction
Field | Description |
---|---|
status | enum Status gRPC status code
|
RouteOptions
Field | Description |
---|---|
modify_request_headers[] | HeaderModification Apply the following modifications to the request headers. |
modify_response_headers[] | HeaderModification Apply the following modifications to the response headers. |
rbac | RBAC |
security_profile_id | string Security profile that will take effect to all requests routed via particular virtual host. |
HeaderModification
Field | Description |
---|---|
name | string Name of the header. |
operation | oneof: append , replace , remove or rename Operation to perform on the header. |
append | string Appends the specified string to the header value. Variables defined for Envoy proxy |
replace | string Replaces the value of the header with the specified string. Variables defined for Envoy proxy |
remove | bool Removes the header. |
rename | string Replaces the name of the header with the specified string. This operation is only supported for ALB Virtual Hosts. |
RBAC
Field | Description |
---|---|
action | enum Action Required. The action to take if a principal matches. Every action either allows or denies a request.
|
principals[] | Principals Required. A match occurs when at least one matches the request. The minimum number of elements is 1. |
Principals
Field | Description |
---|---|
and_principals[] | Principal Required. A match occurs when all principals match the request. The minimum number of elements is 1. |
Principal
Field | Description |
---|---|
identifier | oneof: header , remote_ip or any |
header | HeaderMatcher A header (or pseudo-header such as: path or: method) of the incoming HTTP request. |
remote_ip | string A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 . |
any | bool When any is set, it matches any request. |
HeaderMatcher
Field | Description |
---|---|
name | string Required. Specifies the name of the header in the request. |
value | StringMatch Specifies how the header match will be performed to route the request. In the absence of value a request that has specified header name will match, regardless of the header's value. |
Operation
Field | Description |
---|---|
id | string ID of the operation. |
description | string Description of the operation. 0-256 characters long. |
created_at | google.protobuf.Timestamp Creation timestamp. |
created_by | string ID of the user or service account who initiated the operation. |
modified_at | google.protobuf.Timestamp The time when the Operation resource was last modified. |
done | bool If the value is false , it means the operation is still in progress. If true , the operation is completed, and either error or response is available. |
metadata | google.protobuf.Any Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. |
result | oneof: error or response The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true , exactly one of error or response is set. |
error | google.rpc.Status The error result of the operation in case of failure or cancellation. |
response | google.protobuf.Any if operation finished successfully. |
UpdateRouteMetadata
Field | Description |
---|---|
http_router_id | string ID of the HTTP router that the route is being updated in. |
virtual_host_name | string Name of the virtual host that the route is being updated in. |
route_name | string Name of the route that is being updated. |
VirtualHost
Field | Description |
---|---|
name | string Required. Name of the virtual host. The name is unique within the HTTP router. |
authority[] | string List of domains that are attributed to the virtual host. The host is selected to process the request received by the load balancer if the domain specified in the HTTP/1.1 Host header or the HTTP/2 :authority pseudo-header matches a domain specified in the host. A wildcard asterisk character ( * ) matches 0 or more characters. If not specified, all domains are attributed to the host, which is the same as specifying a * value. An HTTP router must not contain more than one virtual host to which all domains are attributed. |
routes[] | Route Routes of the virtual host. A route contains a set of conditions (predicates) that are used by the load balancer to select the route for the request and an action on the request. For details about the concept, see documentation. The order of routes matters: the first route whose predicate matches the request is selected. The most specific routes should be at the top of the list, so that they are not overridden. For example, if the first HTTP route is configured, via HttpRoute.match, to match paths prefixed with just / , other routes are never matched. |
modify_request_headers[] | HeaderModification Deprecated, use route_options.modify_request_headers. |
modify_response_headers[] | HeaderModification Deprecated, use route_options.modify_response_headers. |
route_options | RouteOptions |
Route
Field | Description |
---|---|
name | string Required. Name of the route. |
route | oneof: http or grpc Route configuration. |
http | HttpRoute HTTP route configuration. |
grpc | GrpcRoute gRPC route configuration. |
route_options | RouteOptions |