Get started
Yandex Application Load Balancer

Ingress fields and annotations

Written by

The Ingress resource defines the rules for distributing incoming traffic to Kubernetes services. The Application Load Balancer Ingress controller uses these rules to create a load balancer with the requisite listeners and HTTP routers. The services acting as Application Load Balancer backends may be specified in Ingress directly or as part of HttpBackendGroup backend groups.

Ingress is a Kubernetes standard resource. This reference describes the fields and the annotations of the resource that a Application Load Balancer Ingress controller interfaces with. For a complete reference on the resource, please see the Kubernetes documentation.

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <string>
  annotations:
    ...
spec: <IngressSpec>

Where:

  • apiVersion: networking.k8s.io/v1

  • kind: Ingress

  • metadata (ObjectMeta, required)

    Resource metadata.

    • name (string, required)

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

      Does not match the balancer name in Application Load Balancer.

    • annotations (map[string]string, required)

      Resource annotation. For more detail, please see below.

  • spec (IngressSpec, required)

    Resource specification. For more detail, please see below.

Annotations (metadata.annotations)

metadata:
  annotations:
    ingress.alb.yc.io/group-name: <string>
    ingress.alb.yc.io/subnets: <string>
    ingress.alb.yc.io/security-groups: <string>
    ingress.alb.yc.io/external-ipv4-address: <string>
    ingress.alb.yc.io/internal-ipv4-address: <string>
    ingress.alb.yc.io/internal-alb-subnet: <string>
    ingress.alb.yc.io/protocol: <string>
    ingress.alb.yc.io/transport-security: <string>
    ingress.alb.yc.io/prefix-rewrite: <string>
    ingress.alb.yc.io/upgrade-types: <string>
    ingress.alb.yc.io/request-timeout: <string>
    ingress.alb.yc.io/idle-timeout: <string>

Where:

  • ingress.alb.yc.io/group-name (string, required)

    Name of an Ingress resource group combined in a single load balancer. For more information about format, please see the Kubernetes documentation.

    The field is required even if the load balancer uses a single Ingress.

  • ingress.alb.yc.io/subnets (string)

    List of Virtual Private Cloud subnets the load balancer is located on. Subnet IDs are provided as a comma-separated list, such as:

    ingress.alb.yc.io/subnets: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1

    The field is required for at least a single Ingress in a group (ingress.alb.yc.io/group-name annotation) to create one load balancer. A balancer uses all the subnets specified in the relevant Ingress resources.

    All the subnets of a single load balancer must belong to the same network with no more than one network specified in each availability zone.

  • ingress.alb.yc.io/security-groups (string)

    Note

    Security groups are at the Preview stage. If they aren't available on your network, all incoming and outgoing traffic will be enabled for the resources and no additional setup is required.

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

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

    A load balancer created for a group of several Ingress resources (ingress.alb.yc.io/group-name annotation) uses all the security groups specified in these Ingress resources.

    For proper load balancer and Ingress controller operation, the security groups must be configured as specified in Configuring Application Load Balancer Ingress controller security groups.

  • ingress.alb.yc.io/external-ipv4-address (string)

    Configuring a load balancer's public IP.

    To use a reserved IP, put it in the annotation value. For the load balancer to get its IP automatically, specify auto.

    A load balancer must be configured with either a public or a private IP (ingress.alb.yc.io/internal-ipv4-address annotation) but not both.

  • ingress.alb.yc.io/internal-ipv4-address (string)

    Configuring a load balancer with a private IP.

    The IP address must belong to the subnet specified in the ingress.alb.yc.io/internal-alb-subnet annotation. To use a specific IP from the subnet in question, put it in the annotation. For the load balancer to get its IP automatically, specify auto.

    A load balancer must be configured with either a private or a public IP (ingress.alb.yc.io/external-ipv4-address annotation) but not both.

  • ingress.alb.yc.io/internal-alb-subnet (string)

    Load balancer private IP subnet ID.

    The field is required if a load balancer is configured with a private IP address (ingress.alb.yc.io/internal-ipv4-address annotation).

  • ingress.alb.yc.io/protocol (string)

    Connection protocol for load balancer and backends described in Ingress:

    • http: HTTP/1.1. Default value.
    • http2: HTTP/2.
    • grpc: gRPC.

  • ingress.alb.yc.io/transport-security (string)

    Connection encryption protocol for load balancer and backends specified in Ingress directly (no HttpBackendGroup):

    • tls: TLS with no certificate challenge.

    If no annotation is specified, the load balancer connects to the backends with no encryption.

    For backends belonging to groups, the annotation value is ignored. When you encrypt a connection between a load balancer and grouped backends, you configure the encryption via the spec.backend.tls field of the HttpBackendGroup resource (see the resource reference).

  • ingress.alb.yc.io/prefix-rewrite (string)

    Substitution for URI paths or gRPC call names listed in the Ingress specification (rules.http.paths field) when routing requests to backends.

    The substitution depends on path or name type: for pathType: Exact, the entire path or name is replaced, for pathType: Prefix, only the specified initial portion is replaced.

    For example, to have the load balancer route backend requests to a specific version when handling all incoming API calls, configure the following substitution:

    ...
metadata:
  annotations:
    ingress.alb.yc.io/prefix-rewrite: /api/v4/
...
spec:
  rules:
    - host: <domain name>
      http:
        paths:
          - path: /api/
            pathType: Prefix
            ...

    In Application Load Balancer, the substitution will be configured on all HTTP routers created for the Ingress resource.

  • ingress.alb.yc.io/upgrade-types (string)

    Value of the HTTP Upgrade header in all incoming requests supported by the load balancer. The values are given as a comma-separated list.

    You can use this annotation, for instance, to enable WebSocket support:

    ingress.alb.yc.io/upgrade-types: WebSocket

    In Application Load Balancer, Upgrade will be configured on all the HTTP routers created for the Ingress resource.

  • ingress.alb.yc.io/request-timeout (string)

    Maximum load balancer node/backend connection timeout. Once the timeout expires, the load balancer responds to client with 504 Gateway Timeout.

    Default: 60s.

    In Application Load Balancer, the timeout will be configured on all HTTP routers created for the Ingress resource.

  • ingress.alb.yc.io/idle-timeout (string)

    Maximum load balancer node/backend connection idle timeout. Once the timeout expires, the load balancer responds to client with 504 Gateway Timeout.

    Unless an annotation is specified, a connection can remain idle for any length of time until the overall timeout expires (ingress.alb.yc.io/request-timeout annotation).

    In Application Load Balancer, the timeout will be configured on all HTTP routers created for the Ingress resource.

IngressSpec

spec:
  tls:
    - hosts:
        - <string>
        - ...
      secretName: <string>
    - ...
  rules:
    - host: <string>
      http:
        paths:
          - path: <string>
            pathType: <string>
            backend: <IngressBackend>
    - ...

Where:

  • tls ([]IngressTLS)

    Incoming HTTPS traffic settings: domain name collections and the relevant TLS certificates.

    If the field is specified, two types of listeners will be created for the load balancer: some will be receiving HTTPS traffic on port 443, others will redirect HTTP requests (port 80) to HTTPS. At the same time, the traffic distribution rules for the same domain names, if explicitly specified in other Ingress resources lacking the tls field will be given priority with respect to HTTP-to-HTTPS redirects.

    If the field is not specified, only HTTP listeners will be created for the load balancer to handle traffic on port 80.

    • hosts ([]string, required)

      Domain names that the secretName TLS certificate corresponds to.

      The load balancer will create a dedicated listener for each domain name serving as a value for the Server Name Indication (SNI) TLS extension.

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

      The value "*.yandexcloud.example", for instance, matches foo.yandexcloud.example, foo-bar.yandexcloud.example, foo.bar.yandexcloud.example, foo.bar.baz.yandexcloud.example, and so on (but not yandexcloud.example).

      You cannot replace only a part of a first-level domain name with an asterisk. *foo.yandexcloud.example, for instance, is illegal.

    • secretName (string, required)

      A reference to a TLS certificate from Yandex Certificate Manager as yc-certmgr-cert-id-<certificate ID>. This is the name a secret with a certificate is available as in Managed Service for Kubernetes.

      In Certificate Manager, you can have a certificate issued by Let's Encrypt® or load one of your own.

      Warning

      The secretName field only supports references to certificates from Certificate Manager as yc-certmgr-cert-id-<certificate ID>. Do not enter Kubernetes internal secrets in this field.

  • rules ([]IngressRule, required)

    A list of rules for distributing incoming traffic to the backends as a function of the domain names (host field) and the resource being requested (http.paths field).

    In Application Load Balancer, the rules correspond to HTTP router virtual hosts.

    • host (string, required)

      Domain name (value of Host header for HTTP/1.1 or :authority pseudo-header for HTTP/2), to which a rule applies.

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

      The value "*.yandexcloud.example", for instance, matches foo.yandexcloud.example, foo-bar.yandexcloud.example, foo.bar.yandexcloud.example, foo.bar.baz.yandexcloud.example, and so on (but not yandexcloud.example).

      You cannot replace only a part of a first-level domain name with an asterisk. *foo.yandexcloud.example, for instance, is illegal.

    • http (HTTPIngressRuleValue, required)

      Rule for routing incoming requests with the domain name specified in the rules.host field as a function of the resource being requested.

      • paths ([]HTTPIngressPath, required)

        List of routes: the resources being requested, subject to a rule and the corresponding backends.

        The sequence of routes on the list is important: they are matched against an incoming request in turn, and the first match is used for routing. Therefore, it is recommended that you place the most specific routes at the top of the list. This logic is different from what is described in the Kubernetes documentation which prioritizes routes with the longest paths (rules.http.paths.path field).

        Warning

        If you create a load balancer for several Ingress resources (with the same ingress.alb.yc.io/group-name annotation value), and they include rules for the same domain name, the route processing sequence is only guaranteed within each of the Ingress resources but not across them.

        • pathType (string, required)

          Type of reference to the requested resource:

          • Exact: path in the request URI or gRPC call name must match the value in the rules.http.paths.path field.
          • Prefix: path in request URI or gRPC call name must begin with the value in the rules.http.paths.path field.

          In addition to distributing traffic, the type also affects the path or call name substitution mechanism in backend requests if the substitution is configured via the ingress.alb.yc.io/prefix-rewrite annotation.

        • path (string, required)

          Reference to the resource being requested:

          • For simple HTTP: path in the incoming request URI (if Exact) or its front portion (if Prefix).
          • For gRPC (with the ingress.alb.yc.io/protocol annotation value equal to grpc): full gRPC call name (for Exact) or its front portion (for Prefix). Example: /my.custom.server.Service/Method.

          In both cases, the value must begin with /.

        • backend (IngressBackend, required)

          Reference to a backend or a group of backends to process requests with the specified domain name or URI path or gRPC call name. For more detail, please see below.

IngressBackend

spec:
  rules:
    - http:
        paths:
          - backend:
              service:
                name: <string>
                port:
                  name: <string>
                  number: <int32>
              resource:
                kind: HttpBackendGroup
                name: <string>
                apiGroup: alb.yc.io

Where:

  • service (IngressServiceBackend)

    Reference to the Kubernetes service expected to be the backend to process the requests.

    The Service resource this field points to must be described as in the specification.

    For the spec.rules.http.paths list element, you must specify either a service backend or a backend group (resource) but not both.

    • name (string, required)

      Kubernetes service name.

    • port (ServiceBackendPort, required)

      Port of the service Ingress will access.

      The field is designed for Ingress controller operation and does not match any of the Application Load Balancer resource fields.

      • name (string)

        Service port name.

        The name must match one of the port names specified in the spec.ports.name fields of the Service resource. For more detail, please see the resource specification.

        Either a name or a number must be specified for the service port but not both.

      • number (int32)

        Service port number.

        The number must match one of the port numbers specified in the spec.ports.port fields of the Service resource. For more detail, please see the resource specification.

        Either a number or a name must be specified for the service port but not both.

  • resource (TypedLocalObjectReference)

    Reference to a backend group to process requests.

    The Ingress controller implements the HttpBackendGroup resource that this field points to as a custom resource. It must be described as in the specification.

    For the spec.rules.http.paths list element, you must specify either a backend group or a service backend (service) but not both.

    • kind: HttpBackendGroup

    • name (string)

      Backend group name.

      The name must match the value specified in the metadata.name field of the HttpBackendGroup resource. For more detail, please see the resource specification.

    • apiGroup: alb.yc.io

In this article: