Application Load Balancer API, REST: HttpRouter.List

Field

Description

folderId

string

Required field. ID of the folder to list HTTP routers in.

To get the folder ID, make a yandex.cloud.resourcemanager.v1.FolderService.List request.

pageSize

string (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 ListHttpRoutersResponse.nextPageToken
that can be used to get the next page of results in subsequent list requests.
Default value: 100.

pageToken

string

Page token. To get the next page of results, set page_token to the
ListHttpRoutersResponse.nextPageToken returned by a previous list request.

filter

string

A filter expression that filters HTTP routers listed in the response.

The expression must specify:

1. The field name. Currently you can use filtering only on HttpRouter.name field.
2. An = operator.
3. The value in double quotes ("). Must be 3-63 characters long and match the regular expression [a-z][-a-z0-9]{1,61}[a-z0-9].
   Example of a filter: name=my-http-router.

Field

Description

httpRouters[]

HttpRouter

List of HTTP routers in the specified folder.

nextPageToken

string

Token for getting the next page of the list. If the number of results is greater than
the specified ListHttpRoutersRequest.pageSize, use next_page_token as the value
for the ListHttpRoutersRequest.pageToken parameter in the next list request.

Each subsequent page will have its own next_page_token to continue paging through the results.

Field

Description

id

string

ID of the router. Generated at creation time.

name

string

Name of the router. The name is unique within the folder.

description

string

Description of the router.

folderId

string

ID of the folder that the router belongs to.

labels

object (map<string, string>)

Router labels as key:value pairs.
For details about the concept, see documentation.

virtualHosts[]

VirtualHost

Virtual hosts that combine routes inside the router.
For details about the concept, see documentation.

Only one virtual host with no authority (default match) can be specified.

createdAt

string (date-time)

Creation timestamp.

String in RFC3339 text format. The range of possible values is from
0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the
Protocol Buffers reference.
In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).

routeOptions

RouteOptions

Field

Description

name

string

Required field. 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.

modifyRequestHeaders[]

HeaderModification

Deprecated, use route_options.modify_request_headers.

modifyResponseHeaders[]

HeaderModification

Deprecated, use route_options.modify_response_headers.

routeOptions

RouteOptions

rateLimit

RateLimit

RateLimit is a rate limit configuration applied for a whole virtual host.

Field

Description

name

string

Required field. Name of the route.

http

HttpRoute

HTTP route configuration.

Includes only one of the fields http, grpc.

Route configuration.

grpc

GrpcRoute

gRPC route configuration.

Includes only one of the fields http, grpc.

Route configuration.

routeOptions

RouteOptions

Field

Description

match

HttpRouteMatch

Condition (predicate) used to select the route.

route

HttpRouteAction

Forwards the request to a backend group for processing as configured.

Includes only one of the fields route, redirect, directResponse.

Action performed on the request if the route is selected.

redirect

RedirectAction

Redirects the request as configured.

Includes only one of the fields route, redirect, directResponse.

Action performed on the request if the route is selected.

directResponse

DirectResponseAction

Instructs the load balancer to respond directly as configured.

Includes only one of the fields route, redirect, directResponse.

Action performed on the request if the route is selected.

Field

Description

httpMethod[]

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.

Field

Description

exactMatch

string

Exact match string.

Includes only one of the fields exactMatch, prefixMatch, regexMatch.

Match string for either exact or prefix match.

prefixMatch

string

Prefix match string.

Includes only one of the fields exactMatch, prefixMatch, regexMatch.

Match string for either exact or prefix match.

regexMatch

string

Regular expression match string.

Includes only one of the fields exactMatch, prefixMatch, regexMatch.

Match string for either exact or prefix match.

Field

Description

backendGroupId

string

Required field. Backend group to forward requests to.

Stream (TCP) backend groups are not supported.

timeout

string (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.

idleTimeout

string (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).

hostRewrite

string

Host replacement.

Includes only one of the fields hostRewrite, autoHostRewrite.

Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers.

If not specified, the host is not changed.

autoHostRewrite

boolean

Automatically replaces the host with that of the target.

Includes only one of the fields hostRewrite, autoHostRewrite.

Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers.

If not specified, the host is not changed.

prefixRewrite

string

Replacement for the path prefix matched by StringMatch.

For instance, if StringMatch.prefixMatch value is /foo and prefix_rewrite value is /bar,
a request with /foobaz path is forwarded with /barbaz path.
For StringMatch.exactMatch, the whole path is replaced.

If not specified, the path is not changed.

upgradeTypes[]

string

Supported values for HTTP Upgrade header. E.g. websocket.

rateLimit

RateLimit

RateLimit is a rate limit configuration applied for route.

Field

Description

allRequests

Limit

AllRequests is a rate limit configuration applied to all incoming requests.

requestsPerIp

Limit

RequestsPerIp is a rate limit configuration applied separately for each set of requests
grouped by client IP address.

Field

Description

perSecond

string (int64)

PerSecond is a limit value specified with per second time unit.

Includes only one of the fields perSecond, perMinute.

perMinute

string (int64)

PerMinute is a limit value specified with per minute time unit.

Includes only one of the fields perSecond, perMinute.

Field

Description

replaceScheme

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.

replaceHost

string

URI host replacement.

If not specified, the original host is used.

replacePort

string (int64)

URI host replacement.

If not specified, the original host is used.

replacePath

string

Replacement for the whole path.

Includes only one of the fields replacePath, replacePrefix.

URI path replacement.

If not specified, the original path is used.

replacePrefix

string

Replacement for the path prefix matched by StringMatch.

For instance, if StringMatch.prefixMatch 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.exactMatch, the whole path is replaced.

Includes only one of the fields replacePath, replacePrefix.

URI path replacement.

If not specified, the original path is used.

removeQuery

boolean

Removes URI query.

responseCode

enum (RedirectResponseCode)

HTTP status code to use in redirect responses.

• MOVED_PERMANENTLY: 301 Moved Permanently status code.
• FOUND: 302 Found status code.
• SEE_OTHER: 303 See Other status code.
• TEMPORARY_REDIRECT: 307 Temporary Redirect status code.
• PERMANENT_REDIRECT: 308 Permanent Redirect status code.

Field

Description

status

string (int64)

HTTP status code to use in responses.

body

Payload

Response body.

Field

Description

text

string

Payload text.

Includes only one of the fields text.

Payload.

Field

Description

match

GrpcRouteMatch

Condition (predicate) used to select the route.

route

GrpcRouteAction

Forwards the request to a backend group for processing as configured.

Includes only one of the fields route, statusResponse.

Action performed on the request if the route is selected.

statusResponse

GrpcStatusResponseAction

Instructs the load balancer to respond directly with a specified status.

Includes only one of the fields route, statusResponse.

Action performed on the request if the route is selected.

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.

Field

Description

backendGroupId

string

Required field. Backend group to forward requests to.

maxTimeout

string (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.

idleTimeout

string (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 maxTimeout 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 maxTimeout).

hostRewrite

string

Host replacement.

Includes only one of the fields hostRewrite, autoHostRewrite.

Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers.

If not specified, the host is not changed.

autoHostRewrite

boolean

Automatically replaces the host with that of the target.

Includes only one of the fields hostRewrite, autoHostRewrite.

Value rewrite settings for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers.

If not specified, the host is not changed.

rateLimit

RateLimit

RateLimit is a rate limit configuration applied for route.

Field

Description

status

enum (Status)

gRPC status code to use in responses.

• OK: OK (0) status code.
• INVALID_ARGUMENT: INVALID_ARGUMENT (3) status code.
• NOT_FOUND: NOT_FOUND (5) status code.
• PERMISSION_DENIED: PERMISSION_DENIED (7) status code.
• UNAUTHENTICATED: UNAUTHENTICATED (16) status code.
• UNIMPLEMENTED: UNIMPLEMENTED (12) status code.
• INTERNAL: INTERNAL (13) status code.
• UNAVAILABLE: UNAVAILABLE (14) status code.

Field

Description

modifyRequestHeaders[]

HeaderModification

Apply the following modifications to the request headers.

modifyResponseHeaders[]

HeaderModification

Apply the following modifications to the response headers.

rbac

RBAC

securityProfileId

string

Security profile that will take effect to all requests routed via particular virtual host.

Field

Description

name

string

Name of the header.

append

string

Appends the specified string to the header value.

Variables defined for Envoy proxy
are supported.

Includes only one of the fields append, replace, remove, rename.

Operation to perform on the header.

replace

string

Replaces the value of the header with the specified string.

Variables defined for Envoy proxy
are supported.

Includes only one of the fields append, replace, remove, rename.

Operation to perform on the header.

remove

boolean

Removes the header.

Includes only one of the fields append, replace, remove, rename.

Operation to perform on the header.

rename

string

Replaces the name of the header with the specified string.
This operation is only supported for ALB Virtual Hosts.

Includes only one of the fields append, replace, remove, rename.

Operation to perform on the header.

Field

Description

action

enum (Action)

Required field. The action to take if a principal matches. Every action either allows or denies a request.

• ACTION_UNSPECIFIED
• ALLOW: Allows the request if and only if there is a principal that matches the request.
• DENY: Allows the request if and only if there are no principal that match the request.

principals[]

Principals

Required. A match occurs when at least one matches the request.

Field

Description

andPrincipals[]

Principal

Required. A match occurs when all principals match the request.

Field

Description

header

HeaderMatcher

A header (or pseudo-header such as :path or :method) of the incoming HTTP request.

Includes only one of the fields header, remoteIp, any.

remoteIp

string

A CIDR block or IP that describes the request remote/origin address, e.g. 192.0.0.0/24 or192.0.0.4 .

Includes only one of the fields header, remoteIp, any.

any

boolean

When any is set, it matches any request.

Includes only one of the fields header, remoteIp, any.

Field

Description

name

string

Required field. 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.