[Документация Yandex Cloud](../../index.md) > [Yandex Managed Service for Kubernetes](../index.md) > Инструменты Application Load Balancer > Gwin > Конфигурация ресурсов (англ.) > HTTPRoute
# HTTPRoute
HTTPRoute provides a way to route HTTP requests. This includes the capability to match requests by hostname, path, header, or query param. Filters can be used to modify requests, and requests should be routed to backend services.
HTTPRoute is a [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) project resource. Below, we describe its fields and annotations used by Gwin. For details, see the [upstream documentation](https://gateway-api.sigs.k8s.io/reference/spec/#httproute).
HTTPRoute resources must be attached to [Gateway](gateway.md) resources to function properly.
* [Cheatsheet](#cheatsheet)
* [HTTPRouteMeta](#httproutemeta)
* [Annotations cheatsheet](#annotations-cheatsheet)
* [Annotations reference](#annotations-reference)
* [HTTPRouteSpec](#httproutespec)
* [ParentReference](#parentreference)
* [HTTPRouteRule](#httprouterule)
* [HTTPRouteMatch](#httproutematch)
* [HTTPPathMatch](#httppathmatch)
* [HTTPHeaderMatch](#httpheadermatch)
* [HTTPQueryParamMatch](#httpqueryparammatch)
* [HTTPRouteFilter](#httproutefilter)
* [HTTPHeaderFilter](#httpheaderfilter)
* [HTTPRequestRedirectFilter](#httprequestredirectfilter)
* [HTTPPathModifier](#httppathmodifier)
* [ExtensionRef](#extensionref)
* [HTTPBackendRef](#httpbackendref)
* [HTTPRouteTimeouts](#httproutetimeouts)
## Cheatsheet
{% note info %}
Specification provided below is not valid configuration.
It's just demonstration of all `HTTPRoute` fields.
{% endnote %}
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: example-ns
annotations: ... # see annotations example below
spec:
parentRefs: # attach to Gateway resources
- group: gateway.networking.k8s.io
kind: Gateway
namespace: gateway-ns
name: example-gateway
sectionName: http-listener # specific listener name, can be omitted
hostnames: # domains this route handles
- "*.example.com" # wildcard domain
- "api.example.com" # specific subdomain
rules:
- name: api-rule # rule identifier
matches: # conditions for this rule
- path:
type: PathPrefix # match path prefix
value: "/api"
method: GET # HTTP method
headers: # header matching
- name: "X-Version"
value: "v1"
type: Exact # match type: Exact or RegularExpression
- name: "X-User-Agent"
value: "^Mozilla.*"
type: RegularExpression # regex pattern matching
queryParams: # query parameter matching
- name: "version"
value: "v2"
type: Exact # match type: Exact or RegularExpression
- name: "debug"
value: "true|false"
type: RegularExpression # regex pattern matching
filters: # modify requests before routing
- type: RequestHeaderModifier
requestHeaderModifier:
set: # replace header values
- name: "X-Custom-Header"
value: "custom-value"
add: # add new headers
- name: "X-Added-Header"
value: "added-value"
remove: # remove headers
- "X-Remove-Header"
- type: ResponseHeaderModifier # modify response headers
responseHeaderModifier: ... # same as RequestHeaderModifier
- type: RequestRedirect # redirect instead of routing
requestRedirect:
scheme: https # change protocol
hostname: secure.example.com # change host
path:
type: ReplaceFullPath # replace entire path
replaceFullPath: "/v2/api"
port: 443 # change port
statusCode: 301 # HTTP redirect code
- type: ExtensionRef # return a fixed response (no backend needed)
extensionRef:
group: gwin.yandex.cloud
kind: DirectResponse # reference a DirectResponse resource
name: not-found-response
backendRefs: # where to route requests
- group: "" # core Kubernetes API
kind: Service # Kubernetes service
name: api-service
namespace: api-ns
port: 8080
weight: 80 # 80% of traffic
- group: gwin.yandex.cloud # Gwin custom resources
kind: YCStorageBucket # Object Storage bucket
name: static-bucket
weight: 20 # 20% of traffic
timeouts: # request timeouts
backendRequest: "25s" # backend request timeout
```
| Field | Description |
|-------|-------------|
| metadata | **[HTTPRouteMeta](#httproutemeta)**
Name, namespace and annotations. |
| spec | **[HTTPRouteSpec](#httproutespec)**
Resource specification. |
## HTTPRouteMeta
| Field | Description |
|-------|-------------|
| name | **string**
Name of the HTTPRoute. |
| namespace | **string**
Namespace of the HTTPRoute. |
| annotations | **map[string]string**
Annotations of the HTTPRoute. |
### Annotations cheatsheet
{% note info %}
You can also set policy parameters using [RoutePolicy](routepolicy.md) resource. The RoutePolicy resource parameters and HTTPRoute annotations are equivalent.
{% endnote %}
Specification provided below is not valid configuration.
It's just demonstration of all `HTTPRoute` annotations.
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
annotations:
# Backend group configuration
gwin.yandex.cloud/rules.backends.http.useHTTP2: "true" # enable HTTP/2 to backends
gwin.yandex.cloud/rules.backends.balancing.mode: "ROUND_ROBIN" # load balancing algorithm
gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting: "80" # prefer same zone
gwin.yandex.cloud/rules.backends.balancing.strictLocality: "false" # allow cross-zone routing
gwin.yandex.cloud/rules.backends.balancing.panicThreshold: "50" # panic mode threshold
# Health checks
gwin.yandex.cloud/rules.backends.hc.timeout: "5s" # health check timeout
gwin.yandex.cloud/rules.backends.hc.interval: "10s" # check interval
gwin.yandex.cloud/rules.backends.hc.healthyThreshold: "2" # checks to mark healthy
gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold: "3" # checks to mark unhealthy
gwin.yandex.cloud/rules.backends.hc.port: "8080" # health check port
gwin.yandex.cloud/rules.backends.hc.http.path: "/health" # HTTP health check path
gwin.yandex.cloud/rules.backends.hc.http.useHTTP2: "false" # use HTTP/1.1 for checks
gwin.yandex.cloud/rules.backends.hc.http.host: "health.example.com" # Host header
gwin.yandex.cloud/rules.backends.hc.grpc.serviceName: "health.HealthService" # gRPC service
gwin.yandex.cloud/rules.backends.hc.stream.send: "PING" # TCP check data to send
gwin.yandex.cloud/rules.backends.hc.stream.receive: "PONG" # expected TCP response
# Health check transport settings
gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext: "true" # use plaintext for health checks
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni: "health.example.com" # SNI for health check TLS
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id: "health-cert-123" # health check TLS cert ID
gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..." # health check TLS cert PEM
# Backend TLS configuration
gwin.yandex.cloud/rules.backends.tls.sni: "backend.example.com" # SNI for TLS
gwin.yandex.cloud/rules.backends.tls.trustedCA.id: "cert-123456" # cloud certificate ID
gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes: "-----BEGIN CERTIFICATE-----..." # PEM certificate
# Stream backend configuration
gwin.yandex.cloud/rules.backends.stream.enableProxy: "true" # enable proxy protocol
gwin.yandex.cloud/rules.backends.stream.keepConnectionsOnHostHealthFailure: "false" # drop failed connections
# Session affinity
gwin.yandex.cloud/rules.sessionAffinity.header.name: "X-Session-ID" # header-based affinity
gwin.yandex.cloud/rules.sessionAffinity.cookie.name: "session" # cookie name
gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl: "3600s" # cookie lifetime
gwin.yandex.cloud/rules.sessionAffinity.cookie.path: "/app" # cookie path attribute
gwin.yandex.cloud/rules.sessionAffinity.sourceIP: "true" # IP-based affinity
# Route timeouts
gwin.yandex.cloud/rules.timeout: "60s" # overall connection timeout
gwin.yandex.cloud/rules.idleTimeout: "300s" # idle connection timeout
# HTTP specific settings
gwin.yandex.cloud/rules.http.upgradeTypes: "websocket" # supported upgrade protocols
gwin.yandex.cloud/rules.http.regexRewrite.regex: "^/service/([^/]+)(/.*)$" # regex pattern for path rewriting
gwin.yandex.cloud/rules.http.regexRewrite.substitute: "\\2/instance/\\1" # substitution pattern with capture groups
# Host rewriting
gwin.yandex.cloud/rules.hostRewrite.auto: "true" # automatically rewrite host to backend target
gwin.yandex.cloud/rules.hostRewrite.replace: "backend.example.com" # static host replacement
# Security
gwin.yandex.cloud/hosts.securityProfileID: "host-security-profile-1" # Yandex Smart Web Security profile for hosts
# Rate limiting
gwin.yandex.cloud/rules.rateLimit.allRequests.perSecond: "100" # route-level rate limit for all requests
gwin.yandex.cloud/rules.rateLimit.allRequests.perMinute: "6000" # route-level rate limit for all requests
gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perSecond: "10" # route-level rate limit per IP
gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perMinute: "600" # route-level rate limit per IP
gwin.yandex.cloud/hosts.rateLimit.allRequests.perSecond: "100" # host-level rate limit for all requests
gwin.yandex.cloud/hosts.rateLimit.allRequests.perMinute: "6000" # host-level rate limit for all requests
gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perSecond: "10" # host-level rate limit per IP
gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perMinute: "600" # host-level rate limit per IP
# RBAC configuration
gwin.yandex.cloud/rules.rbac.action: "ALLOW" # default RBAC action
gwin.yandex.cloud/rules.rbac.principals.admin.check-token.header.name: "X-Api-Token" # header to check
gwin.yandex.cloud/rules.rbac.principals.admin.check-token.header.exact: "admin123" # required value
gwin.yandex.cloud/rules.rbac.principals.admin.check-ip.ip.remoteIp: "10.0.0.0/8" # allowed IP range
gwin.yandex.cloud/rules.rbac.principals.admin.any.any: "true" # match any request
gwin.yandex.cloud/hosts.rbac.action: "DENY" # host-level RBAC action
# Attach to existing ALB infrastructure
gwin.yandex.cloud/rules.attach.backendGroup.id: "backend-group-id-1" # existing backend group ID
gwin.yandex.cloud/rules.attach.backendGroup.dontUpdatePaths: "name,description" # fields not to update
gwin.yandex.cloud/rules.attach.gatewayClass: "yandex-cloud-gateway" # gateway class filter
# Rule-specific configuration (conflict with global settings is an error)
gwin.yandex.cloud/rule.api-rule.backends.balancing.mode: "LEAST_REQUEST" # per-rule balancing
gwin.yandex.cloud/rule.api-rule.timeout: "30s" # per-rule timeout
gwin.yandex.cloud/rule.api-rule.idleTimeout: "120s" # per-rule idle timeout
gwin.yandex.cloud/rule.api-rule.attach.backendGroup.id: "rule-backend-group-id" # per-rule attach
# ALB resource naming
# Custom names for ALB resources created by the controller.
gwin.yandex.cloud/hosts.albVirtualHostName: "my-virtual-host" # custom virtual host name
gwin.yandex.cloud/rule.api-rule.albRouteName: "my-route" # custom route name for a specific rule
gwin.yandex.cloud/rule.api-rule.albBackendGroupName: "my-backend-group" # custom backend group name
gwin.yandex.cloud/rule.api-rule.backend.0.albBackendName: "my-backend" # custom backend name by index
```
### Annotations reference
#### Backend group configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.http.useHTTP2`
_(boolean)_
Use HTTP/2 for connections between load balancer and backends.
Example: `true` |
| `gwin.yandex.cloud/rules.backends.balancing.mode`
_(string)_
Load balancing mode for backend group. Possible values: `RANDOM`, `ROUND_ROBIN`, `LEAST_REQUEST`, `MAGLEV_HASH`.
Example: `ROUND_ROBIN` |
| `gwin.yandex.cloud/rules.backends.balancing.localityAwareRouting`
_(number)_
Percentage of traffic sent to backends in the same [availability zone](../../overview/concepts/geo-scope.md).
Example: `80` |
| `gwin.yandex.cloud/rules.backends.balancing.strictLocality`
_(boolean)_
Route traffic only to backends in the same [availability zone](../../overview/concepts/geo-scope.md).
Example: `false` |
| `gwin.yandex.cloud/rules.backends.balancing.panicThreshold`
_(number)_
[Panic mode](../../application-load-balancer/concepts/backend-group.md#panic-mode) threshold percentage for load balancing.
Example: `50` |
#### Health check configuration
##### Common health check settings
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.hc.timeout`
_(duration)_
Health check timeout.
Example: `5s` |
| `gwin.yandex.cloud/rules.backends.hc.interval`
_(duration)_
Interval between health checks.
Example: `10s` |
| `gwin.yandex.cloud/rules.backends.hc.healthyThreshold`
_(number)_
Number of successful checks to mark backend as healthy.
Example: `2` |
| `gwin.yandex.cloud/rules.backends.hc.unhealthyThreshold`
_(number)_
Number of failed checks to mark backend as unhealthy.
Example: `3` |
| `gwin.yandex.cloud/rules.backends.hc.port`
_(number)_
Port for health checks.
Example: `8080` |
##### HTTP health checks
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.hc.http.path`
_(string)_
HTTP path for health checks.
Example: `/health` |
| `gwin.yandex.cloud/rules.backends.hc.http.useHTTP2`
_(boolean)_
Use HTTP/2 for health checks.
Example: `false` |
| `gwin.yandex.cloud/rules.backends.hc.http.host`
_(string)_
Host header for HTTP health checks.
Example: `health.example.com` |
##### gRPC health checks
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.hc.grpc.serviceName`
_(string)_
gRPC service name for health checks.
Example: `health.HealthService` |
##### Stream health checks
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.hc.stream.send`
_(string)_
Data to send for TCP health checks.
Example: `PING` |
| `gwin.yandex.cloud/rules.backends.hc.stream.receive`
_(string)_
Expected response for TCP health checks.
Example: `PONG` |
##### Health check transport settings
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.hc.transportSettings.plaintext`
_(boolean)_
Use plaintext protocol for health checks. Set to `true` to force HTTP health checks even for HTTPS backends.
Example: `true` |
| `gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.sni`
_(string)_
Server Name Indication (SNI) for health check TLS connections.
Example: `health.example.com` |
| `gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.id`
_(string)_
Cloud certificate ID for health check TLS validation.
Example: `health-cert-123` |
| `gwin.yandex.cloud/rules.backends.hc.transportSettings.tls.trustedCA.bytes`
_(string)_
X.509 certificate contents in PEM format for health check TLS validation.
Example: `-----BEGIN CERTIFICATE-----...` |
#### Backend TLS configuration
TLS settings for backend connections. \
Use when the load balancer must connect to its targets over TLS. \
If you only need “TLS as is” (no SNI and no backend certificate verification), set `gwin.yandex.cloud/rules.backends.tls.sni: ""`. \
Health check TLS settings work the same way, but are configured separately.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.tls.sni`
_(string)_
Server Name Indication (SNI) for TLS connections to backends.
Example: `backend.example.com` |
| `gwin.yandex.cloud/rules.backends.tls.trustedCA.id`
_(string)_
Cloud certificate ID for backend TLS validation.
Example: `cert-123456` |
| `gwin.yandex.cloud/rules.backends.tls.trustedCA.bytes`
_(string)_
X.509 certificate contents in PEM format for backend TLS validation.
Example: `-----BEGIN CERTIFICATE-----...` |
#### Stream backend configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.backends.stream.enableProxy`
_(boolean)_
Enable proxy protocol for stream backends.
Example: `true` |
| `gwin.yandex.cloud/rules.backends.stream.keepConnectionsOnHostHealthFailure`
_(boolean)_
Keep connections when backend host becomes unhealthy.
Example: `false` |
#### Session affinity
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.sessionAffinity.header.name`
_(string)_
HTTP header name for session affinity.
Example: `X-Session-ID` |
| `gwin.yandex.cloud/rules.sessionAffinity.cookie.name`
_(string)_
Cookie name for session affinity.
Example: `session` |
| `gwin.yandex.cloud/rules.sessionAffinity.cookie.ttl`
_(duration)_
Cookie TTL for session affinity.
Example: `3600s` |
| `gwin.yandex.cloud/rules.sessionAffinity.cookie.path`
_(string)_
Path attribute for the generated session cookie. If unspecified or empty, no path is set for the cookie.
Example: `/app` |
| `gwin.yandex.cloud/rules.sessionAffinity.sourceIP`
_(boolean)_
Use source IP for session affinity.
Example: `true` |
#### Route configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.timeout`
_(duration)_
Overall timeout for HTTP connection between load balancer and backend. The maximum time the connection is kept alive, regardless of data transfer. Default: 60s. On timeout, returns UNAVAILABLE status. _NOTE_: In HTTPRoute you can use rules[].timeouts.backendRequest field instead, it overrides annotation value.
Example: `60s` |
| `gwin.yandex.cloud/rules.idleTimeout`
_(duration)_
Idle timeout for HTTP connection.
Example: `300s` |
| `gwin.yandex.cloud/rules.http.upgradeTypes`
_(comma separated strings)_
Supported HTTP Upgrade header values.
Example: `websocket` |
#### Route rate limiting
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.rateLimit.allRequests.perSecond`
_(number)_
Route-level rate limit for all requests per second.
Example: `100` |
| `gwin.yandex.cloud/rules.rateLimit.allRequests.perMinute`
_(number)_
Route-level rate limit for all requests per minute.
Example: `6000` |
| `gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perSecond`
_(number)_
Route-level rate limit per IP address per second.
Example: `10` |
| `gwin.yandex.cloud/rules.rateLimit.requestsPerIP.perMinute`
_(number)_
Route-level rate limit per IP address per minute.
Example: `600` |
#### Host rewriting
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.hostRewrite.auto`
_(boolean)_
Automatically replaces the host with that of the target backend. Cannot be used together with `hostRewrite.replace`.
Example: `true` |
| `gwin.yandex.cloud/rules.hostRewrite.replace`
_(string)_
Static host replacement value for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers. Cannot be used together with `hostRewrite.auto`.
Example: `backend.example.com` |
#### Path rewriting
`regexRewrite` rewrites the request path before forwarding to the backend.
**Example: match several paths by regex and add a prefix**
```yaml
metadata:
annotations:
# /foo/... → /v2/foo/..., /bar/... → /v2/bar/...
gwin.yandex.cloud/rule.my-rule.http.regexRewrite.regex: "^((/foo|/bar).*)$"
gwin.yandex.cloud/rule.my-rule.http.regexRewrite.substitute: "/v2\\1"
spec:
rules:
- name: my-rule
matches:
- path:
type: RegularExpression
value: "(/foo|/bar).*"
backendRefs:
- name: example-service
port: 8080
```
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.http.regexRewrite.regex`
_(string)_
Regular expression pattern to match portions of the path for rewriting. Used together with `regexRewrite.substitute`.
Example: `^/service/([^/]+)(/.*)$` |
| `gwin.yandex.cloud/rules.http.regexRewrite.substitute`
_(string)_
Substitution string for path rewriting with capture group support. Pattern `^/service/([^/]+)(/.*)$` with substitution `\\2/instance/\\1` transforms `/service/foo/v1/api` to `/v1/api/instance/foo`.
Example: `\\2/instance/\\1` |
#### Security configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/hosts.securityProfileID`
_(string)_
[Security profile](../../smartwebsecurity/index.md) ID for host-level protection.
Example: `host-security-profile-1` |
#### Rate limiting
| Annotation and description |
|------------|
| `gwin.yandex.cloud/hosts.rateLimit.allRequests.perSecond`
_(number)_
Rate limit for all requests per second.
Example: `100` |
| `gwin.yandex.cloud/hosts.rateLimit.allRequests.perMinute`
_(number)_
Rate limit for all requests per minute.
Example: `6000` |
| `gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perSecond`
_(number)_
Rate limit per IP address per second.
Example: `10` |
| `gwin.yandex.cloud/hosts.rateLimit.requestsPerIP.perMinute`
_(number)_
Rate limit per IP address per minute.
Example: `600` |
#### RBAC configuration
RBAC allows controlling access to routes or hosts based on request attributes.
Annotations follow the pattern:
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.{rule-type}`
Where:
* `{resource}` — resource type (`rules`, `hosts`);
* `{principal-group}` — logical group of checks (e.g. `admin`);
* `{principal}` — specific principal identifier (e.g. `check-token`);
* `{rule-type}` — matching rule type (`header`, `ip`, etc.).
##### Combination Rules
* All checks within the same principal group are combined with AND logic.
* Different principal groups are combined with OR logic.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.rbac.action`
_(string)_
Action when principals match (ALLOW/DENY) for route access control.
Example: `ALLOW` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.name`
_(string)_
Header name to match for route RBAC.
Example: `X-Api-Token` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.exact`
_(string)_
Exact header value match for route RBAC.
Example: `admin123` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.regex`
_(string)_
Regex pattern for header value match for route RBAC.
Example: `^admin.*` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.header.prefix`
_(string)_
Header value prefix match for route RBAC.
Example: `Bearer ` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.ip.remoteIp`
_(string)_
IP address or CIDR block for route RBAC.
Example: `10.0.0.0/8` |
| `gwin.yandex.cloud/rules.rbac.principals.{group}.{principal}.any`
_(boolean)_
Match any request for route RBAC.
Example: `true` |
| `gwin.yandex.cloud/hosts.rbac.action`
_(string)_
Action when principals match (ALLOW/DENY) for host access control.
Example: `DENY` |
#### Attach Configuration
{% note info %}
Attach configuration applies to individual route rules, not the entire HTTPRoute resource. Each rule can be attached to a different existing backend group.
{% endnote %}
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.attach.backendGroup.id`
_(string)_
Cloud backend group ID that should be managed by this route rule. The controller will attach to this existing backend group instead of creating a new one.
Example: `backend-group-id-1` |
| `gwin.yandex.cloud/rules.attach.backendGroup.dontUpdatePaths`
_(string list)_
Specifies which fields should NOT be updated by the controller. Default is "name" - the controller doesn't touch the group name.
Example: `name,description`, `none` |
| `gwin.yandex.cloud/rules.attach.gatewayClass`
_(string)_
Specifies the gateway class that should manage this route rule. If specified and the corresponding gatewayClass is not managed by the controller, the route rule is ignored. This is useful for advanced scenarios where multiple controllers might be present.
Example: `yandex-cloud-gateway` |
#### Rule-specific configuration
{% note info %}
Any `rules` option can be applied to a specific rule by prefixing with `rule.{rule-name}`.
For example: `gwin.yandex.cloud/rule.api-rule.backends.balancing.mode: "LEAST_REQUEST"`.
{% endnote %}
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rule.{rule-name}.backends.balancing.mode`
_(string)_
Load balancing mode for specific rule.
Example: `LEAST_REQUEST` |
| `gwin.yandex.cloud/rule.{rule-name}.timeout`
_(duration)_
Timeout for specific rule.
Example: `30s` |
| `gwin.yandex.cloud/rule.{rule-name}.idleTimeout`
_(duration)_
Idle timeout for specific rule.
Example: `120s` |
| `gwin.yandex.cloud/rule.{rule-name}.attach.backendGroup.id`
_(string)_
Cloud backend group ID for specific rule attachment.
Example: `backend-group-id-1` |
#### Per-backend configuration by index
{% note info %}
Any `rules.backends` option can be applied to a specific backend within a rule by using `rule.{rule-name}.backend.{index}`, where `{index}` is the zero-based position of the backend in the rule's `backendRefs` list.
For example: `gwin.yandex.cloud/rule.api-rule.backend.0.tls.sni: "backend-0.example.com"`.
{% endnote %}
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rule.{rule-name}.backend.{index}.tls.sni`
_(string)_
SNI for TLS connections to the specific backend.
Example: `backend-0.example.com` |
| `gwin.yandex.cloud/rule.{rule-name}.backend.{index}.hc.http.path`
_(string)_
HTTP health check path for the specific backend.
Example: `/healthz` |
#### ALB resource naming
Custom names for ALB resources created by the controller. By default, the controller generates names automatically.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/hosts.albVirtualHostName`
_(string)_
Custom name for the ALB virtual host.
Example: `my-virtual-host` |
| `gwin.yandex.cloud/rule.{rule-name}.albRouteName`
_(string)_
Custom name for the ALB route for the specified rule.
Example: `my-route` |
| `gwin.yandex.cloud/rule.{rule-name}.albBackendGroupName`
_(string)_
Custom name for the ALB backend group for the specified rule.
Example: `my-backend-group` |
| `gwin.yandex.cloud/rule.{rule-name}.backend.{index}.albBackendName`
_(string)_
Custom name for the ALB backend at the specified zero-based index within the rule's `backendRefs`.
Example: `my-backend` |
For the target group name, see [`gwin.yandex.cloud/albTargetGroupName`](service.md) on the Service resource.
## HTTPRouteSpec
HTTPRoute specification defines the desired state of HTTPRoute.
*Appears in*: [HTTPRoute](#httproute)
| Field | Description |
|-------|-------------|
| parentRefs | **[]ParentReference**
References to Gateway resources that this HTTPRoute should attach to. |
| hostnames | **[]string**
Hostnames that should match against the HTTP Host header. |
| rules | **[[]HTTPRouteRule](#httprouterule)**
Rules for routing HTTP requests. |
### ParentReference
Reference to a Gateway resource that this route should attach to.
*Appears in*: [HTTPRouteSpec](#httproutespec)
| Field | Description |
|-------|-------------|
| group | **string**
API group of the parent resource.
Example: `gateway.networking.k8s.io` |
| kind | **string**
Kind of the parent resource.
Example: `Gateway` |
| namespace | **string**
Namespace of the parent resource.
Example: `gateway-ns` |
| name | **string**
Name of the parent resource.
Example: `example-gateway` |
| sectionName | **string**
Name of the specific listener to attach to.
Example: `http-listener` |
| port | **int32**
Port number of the listener to attach to.
Example: `80` |
### HTTPRouteRule
HTTPRouteRule defines semantics for matching an HTTP request based on conditions (matches), processing it (filters), and forwarding the request to an API object (backendRefs).
*Appears in*: [HTTPRouteSpec](#httproutespec)
| Field | Description |
|-------|-------------|
| name | **string**
Name of the route rule. Must be unique within a Route if set.
Example: `api-rule` |
| matches | **[[]HTTPRouteMatch](#httproutematch)**
Conditions required for a request to match this rule. |
| filters | **[[]HTTPRouteFilter](#httproutefilter)**
Filters to modify requests before forwarding to backends. |
| backendRefs | **[[]HTTPBackendRef](#httpbackendref)**
Backend services to route requests to. |
| timeouts | **[HTTPRouteTimeouts](#httproutetimeouts)**
Timeout configuration for this rule. |
### HTTPRouteMatch
HTTPRouteMatch defines the predicate used to match requests to a given action. Multiple match types are ANDed together.
*Appears in*: [HTTPRouteRule](#httprouterule)
| Field | Description |
|-------|-------------|
| path | **[HTTPPathMatch](#httppathmatch)**
HTTP request path matcher. |
| headers | **[[]HTTPHeaderMatch](#httpheadermatch)**
HTTP request header matchers. |
| queryParams | **[[]HTTPQueryParamMatch](#httpqueryparammatch)**
HTTP query parameter matchers. |
| method | **string**
HTTP method to match.
Example: `GET`, `POST`, `PUT`. |
### HTTPPathMatch
HTTPPathMatch describes how to select a HTTP route by matching the HTTP request path.
*Appears in*: [HTTPRouteMatch](#httproutematch)
| Field | Description |
|-------|-------------|
| type | **string**
Path match type. `Exact` for exact path match, `PathPrefix` for path prefix match, `RegularExpression` for regex pattern match.
Example: `Exact`, `PathPrefix`, `RegularExpression`. |
| value | **string**
Path value to match against. For `RegularExpression` type, this should be a valid RE2 regex pattern.
Example: `/api/v1`, `/`, `/api/.*`, `(/qr-pay\|/prepay).*`. |
### HTTPHeaderMatch
HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request headers.
*Appears in*: [HTTPRouteMatch](#httproutematch)
| Field | Description |
|-------|-------------|
| type | **string**
Type specifies how to match against the value of the header. `Exact` for exact header value match, `RegularExpression` for regex pattern match.
Example: `Exact`, `RegularExpression`. |
| name | **string**
Name of the HTTP Header to be matched. Name matching is case insensitive.
Example: `X-Version`, `Authorization`. |
| value | **string**
Value of HTTP Header to be matched. For `RegularExpression` type, this should be a valid regex pattern.
Example: `v1`, `^Bearer .*`. |
### HTTPQueryParamMatch
HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP query parameters.
*Appears in*: [HTTPRouteMatch](#httproutematch)
| Field | Description |
|-------|-------------|
| type | **string**
Type specifies how to match against the value of the query parameter. `Exact` for exact parameter value match, `RegularExpression` for regex pattern match.
Example: `Exact`, `RegularExpression`. |
| name | **string**
Name of the HTTP query param to be matched. This must be an exact string match.
Example: `version`, `debug`. |
| value | **string**
Value of HTTP query param to be matched. For `RegularExpression` type, this should be a valid regex pattern.
Example: `v2`, `true|false`. |
### HTTPRouteFilter
HTTPRouteFilter defines processing steps that must be completed during the request or response lifecycle.
*Appears in*: [HTTPRouteRule](#httprouterule), [HTTPBackendRef](#httpbackendref)
| Field | Description |
|-------|-------------|
| type | **string**
Filter type. Supported: `RequestHeaderModifier`, `ResponseHeaderModifier`, `RequestRedirect`, `URLRewrite`, `ExtensionRef`.
Example: `RequestHeaderModifier` |
| requestHeaderModifier | **[HTTPHeaderFilter](#httpheaderfilter)**
Request header modification configuration. |
| responseHeaderModifier | **[HTTPHeaderFilter](#httpheaderfilter)**
Response header modification configuration. |
| requestRedirect | **[HTTPRequestRedirectFilter](#httprequestredirectfilter)**
Request redirect configuration. |
| urlRewrite | **HTTPURLRewriteFilter**
URL rewrite configuration. |
| extensionRef | **[ExtensionRef](#extensionref)**
Extension filter configuration. Used with `type: ExtensionRef`. |
### HTTPHeaderFilter
HTTPHeaderFilter defines configuration for header modification filters (both RequestHeaderModifier and ResponseHeaderModifier).
*Appears in*: [HTTPRouteFilter](#httproutefilter)
| Field | Description |
|-------|-------------|
| set | **[]HTTPHeader**
Headers to set, replacing any existing values. |
| add | **[]HTTPHeader**
Headers to add to the request/response. |
| remove | **[]string**
Header names to remove from the request/response. |
### HTTPRequestRedirectFilter
HTTPRequestRedirectFilter defines configuration for the RequestRedirect filter.
*Appears in*: [HTTPRouteFilter](#httproutefilter)
| Field | Description |
|-------|-------------|
| scheme | **string**
Scheme to redirect to.
Example: `https` |
| hostname | **string**
Hostname to redirect to.
Example: `secure.example.com` |
| path | **[HTTPPathModifier](#httppathmodifier)**
Path modification for redirect. |
| port | **int32**
Port to redirect to.
Example: `443` |
| statusCode | **int**
HTTP status code for redirect.
Example: `301`, `302`. |
### HTTPPathModifier
HTTPPathModifier defines configuration for path modification in redirects.
*Appears in*: [HTTPRequestRedirectFilter](#httprequestredirectfilter)
| Field | Description |
|-------|-------------|
| type | **string**
Path modification type. `ReplaceFullPath` or `ReplacePrefixMatch`.
Example: `ReplaceFullPath` |
| replaceFullPath | **string**
Complete path replacement.
Example: `/v2/api` |
| replacePrefixMatch | **string**
Path prefix replacement. Only valid when the rule has exactly one `PathPrefix` match. Cannot be used with `RegularExpression` path matches — use the [`regexRewrite` annotation](#path-rewriting) instead.
Example: `/api/v2` |
### ExtensionRef
ExtensionRef identifies a Gwin-specific extension resource used as a filter. Currently the only supported extension is [`DirectResponse`](directresponse.md), which instructs the load balancer to return a fixed HTTP response without forwarding to any backend.
*Appears in*: [HTTPRouteFilter](#httproutefilter)
| Field | Description |
|-------|-------------|
| group | **string**
API group of the extension resource.
Example: `gwin.yandex.cloud` |
| kind | **string**
Kind of the extension resource.
Example: `DirectResponse` |
| name | **string**
Name of the extension resource. Must be in the same namespace as the HTTPRoute.
Example: `not-found-response` |
### HTTPBackendRef
HTTPBackendRef defines how an HTTPRoute forwards an HTTP request.
[`Service`](service.md) or [`YCStorageBucket`](ycstoragebucket.md) can be used as a backend.
*Appears in*: [HTTPRouteRule](#httprouterule)
| Field | Description |
|-------|-------------|
| group | **string**
API group of the backend resource.
Example: `""`, `gwin.yandex.cloud`. |
| kind | **string**
Kind of the backend resource.
Example: `Service`, `YCStorageBucket`. |
| name | **string**
Name of the backend resource.
Example: `api-service` |
| namespace | **string**
Namespace of the backend resource.
Example: `api-ns` |
| port | **int32**
Port of the backend service (for `Service` kind only).
Example: `8080` |
| weight | **int32**
Weight for traffic distribution between backends.
Example: `80` |
### HTTPRouteTimeouts
HTTPRouteTimeouts defines timeouts that can be configured for an HTTPRoute.
*Appears in*: [HTTPRouteRule](#httprouterule)
| Field | Description |
|-------|-------------|
| backendRequest | **string**
Maximum duration for a request from balancer to a backend.
Example: `25s` |