Gateway resource fields

The Gateway resource defines rules for accepting and routing incoming traffic. HTTPRoute and TLSRoute resources specify traffic routes. Application Load Balancer Gateway API uses these rules to create:

• Load balancer and its listeners.
• Backend groups.
• HTTP routers. They are only created if HTTPRoute resources are used.

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

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.

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. This is a required field.

  Resource metadata.

  • name: string. This is a required field.

    Resource name. For more information about the name format, see the relevant Kubernetes guides.

    Do not mistake this name for the Application Load Balancer load balancer name.

  • namespace (string)

    Resource namespace. The default namespace is default.

  • annotations (map[string]string, required)

    Resource annotations.

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

      Comma separated list of load balancer’s Virtual Private Cloud security group IDs, e.g.:

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

      For the proper load balancer and Gateway API operation, 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)

    Listener internal name.

    This name is only used by Kubernetes. Do not mistake it for the Application Load Balancer 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 internal name can be up to 63 characters long.

  • hostname (string)

    Listener domain name.

    To match all subdomains at any level, use a wildcard * in place of the first-level domain name. Wildcard domain values must be quoted.

    For example, "*.example.com" matches foo.example.com, foo-bar.example.com, foo.bar.example.com, and foo.bar.baz.example.com, but not example.com.

    Wildcards must replace complete domain levels; for example, *foo.example.com is invalid.

    The listener will only process routes, i.e., HTTPRoute and TLSRoute resources, with domain names, i.e spec.hostnames fields, matching the value specified in this setting.

  • port (int32)

    Listener incoming traffic port.

  • protocol (string)

    Listener incoming traffic protocol: HTTP, HTTPS or TLS.

  • tls (GatewayTlsConfig)

    TLS settings for incoming HTTPS and TLS traffic.

    • 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.

    • 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.

      The load balancer will only use the first certificate from the list while ignoring the others.

      You can add a certificate to a cluster as a secret, i.e., Secret resource, in the Managed Service for Kubernetes management console or using the kubectl command line tool:

      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 associated with the certificate resource, e.g., networking.k8s.io.

        The default value is empty, indicating the root API group.

      • kind (string)

        Type of the Kubernetes certificate storage resource.

        The default value is Secret.

      • name (string)

        Name of the Kubernetes certificate storage resource.

      • namespace (string)

        Certificate resource namespace.

  • allowedRoutes (AllowedRoutes)

    Rules for selection of listener routes, i.e., HTTPRoute 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.

    • namespaces (RouteNamespaces)

      Namespace selection rule for HTTPRoute and TLSRoute listener resources.

      • 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.

      • selector (LabelSelector)

        Namespace selection requirements. To be selected, a namespace must meet all criteria specified in matchExpressions and matchLabels fields.

        To learn more, see the Kubernetes API reference.

        If you specify a value other than Selector in the from field, the selector field will be ignored.

• addresses ([]GatewayAddress)

  Load balancer public IP settings.

  If you skip this field, the system will automatically assign one public IP address to the load balancer.

  • type: IPAddress

  • value (string)

    Yandex Virtual Private Cloud Load balancer public IP address.

    To use a public IP address, first, you need to reserve it by following this guide.