Gateway resource fields

The Gateway resource defines the rules for accepting incoming traffic and selecting routes (the HTTPRoute and TLSRoute resources) for that traffic. Application Load Balancer Gateway API uses these rules to create:

• Load balancer with the required listeners.
• Backend groups.
• HTTP routers (if the HTTPRoute resources are used).

Gateway is designed for cluster operators. Application developers should use TLSRoute or HTTPRoute.

Gateway is a Kubernetes resource specified by the Kubernetes Gateway API project. Below, you can find the descriptions of the resource fields and annotations Application Load Balancer Gateway API interfaces with. For a full description of the resource configuration, see the Kubernetes Gateway API documentation.

GatewayGateway

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: <string>
  namespace: <string>
  annotations:
    gateway.alb.yc.io/security-groups: <string>
spec: <GatewaySpec>

Where:

• apiVersion: gateway.networking.k8s.io/v1alpha2

• kind: Gateway

• metadata (ObjectMeta, required)

  Resource metadata.

  • name (string, required)

    Resource name. For more information about the format, please see the Kubernetes documentation.

    This name is not the balancer name in Application Load Balancer.

  • namespace (string)

    Namespace the resource belongs to. The default value is default.

  • annotations (map[string]string, required)

    Resource annotations.

    • gateway.alb.yc.io/security-groups (string, required)

      List of Virtual Private Cloud security groups for a load balancer. Group IDs are provided in a comma-separated list, e.g.:

      gateway.alb.yc.io/security-groups: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1
      

      For the load balancer and Gateway API to function properly, make sure to configure security groups as specified in Configuring security groups for Application Load Balancer tools for Managed Service for Kubernetes.

• spec (GatewaySpec, required)

  Resource specification. For more information, see below.

GatewaySpecGatewaySpec

gatewayClassName: yc-df-class
listeners:
  - name: <string>
    hostname: <string>
    port: <int32>
    protocol: <string>
    tls:
      mode: <string>
      certificateRefs:
        - group: <string>
          kind: <string>
          name: <string>
          namespace: <string>
        - ...
    allowedRoutes:
      namespaces:
        from: <string>
        selector:
          matchExpressions:
            - key: <string>
              operator: <string>
              values:
                - <string>
                - ...
          matchLabels:
            <string>: <string>
            ...
  - ...
addresses:
  - type: IPAddress
    value: <string>
  - ...

Where:

• gatewayClassName: yc-df-class

• listeners ([]Listener)

  Load balancer listeners.

  • name (string)

    Internal name of the listener.

    This name only serves the Kubernetes needs and is not the listener name in Application Load Balancer.

    A name should have the domain format, i.e., correspond to 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 names, while example.com/bar and -example. are not.

    The name can be up to 63 characters long.

  • hostname (string)

    Domain name that the listener is enabled for.

    To refer to every possible subdomain at any level, replace the first-level domain name with an asterisk (*). In this case, the value must be wrapped in quotes.

    For instance, the "*.example.com" value matches foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com, etc., but does not match example.com.

    You cannot replace only a part of a first-level domain name with an asterisk, as in *foo.example.com.

    Only the routes (the HTTPRoute and TLSRoute resources) whose domain names (the spec.hostnames field) overlap with the domain name specified in this field will be linked to the listener.

  • port (int32)

    Port the listener uses for incoming traffic.

  • protocol (string)

    Protocol the listener uses for incoming traffic: HTTP, HTTPS or TLS.

  • tls (GatewayTlsConfig)

    TLS settings used for incoming HTTPS or TLS traffic.

    • mode (string)

      Mode for terminating TLS connections.

      The only supported and default value is Terminate: connections are terminated using certificates from the certificateRefs field, with decrypted traffic routed to backends. Passthrough mode (without connection termination) is not supported.

    • certificateRefs ([]SecretObjectReference)

      List of Kubernetes resources where TLS certificates are stored.

      It is only used if the protocol field is set to HTTPS or TLS. In which case the list must contain at least one certificate.

      The load balancer only uses the first certificate from the list while ignoring the other ones.

      You can add a certificate to a cluster as a secret (the Secret resource) using the Managed Service for Kubernetes management console or kubectl:

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

      • group (string)

        Name of the Kubernetes API group the resource with the certificate belongs to, e.g., networking.k8s.io.

        The default value is an empty line that indicates the root API group.

      • kind (string)

        Type of the Kubernetes resource that stores the certificate.

        The default value is Secret.

      • name (string)

        Name of the Kubernetes resource that stores the certificate.

      • namespace (string)

        Namespace that the name of the resource with the certificate belongs to.

  • allowedRoutes (AllowedRoutes)

    Rules for selecting routes for the listener (HTTPRoute and TLSRoute resources). To ensure a route is selected, the configuration of these resources must have the Gateway resource specified in the spec.parentRefs field.

    These routes are used to create the backend groups you can link to the listener. If using HTTPRoute, HTTP routers are also created.

    • namespaces (RouteNamespaces)

      Rule for selecting namespaces that cover the HTTPRoute and TLSRoute resources linked to the listener.

      • from (string)

        Rule type:

        • All: Resources are selected from all namespaces.
        • Same: Resources are only selected from the same namespace as the Gateway resource (the metadata.namespace field).
        • Selector: Resources are selected from namespaces that meet the criteria specified in the selector field.

      • selector (LabelSelector)

        A selector is a set of namespace requirements. Only namespaces that meet all the criteria in the matchExpressions and matchLabels fields are selected.

        To learn more, see the Kubernetes API reference.

        If the from field is not set to Selector, the selector field is ignored.

• addresses ([]GatewayAddress)

  Load balancer's public IP settings.

  If omitted, the load balancer is automatically assigned one public IP address.

  • type: IPAddress

  • value (string)

    Yandex Virtual Private Cloud public IP assigned to the load balancer.

    Before specifying an IP address in this field, make sure to reserve it by following this guide.