Gateway

Статья создана

Обновлена 30 октября 2025 г.

Cheatsheet
GatewayMeta
- Annotations cheatsheet
- Annotations reference
GatewaySpec

Gateway represents an instance of a service-traffic handling infrastructure by binding Listeners to a set of IP addresses. Gwin use these rules to create Load balancer.

Gateway is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by Application Load Balancer Gateway API. For configuration details, see the Kubernetes Gateway API reference.

Cheatsheet

Примечание

Specification provided below is not valid configuration.

It's just demonstration of all Gateway fields.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: my-gateway
  namespace: my-ns
  annotations: ...  # see annotations example below
spec:
  gatewayClassName: gwin-default  # Make Gwin to manage this gateway
  listeners:
    - name: http  # listener identifier
      hostname: "*.example.com"  # accept requests for this domain
      port: 80  # listen on this port
      protocol: HTTP  # protocol type
      allowedRoutes:  # which routes can use this listener
        namespaces:
          from: Selector  # select by labels (Any or Same can be used as alternative)
          selector:
            matchLabels:
              app: my-app  # routes in namespaces with this label
            matchExpressions:
              - key: app
                operator: In
                values:
                  - my-app  # alternative label matching
      tls:
        mode: Terminate  # decrypt TLS at load balancer
        certificateRefs:
          - group: gwin.yandex.cloud
            kind: YCCertificate  # Yandex Cloud certificate
            name: some-certificate
            namespace: some-ns
          - kind: Secret  # Kubernetes secret certificate
            name: some-secret
            namespace: some-ns
  addresses:
    - type: IPAddress
      value: <IP> # ipv4 address preallocated with vpc
    - type: gwin.yandex.cloud/autoIPv4 # Automatic external ipv4 address.
      value: auto
    - type: gwin.yandex.cloud/internalIPv4 # Address in vpc subnet.
      value: <subnet-id>/<ip> # You can use "auto" in <ip>.

Field	Description
metadata	GatewayMeta Name, namespace and annotations.
spec	GatewaySpec Resource specification.

GatewayMeta

Field	Description
name	string Name of the Gateway.
namespace	string Namespace of the Gateway.
annotations	map[string]string Annotations of the Gateway.

Annotations cheatsheet

Примечание

You can also set policy parameters using GatewayPolicy resource. The GatewayPolicy resource parameters and Gateway annotations are equivalent.

Specification provided below is not valid configuration.
It's just demonstration of all Gateway annotations.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: some-gateway
  annotations:
    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: "true"  # turn off logging
    gwin.yandex.cloud/logs.discardRule.some-rule.httpCodes: "404,500"  # skip these status codes
    gwin.yandex.cloud/logs.discardRule.some-rule.httpCodeIntervals: "HTTP_4XX,HTTP_5XX"  # skip error ranges
    gwin.yandex.cloud/logs.discardRule.some-rule.grpcCodes: "INTERNAL,UNIMPLEMENTED"  # skip gRPC errors
    gwin.yandex.cloud/logs.discardRule.some-rule.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

    # HTTPRouter configuration
    gwin.yandex.cloud/listeners.rbac.action: "ALLOW"  # access control policy

    # Listener configuration
    ## HTTP specific
    gwin.yandex.cloud/listeners.http.protocolSettings.allowHTTP10: "true"  # support old HTTP
    gwin.yandex.cloud/listeners.http.protocolSettings.http2Options.maxConcurrentStreams: "100"  # limit connections
    ## Stream specific
    gwin.yandex.cloud/listeners.stream.idleTimeout: "300s"  # stream backend idle timeout

    # Specific listener configuration
    gwin.yandex.cloud/listener.http-listener.http.protocolSettings.allowHTTP10: "true"  # per-listener HTTP setting
    gwin.yandex.cloud/listener.stream-listener.stream.idleTimeout: "300s"  # per-listener timeout
    ...

Annotations reference

Basic Gateway сonfiguration

Annotation and description
`gwin.yandex.cloud/subnets` (comma separated strings) Subnets of the zones where load balancer will be instantiated. Example: `subnet-id-1,subnet-id-2`
`gwin.yandex.cloud/securityGroups` (comma separated strings) Security groups of load balancer. Example: `"sg-id-1,sg-id-2"`
`gwin.yandex.cloud/allowZonalShift` (boolean) Specifies whether application load balancer is available to zonal shift. Read more about concept here. 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 log group ID to store access logs. Example: `log-group-id-1`
`gwin.yandex.cloud/logs.disable` (boolean) Disable sending logs to Cloud Logging. Example: `true`
`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 per zone (must be ≥2). Example: `2`
`gwin.yandex.cloud/autoScale.maxSize` (number) Maximum total resource units (0 = no limit). Example: `10`

Zone traffic control

<zone> 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. Example: `false`

Listener configuration

Примечание

Any listeners option can be applied to a specific listener by prefixing with listener.{listener-name}.

For example: gwin.yandex.cloud/listener.http-listener.http.protocolSettings.allowHTTP10: "true".

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`

HTTP router configuration

Примечание

Any listeners router option can be applied to a specific listener by prefixing with listener.{listener-name}.

For example: gwin.yandex.cloud/listener.http-listener.rbac.action: "ALLOW".

Annotation and description
`gwin.yandex.cloud/listeners.rbac.action` (string) RBAC action (ALLOW/DENY) for HTTP router access control for all listeners. Example: `ALLOW`

For detailed RBAC configuration patterns, see: RBAC Configuration

RBAC configuration

RBAC allows controlling access to listeners, 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 (listeners, 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.

Principal Types

Annotation pattern and description
`gwin.yandex.cloud/{resource}.rbac.action` (string) Action when principals match (ALLOW/DENY). Example: `ALLOW`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.header.name` (string) Header name to match. Example: `X-Api-Token`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.header.exact` (string) Exact header value match. Example: `admin123`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.header.regex` (string) Regular expression header value match. Example: `^admin.*`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.header.prefix` (string) Prefix header value match. Example: `Bearer`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.ip.remoteIp` (string) IP/CIDR to match. Example: `10.0.0.0/8`
`gwin.yandex.cloud/{resource}.rbac.principals.{principal-group}.{principal}.any` (boolean) Match any request. Example: `true`

GatewaySpec

Gateway specification.

Default name for default GatewayClass is "gwin-default". So use this to attach gateways to Gwin.

Appears in: Gateway

Field	Description
gatewayClassName	string Gateway class name. Example: `gwin-default`
listeners	[]Listener Gateway listeners.
addresses	[]GatewayAddress Load balancer public IP settings.

Listener

Gateway listener configuration.

Appears in: GatewaySpec

Field	Description
name	string Listener internal name. This name is only used by Kubernetes. Do not mistake it for the ALB listener name. The internal name should be in domain format, i.e., match the following regular expression: `[a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)*`. For example, `example`, `example.com`, and `foo.example.com` are valid internal names, while `example.com/bar` and `-example.` are not. The name can be up to 63 characters long. Example: `http`, `example.com`.
hostname	string Listener domain name. The listener will only process routes, i.e., HTTPRoute, GRPCRoute and TLSRoute resources, with domain names, i.e `spec.hostnames` fields, matching the value specified in this setting. Example: `*.example.com`
port	int32 Listener incoming traffic port. Example: `80`, `443`.
protocol	string Listener incoming traffic protocol: `HTTP`, `HTTPS` or `TLS`. Example: `HTTP`, `HTTPS`, `TLS`.
tls	GatewayTlsConfig TLS settings for incoming HTTPS and TLS traffic.
allowedRoutes	AllowedRoutes Rules for selection of listener routes, i.e., HTTPRoute, GRPCRoute and TLSRoute resources. To ensure route selection, these resources must have `Gateway` specified in their `spec.parentRefs` fields. The system will use these routes to create backend groups you can link to the listener. The system will automatically create HTTP routers for `HTTPRoute` resources.

GatewayTlsConfig

TLS settings for HTTPS and TLS traffic termination.

Appears in: Listener

Field	Description
mode	string TLS connections termination mode. You can only use the default `Terminate` setting, where incoming traffic is decrypted using certificates from `certificateRefs` and then routed to backends. `Passthrough` mode without connection termination is not supported yet. Example: `Terminate`
certificateRefs	[]SecretObjectReference Kubernetes resources containing TLS certificates. You can only use this setting if `protocol` is specified as `HTTPS` or `TLS`. The list must contain at least one certificate.

SecretObjectReference

Reference to Kubernetes resource containing TLS certificate.

You can specify a certificate from Certificate Manager (the YCCertificate resource) or from Secret resource (certificate in Certificate Manager will be created automatically).

kubectl create secret tls <secret_name> \
  --namespace <namespace_name> \
  --cert <certificate_file_path> \
  --key <path_to_file_with_certificate_private_key>

If Secret is used, Cloud Certificate will be created.
The secret must have the following fields (see k8s docs):

tls.crt — TLS certificate;
tls.key — TLS private key.

For YCCertificate details, see: YCCertificate

Appears in: GatewayTlsConfig

Field	Description
group	string Name of the Kubernetes API group associated with the certificate resource, e.g., `networking.k8s.io`. The default value is empty, indicating the root API group. Example: `gwin.yandex.cloud`
kind	string Type of the Kubernetes certificate storage resource. The default value is `Secret`. For a certificate from Certificate Manager, use the `YCCertificate` value. Example: `Secret`, `YCCertificate`.
name	string Name of the Kubernetes certificate storage resource. Example: `some-certificate`
namespace	string Certificate resource namespace. Example: `some-ns`

AllowedRoutes

Rules for selecting which routes can use this listener.

Appears in: Listener

Field	Description
namespaces	RouteNamespaces Namespace selection rule for HTTPRoute and TLSRoute resources.

RouteNamespaces

Namespace selection rules for HTTPRoute and TLSRoute resources.

Appears in: AllowedRoutes

Field	Description
from	string Rule type: `All` - All namespaces are available for resource selection; `Same` - Only the Gateway resource namespace specified in the `metadata.namespace` field is available for selection; `Selector` - Only namespaces meeting criteria specified in the `selector` field are available for selection. Example: `All`, `Same`, `Selector`.
selector	LabelSelector Namespace selection requirements. To be selected, a namespace must meet all criteria specified in `matchExpressions` and `matchLabels` fields. For more information, see the Kubernetes API reference. If you specify a value other than `Selector` in the `from` field, the `selector` field will be ignored.

LabelSelector

Label-based selection criteria for namespaces.

Appears in: RouteNamespaces

Field	Description
matchLabels	map[string]string Simple label matching requirements. Example: `app: my-app`
matchExpressions	[]LabelSelectorRequirement Advanced label matching expressions.

LabelSelectorRequirement

Advanced label matching expression with operator and values.

Appears in: LabelSelector

Field	Description
key	string Label key to match. Example: `app`
operator	string Matching operator. Example: `In`, `NotIn`, `Exists`.
values	[]string Values to match against. Example: `["my-app"]`

GatewayAddress

Load balancer public IP settings.

Types and values:

- type: IPAddress
  value: <IP> # ipv4 address preallocated with vpc
- type: gwin.yandex.cloud/autoIPv4 # Automatic external ipv4 address.
  value: auto
- type: gwin.yandex.cloud/internalIPv4 # Address in vpc subnet.
  value: <subnet-id>/<ip> # You can use "auto" in <ip>.

Appears in: GatewaySpec

Field	Description
type	string Address type: `IPAddress` for standard IP addresses, `gwin.yandex.cloud/autoIPv4` for automatic external IPv4 address, `gwin.yandex.cloud/internalIPv4` for address in VPC subnet. Example: `IPAddress`,`gwin.yandex.cloud/autoIPv4`,`gwin.yandex.cloud/internalIPv4`.
value	string Load balancer public IP address. To use a public IP address, first, you need to reserve it in VPC. For `gwin.yandex.cloud/autoIPv4` use `auto`. For `gwin.yandex.cloud/internalIPv4` use `<subnet-id>/<ip>` format where you can use `auto` for IP. Example: `5.4.3.2`, `auto`, `subnet-123/10.0.0.1`.

Gateway

CheatsheetCheatsheet

GatewayMetaGatewayMeta

Annotations cheatsheetAnnotations cheatsheet

Annotations referenceAnnotations reference

Basic Gateway сonfigurationBasic Gateway сonfiguration

Cloud LoggingCloud Logging

AutoscalingAutoscaling

Zone traffic controlZone traffic control

Listener configurationListener configuration

HTTP router configurationHTTP router configuration

RBAC configurationRBAC configuration

Combination RulesCombination Rules

Principal TypesPrincipal Types

GatewaySpecGatewaySpec

ListenerListener

GatewayTlsConfigGatewayTlsConfig

SecretObjectReferenceSecretObjectReference

AllowedRoutesAllowedRoutes

RouteNamespacesRouteNamespaces

LabelSelectorLabelSelector

LabelSelectorRequirementLabelSelectorRequirement

GatewayAddressGatewayAddress

Была ли статья полезна?

Cheatsheet

GatewayMeta

Annotations cheatsheet

Annotations reference

Basic Gateway сonfiguration

Cloud Logging

Autoscaling

Zone traffic control

Listener configuration

HTTP router configuration

RBAC configuration

Combination Rules

Principal Types

GatewaySpec

Listener

GatewayTlsConfig

SecretObjectReference

AllowedRoutes

RouteNamespaces

LabelSelector

LabelSelectorRequirement

GatewayAddress