[Документация Yandex Cloud](../../index.md) > [Yandex Application Load Balancer](../index.md) > Инструменты для Managed Service for Kubernetes > Gwin > Конфигурация ресурсов (англ.) > Ingress
# Ingress
Ingress manages external access to services in a cluster, typically HTTP. Gwin extends the standard Kubernetes Ingress resource with custom annotations for Yandex Application Load Balancer features.
Ingress is a standard [Kubernetes](https://kubernetes.io/docs/concepts/services-networking/ingress/) resource. Below, we describe its fields and annotations used by Gwin. For configuration details, see the [upstream documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
{% note info %}
Ingress is frozen. New features are being added to the [Gateway API](https://gateway-api.sigs.k8s.io/). See [k8s docs](https://kubernetes.io/docs/concepts/services-networking/ingress/) for details. Yandex Cloud docs for Gateway API are available [here](gateway.md).
{% endnote %}
* [Cheatsheet](#cheatsheet)
* [IngressMeta](#ingressmeta)
* [Annotations cheatsheet](#annotations-cheatsheet)
* [Annotations reference](#annotations-reference)
* [IngressSpec](#ingressspec)
* [IngressRule](#ingressrule)
* [HTTPIngressRuleValue](#httpingressrulevalue)
* [HTTPIngressPath](#httpingresspath)
* [IngressBackend](#ingressbackend)
* [TypedLocalObjectReference](#typedlocalobjectreference)
* [IngressServiceBackend](#ingressservicebackend)
* [ServiceBackendPort](#servicebackendport)
* [IngressTLS](#ingresstls)
## Cheatsheet
{% note info %}
Specification provided below is not valid configuration.
It's just demonstration of all `Ingress` fields.
{% endnote %}
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
namespace: example-ns
annotations:
# `groupName` is required.
gwin.yandex.cloud/groupName: "my-ingress-group" # group multiple ingresses to single Balancer
# Either `externalIPv4Address` or `internalIPv4Address` is required.
gwin.yandex.cloud/externalIPv4Address: "auto" # external IPv4 address
gwin.yandex.cloud/internalIPv4Address: "subnet-id-1/10.1.1.1" # IPv4 address inside VPC subnet
# Alternatively, you can use IngressPolicy to configure required parameters
... # see annotations reference below
spec:
ingressClassName: gwin-default # use Gwin ingress class
defaultBackend: # default backend for unmatched requests
service:
name: default-service
port:
number: 80
rules:
- host: "example.com" # hostname to match
http:
paths:
- path: "/api" # path to match
pathType: Prefix # path matching type
backend:
service:
name: api-service
port:
number: 8080
- path: "/static"
pathType: Prefix
backend:
resource: # custom backend resource
apiGroup: gwin.yandex.cloud
kind: IngressBackendGroup
name: static-backend-group
- path: "/regex.*" # regex path matching
pathType: ImplementationSpecific # enables regex matching
backend:
service:
name: regex-service
port:
number: 8080
- path: "/redirect"
pathType: Prefix
backend:
resource: # redirect backend
kind: Redirect
name: example-redirect
- path: "/direct"
pathType: Prefix
backend:
resource: # direct response backend
kind: DirectResponse
name: example-response
tls:
- hosts:
- "example.com"
secretName: "yc-certmgr-cert-id-fpq6gvvm6piu********" # Yandex Cloud certificate
```
| Field | Description |
|-------|-------------|
| metadata | **[IngressMeta](#ingressmeta)**
Name, namespace and annotations. |
| spec | **[IngressSpec](#ingressspec)**
Resource specification. |
## IngressMeta
| Field | Description |
|-------|-------------|
| name | **string**
Name of the Ingress. |
| namespace | **string**
Namespace of the Ingress. |
| annotations | **map[string]string**
Annotations of the Ingress. |
### Annotations cheatsheet
{% note info %}
You can also set policy parameters using [IngressPolicy](ingresspolicy.md) resource. The IngressPolicy resource parameters and Ingress annotations are equivalent.
{% endnote %}
Specification provided below is not valid configuration. It's just demonstration of all `Ingress` annotations.
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
# Ingress group configuration
# `groupName` is required.
gwin.yandex.cloud/groupName: "my-ingress-group" # group multiple ingresses to single Balancer
gwin.yandex.cloud/groupOrder: "100" # processing order within group
# Either `externalIPv4Address` or `internalIPv4Address` is required.
gwin.yandex.cloud/externalIPv4Address: "5.4.3.2" # external IPv4 address
gwin.yandex.cloud/internalIPv4Address: "subnet-id-1/auto" # IPv4 address inside VPC subnet
# Alternatively, you can use IngressPolicy to configure required parameters
gwin.yandex.cloud/subnets: "subnet-id-1,subnet-id-2" # where to place balancer
gwin.yandex.cloud/securityGroups: "sg-id-1,sg-id-2" # network access control
gwin.yandex.cloud/allowZonalShift: "true" # enable failover between zones
# Cloud Logging
gwin.yandex.cloud/logs.logGroupID: "log-group-id-1" # where to send logs
gwin.yandex.cloud/logs.disable: "false" # enable logging
gwin.yandex.cloud/logs.discardRule.rule1.httpCodes: "404,500" # skip these status codes
gwin.yandex.cloud/logs.discardRule.rule1.httpCodeIntervals: "HTTP_4XX,HTTP_5XX" # skip error ranges
gwin.yandex.cloud/logs.discardRule.rule1.grpcCodes: "INTERNAL,UNIMPLEMENTED" # skip gRPC errors
gwin.yandex.cloud/logs.discardRule.rule1.discardPercent: "10" # drop 10% of logs
# Autoscaling
gwin.yandex.cloud/autoScale.minZoneSize: "2" # min instances per zone
gwin.yandex.cloud/autoScale.maxSize: "10" # max total instances
# Zone traffic control
gwin.yandex.cloud/zone.ru-central1-a.receiveTraffic: "false" # disable this zone
gwin.yandex.cloud/zone.ru-central1-b.receiveTraffic: "true" # enable this zone
# Listener configuration
gwin.yandex.cloud/listeners.rbac.action: "ALLOW" # access control policy
gwin.yandex.cloud/listeners.http.protocolSettings.allowHTTP10: "true" # support old HTTP
gwin.yandex.cloud/listeners.http.protocolSettings.http2Options.maxConcurrentStreams: "100" # limit connections
gwin.yandex.cloud/listeners.stream.idleTimeout: "300s" # close idle connections
# 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.host: "health.example.com" # Host header
# 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
# 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.allowedMethods: "GET,POST,PUT" # restrict allowed HTTP methods
gwin.yandex.cloud/rules.prefixRewrite: "/new-prefix" # rewrite URL path prefix
# Header modifications
gwin.yandex.cloud/rules.modifyRequestHeaders.append.X-Custom-Header: "custom-value" # add request header
gwin.yandex.cloud/rules.modifyRequestHeaders.rename.Old-Header: "New-Header" # rename request header
gwin.yandex.cloud/rules.modifyRequestHeaders.replace.Authorization: "Bearer token" # replace request header
gwin.yandex.cloud/rules.modifyRequestHeaders.remove: "X-Remove-Me,X-Also-Remove" # remove request headers
gwin.yandex.cloud/rules.modifyResponseHeaders.append.X-Response-Header: "response-value" # add response header
gwin.yandex.cloud/rules.modifyResponseHeaders.rename.Old-Response: "New-Response" # rename response header
gwin.yandex.cloud/rules.modifyResponseHeaders.replace.Cache-Control: "no-cache" # replace response header
gwin.yandex.cloud/rules.modifyResponseHeaders.remove: "Server,X-Powered-By" # remove response headers
# Redirect actions (referenced by backend resource)
gwin.yandex.cloud/redirect.my-redirect.replaceScheme: "https" # change URL scheme
gwin.yandex.cloud/redirect.my-redirect.replaceHost: "new-host.com" # change hostname
gwin.yandex.cloud/redirect.my-redirect.replacePort: "443" # change port
gwin.yandex.cloud/redirect.my-redirect.path.replacePath: "/new-path" # replace entire path
gwin.yandex.cloud/redirect.my-redirect.path.replacePrefix: "/new-prefix" # replace path prefix
gwin.yandex.cloud/redirect.my-redirect.removeQuery: "true" # remove query parameters
gwin.yandex.cloud/redirect.my-redirect.responseCode: "301" # redirect status code
# Direct response actions (referenced by backend resource)
gwin.yandex.cloud/directResponse.my-response.responseCode: "200" # HTTP status code
gwin.yandex.cloud/directResponse.my-response.responseBody.text: "Hello World" # response body text
# Security
gwin.yandex.cloud/hosts.securityProfileID: "host-security-profile-1" # Yandex Smart Web Security profile for hosts
# 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
# Path rewriting
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
# 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
# ALB resource naming
# Custom names for ALB resources created by the controller.
gwin.yandex.cloud/albBalancerName: "my-balancer" # custom balancer name
# albVirtualHostName requires Ingress associated with exactly one host
gwin.yandex.cloud/hosts.albVirtualHostName: "my-virtual-host" # custom virtual host name
# albRouteName, albBackendGroupName, albBackendName require Ingress with exactly one rule
gwin.yandex.cloud/rules.albRouteName: "my-route" # custom route name
gwin.yandex.cloud/rules.albBackendGroupName: "my-backend-group" # custom backend group name
gwin.yandex.cloud/rules.backends.albBackendName: "my-backend" # custom backend name
# 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/hosts.rbac.action: "DENY" # host-level RBAC action
```
### Annotations reference
#### Ingress Group Configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/groupName`
_(string)_
Name of the ingress group. Ingresses in the same group use the same load balancer.
Example: `my-ingress-group` |
| `gwin.yandex.cloud/groupOrder`
_(number)_
Processing order within the ingress group.
Example: `100` |
#### Load Balancer Configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/externalIPv4Address`
_(string)_
External IPv4 address for the load balancer. Use `auto` to automatically allocate a new address.
Example: `5.4.3.2`, `auto` |
| `gwin.yandex.cloud/internalIPv4Address`
_(string)_
Internal IPv4 address for the load balancer inside VPC subnet. Format: `subnet-id/ip-address` or `subnet-id/auto` to automatically allocate an address.
Example: `subnet-id-1/10.1.1.1`, `subnet-id-1/auto` |
| `gwin.yandex.cloud/subnets`
_(comma separated strings)_
[Subnets](../../vpc/concepts/network.md#subnet) of the zones where load balancer will be instantiated.
By default, the balancer is placed in the mk8s cluster subnets. You can override this behavior by configuring `controller.defaultBalancerSubnets` in the Helm chart values.
Example: `subnet-id-1,subnet-id-2` |
| `gwin.yandex.cloud/securityGroups`
_(comma separated strings)_
[Security groups](../../vpc/concepts/security-groups.md) of load balancer.
By default, the balancer network’s default security group is used.
Example: `sg-id-1,sg-id-2` |
| `gwin.yandex.cloud/allowZonalShift`
_(boolean)_
Specifies whether application load balancer is available to zonal shift.
Example: `true` |
#### Cloud Logging
For `discardRule` annotations you can set up any name. It does not affect ALB configuration in any way.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/logs.logGroupID`
_(string)_
[Cloud Logging](../../logging/index.md) log group ID to store [access logs](../logs-ref.md).
Example: `log-group-id-1` |
| `gwin.yandex.cloud/logs.disable`
_(boolean)_
Disable sending logs to [Cloud Logging](../../logging/index.md).
Example: `false` |
| `gwin.yandex.cloud/logs.discardRule.{name}.httpCodes`
_(comma separated numbers)_
HTTP status codes to discard from logs.
Example: `404,500` |
| `gwin.yandex.cloud/logs.discardRule.{name}.httpCodeIntervals`
_(comma separated strings)_
HTTP code intervals to discard.
Example: `HTTP_4XX,HTTP_5XX` |
| `gwin.yandex.cloud/logs.discardRule.{name}.grpcCodes`
_(comma separated strings)_
gRPC codes to discard from logs.
Example: `INTERNAL,UNIMPLEMENTED` |
| `gwin.yandex.cloud/logs.discardRule.{name}.discardPercent`
_(number)_
Percentage of matching logs to discard (0-100).
Example: `10` |
#### Autoscaling
| Annotation and description |
|------------|
| `gwin.yandex.cloud/autoScale.minZoneSize`
_(number)_
Minimum [resource units](../concepts/application-load-balancer.md#lcu-scaling) per zone (must be ≥2).
Example: `2` |
| `gwin.yandex.cloud/autoScale.maxSize`
_(number)_
Maximum total [resource units](../concepts/application-load-balancer.md#lcu-scaling) (0 = no limit).
Example: `10` |
#### Zone traffic control
`` is a zone id, e.g. `ru-central1-a`.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/zone.{zone}.receiveTraffic`
_(boolean)_
Disable traffic to load balancer nodes in specified [availability zone](../../overview/concepts/geo-scope.md).
Example: `false` |
#### Listener configuration
| Annotation and description |
|------------|
| `gwin.yandex.cloud/listeners.http.protocolSettings.allowHTTP10`
_(boolean)_
Enables support for incoming HTTP/1.0 and HTTP/1.1 requests and disables it for HTTP/2 requests. Applies to all HTTP listeners.
Example: `true` |
| `gwin.yandex.cloud/listeners.http.protocolSettings.http2Options.maxConcurrentStreams`
_(number)_
Maximum number of concurrent HTTP/2 streams in a connection. Applies to all HTTP listeners.
Example: `100` |
| `gwin.yandex.cloud/listeners.stream.idleTimeout`
_(duration)_
The idle timeout is duration during which no data is transmitted or received on either the upstream or downstream connection. Applies to all stream listeners.
Example: `300s` |
| `gwin.yandex.cloud/listeners.rbac.action`
_(string)_
RBAC action (ALLOW/DENY) for HTTP router access control for all listeners.
Example: `ALLOW` |
#### 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](../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.
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` |
| `gwin.yandex.cloud/rules.allowedMethods`
_(comma separated strings)_
Restricts which HTTP methods are allowed for this route. If not specified, all methods are allowed.
Example: `GET,POST,PUT` |
| `gwin.yandex.cloud/rules.prefixRewrite`
_(string)_
Replaces URL paths in HTTP/gRPC requests. With pathType Exact, the entire path is replaced; with pathType Prefix, only the matching prefix is rewritten.
Example: `/new-prefix` |
#### 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
| 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` |
#### 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` |
#### Header modification
Header modifications are applied in the following order: append, rename, replace, remove.
##### Request header modifications
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.modifyRequestHeaders.append.{header-name}`
_(string)_
Adds a new request header with the specified value.
Example: `custom-value` |
| `gwin.yandex.cloud/rules.modifyRequestHeaders.rename.{old-header-name}`
_(string)_
Renames an existing request header to the specified new name.
Example: `New-Header-Name` |
| `gwin.yandex.cloud/rules.modifyRequestHeaders.replace.{header-name}`
_(string)_
Replaces the value of an existing request header or creates a new one.
Example: `new-value` |
| `gwin.yandex.cloud/rules.modifyRequestHeaders.remove`
_(comma separated strings)_
Removes the specified request headers.
Example: `X-Remove-Me,X-Also-Remove` |
##### Response header modifications
| Annotation and description |
|------------|
| `gwin.yandex.cloud/rules.modifyResponseHeaders.append.{header-name}`
_(string)_
Adds a new response header with the specified value.
Example: `custom-value` |
| `gwin.yandex.cloud/rules.modifyResponseHeaders.rename.{old-header-name}`
_(string)_
Renames an existing response header to the specified new name.
Example: `New-Header-Name` |
| `gwin.yandex.cloud/rules.modifyResponseHeaders.replace.{header-name}`
_(string)_
Replaces the value of an existing response header or creates a new one.
Example: `new-value` |
| `gwin.yandex.cloud/rules.modifyResponseHeaders.remove`
_(comma separated strings)_
Removes the specified response headers.
Example: `Server,X-Powered-By` |
#### Redirect actions
Redirect actions can be referenced by Ingress path backends using `kind: Redirect` and `name: {redirect-name}`.
**Example**: Redirect HTTP traffic to HTTPS with a different host:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: redirect-example
annotations:
# Define redirect action
gwin.yandex.cloud/redirect.https-redirect.replaceScheme: "https"
gwin.yandex.cloud/redirect.https-redirect.replaceHost: "secure.example.com"
gwin.yandex.cloud/redirect.https-redirect.responseCode: "301"
spec:
ingressClassName: gwin-default
rules:
- host: "example.com"
http:
paths:
- path: "/"
pathType: Prefix
backend:
resource:
kind: Redirect
name: https-redirect # References the redirect action above
```
This example redirects all HTTP requests from `http://example.com/*` to `https://secure.example.com/*` with a 301 (permanent redirect) status code.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/redirect.{name}.replaceScheme`
_(string)_
Changes the URL scheme (http/https) in the redirect location.
Example: `https` |
| `gwin.yandex.cloud/redirect.{name}.replaceHost`
_(string)_
Changes the hostname in the redirect location.
Example: `new-host.com` |
| `gwin.yandex.cloud/redirect.{name}.replacePort`
_(number)_
Changes the port number in the redirect location.
Example: `443` |
| `gwin.yandex.cloud/redirect.{name}.path.replacePath`
_(string)_
Replaces the entire path with the specified value.
Example: `/new-path` |
| `gwin.yandex.cloud/redirect.{name}.path.replacePrefix`
_(string)_
Replaces the matching path prefix with the specified value.
Example: `/new-prefix` |
| `gwin.yandex.cloud/redirect.{name}.removeQuery`
_(boolean)_
Determines whether to remove query parameters from the redirect URL.
Example: `true` |
| `gwin.yandex.cloud/redirect.{name}.responseCode`
_(number)_
HTTP status code for the redirect response (e.g., 301, 302, 303, 307, 308).
Example: `301` |
#### Direct response actions
Direct response actions can be referenced by Ingress path backends using `kind: DirectResponse` and `name: {response-name}`.
| Annotation and description |
|------------|
| `gwin.yandex.cloud/directResponse.{name}.responseCode`
_(number)_
HTTP status code to return in the direct response.
Example: `200` |
| `gwin.yandex.cloud/directResponse.{name}.responseBody.text`
_(string)_
Plain text content to include in the response. body
Example: `Hello World` |
#### 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` |
#### 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/albBalancerName`
_(string)_
Custom name for the ALB load balancer. Applied on the Ingress resource.
Example: `my-balancer` |
| `gwin.yandex.cloud/hosts.albVirtualHostName`
_(string)_
Custom name for the ALB virtual host. Requires the Ingress to be associated with exactly one host.
Example: `my-virtual-host` |
| `gwin.yandex.cloud/rules.albRouteName`
_(string)_
Custom name for the ALB route. Requires the Ingress to have exactly one rule.
Example: `my-route` |
| `gwin.yandex.cloud/rules.albBackendGroupName`
_(string)_
Custom name for the ALB backend group. Requires the Ingress to have exactly one rule.
Example: `my-backend-group` |
| `gwin.yandex.cloud/rules.backends.albBackendName`
_(string)_
Custom name for the ALB backend. Requires the Ingress to have exactly one rule.
Example: `my-backend` |
For the target group name, see [`gwin.yandex.cloud/albTargetGroupName`](service.md) on the Service resource.
#### 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` |
## IngressSpec
IngressSpec describes the Ingress the user wishes to exist.
*Appears in*: [Ingress](#ingress)
| Field | Description |
|-------|-------------|
| ingressClassName | **string**
IngressClassName is the name of the IngressClass cluster resource. For Gwin, use `gwin`.
Example: `gwin-default` |
| defaultBackend | **[IngressBackend](#ingressbackend)**
DefaultBackend is the backend that should handle requests that don't match any rule. |
| tls | **[[]IngressTLS](#ingresstls)**
TLS configuration. |
| rules | **[[]IngressRule](#ingressrule)**
List of host rules used to configure the Ingress. |
### IngressRule
IngressRule represents the rules mapping the paths under a specified host to the related backend services.
*Appears in*: [IngressSpec](#ingressspec)
| Field | Description |
|-------|-------------|
| host | **string**
Host is the fully qualified domain name of a network host.
Example: `example.com` |
| http | **[HTTPIngressRuleValue](#httpingressrulevalue)**
HTTP represents a rule to apply against incoming requests. |
### HTTPIngressRuleValue
HTTPIngressRuleValue is a list of http selectors pointing to backends.
*Appears in*: [IngressRule](#ingressrule)
| Field | Description |
|-------|-------------|
| paths | **[[]HTTPIngressPath](#httpingresspath)**
Paths is a collection of paths that map requests to backends. |
### HTTPIngressPath
HTTPIngressPath associates a path with a backend.
*Appears in*: [HTTPIngressRuleValue](#httpingressrulevalue)
| Field | Description |
|-------|-------------|
| path | **string**
Path is matched against the path of an incoming request. For `ImplementationSpecific` pathType, this would be a regular expression.
Example: `/api` or `/regex.*` |
| pathType | **string**
PathType determines the interpretation of the Path matching. `Exact` for exact match, `Prefix` for prefix match, or `ImplementationSpecific` for regex matching.
Example: `Prefix` |
| backend | **[IngressBackend](#ingressbackend)**
Backend defines the referenced service endpoint to which the traffic will be forwarded. |
### IngressBackend
IngressBackend describes all endpoints for a given service and port.
*Appears in*: [IngressSpec](#ingressspec), [HTTPIngressPath](#httpingresspath)
| Field | Description |
|-------|-------------|
| service | **[IngressServiceBackend](#ingressservicebackend)**
Service references a Service as a Backend. |
| resource | **[TypedLocalObjectReference](#typedlocalobjectreference)**
Resource is an ObjectRef to another Kubernetes resource in the same namespace. Can reference [IngressBackendGroup](ingressbackendgroup.md), [YCStorageBucket](ycstoragebucket.md), `Redirect` or `DirectResponse` |
### TypedLocalObjectReference
Reference to a typed Kubernetes resource in the same namespace.
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| apiGroup | **string**
API group of the referenced resource
Example: `gwin.yandex.cloud` |
| kind | **string**
Kind of the referenced resource
Example: `IngressBackendGroup`, `YCStorageBucket`, `Redirect`, `DirectResponse` |
| name | **string**
Name of the referenced resource
Example: `static-backend-group` |
| apiGroup | **string**
API group of the referenced resource.
Example: `gwin.yandex.cloud` |
| kind | **string**
Kind of the referenced resource.
Example: `IngressBackendGroup`, `YCStorageBucket`, `Redirect`, `DirectResponse` |
| name | **string**
Name of the referenced resource.
Example: `static-backend-group` |
### IngressServiceBackend
IngressServiceBackend references a Kubernetes Service as a Backend.
*Appears in*: [IngressBackend](#ingressbackend)
| Field | Description |
|-------|-------------|
| name | **string**
Name is the referenced service.
Example: `api-service` |
| port | **[ServiceBackendPort](#servicebackendport)**
Port of the referenced service. |
### ServiceBackendPort
ServiceBackendPort is the service port being referenced.
*Appears in*: [IngressServiceBackend](#ingressservicebackend)
| Field | Description |
|-------|-------------|
| name | **string**
Name is the name of the port on the Service.
Example: `http` |
| number | **int32**
Number is the numerical port number on the Service.
Example: `8080` |
### IngressTLS
IngressTLS describes the transport layer security associated with an Ingress.
*Appears in*: [IngressSpec](#ingressspec)
{% note info %}
If multiple Ingress resources are combined into the same Ingress group (via the `gwin.yandex.cloud/groupName` annotation), the same host must not appear in **different `spec.tls` sections** within the group (for example, with a different `secretName`). \
The same host may be repeated across multiple Ingresses only if the corresponding **`spec.tls` sections are identical**. This allows you to split configuration across multiple Ingress resources (for example, to apply different `rules.*` annotations per route).
```yaml
kind: Ingress
metadata:
annotations:
gwin.yandex.cloud/groupName: "my-ingress-group"
gwin.yandex.cloud/rules.timeout: 10s
spec:
tls:
- hosts:
- example.com
secretName: cert-secret
...
kind: Ingress
metadata:
annotations:
gwin.yandex.cloud/groupName: "my-ingress-group"
gwin.yandex.cloud/rules.timeout: 100s # differs from 10s
spec:
tls:
- hosts:
- example.com
secretName: cert-secret
...
```
{% endnote %}
| Field | Description |
|-------|-------------|
| hosts | **[]string**
Hosts are a list of hosts included in the TLS certificate.
Example: `["example.com"]` |
| secretName | **string**
SecretName is the name of the secret used to terminate TLS traffic. For Yandex Cloud certificates, use format `yc-certmgr-cert-id-{certificate-id}`.
Example: `yc-certmgr-cert-id-fpq6gvvm6piu********` |