Ingress resource fields and annotations

The Ingress resource defines the rules for distribution of incoming traffic between 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 standard Kubernetes resource. Below, you can find the descriptions of the resource fields and annotations the Application Load Balancer Ingress controller interfaces with. For a full description of the resource configuration, see the Kubernetes documentation.

IngressIngress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata: <ObjectMeta>
spec: <IngressSpec>

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-demo-tls
  annotations:
    ingress.alb.yc.io/subnets: <list_of_subnet_IDs>
    ingress.alb.yc.io/security-groups: <list_of_security_group_IDs>
    ingress.alb.yc.io/external-ipv4-address: <auto_or_static_IP_address>
    ingress.alb.yc.io/group-name: my-ingress-group
spec:
  tls:
    - hosts:
        - <domain_name>
      secretName: yc-certmgr-cert-id-<TLS_certificate_ID>
  rules:
    - host: <domain_name>
      http:
        paths:
          - path: /app1
            pathType: Prefix
            backend:
              service:
                name: alb-demo-1
                port:
                  number: 80
          - path: /app2
            pathType: Prefix
            backend:
              service:
                name: alb-demo-2
                port:
                  number: 80
          - pathType: Prefix
            path: "/"
            backend:
              service:
                name: alb-demo-2
                port:
                  name: http

ObjectMetaObjectMeta

name: <string>
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/group-settings-name: <string>
  ingress.alb.yc.io/group-order: <string>
  ingress.alb.yc.io/transport-security: <string> # Only up to but excluding version 0.2.0.
  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>
  ingress.alb.yc.io/modify-header-response-append: <string>
  ingress.alb.yc.io/modify-header-response-replace: <string>
  ingress.alb.yc.io/modify-header-response-rename: <string>
  ingress.alb.yc.io/modify-header-response-remove: <string>
  ingress.alb.yc.io/modify-header-request-append: <string>
  ingress.alb.yc.io/modify-header-request-replace: <string>
  ingress.alb.yc.io/modify-header-request-rename: <string>
  ingress.alb.yc.io/modify-header-request-remove: <string>
  ingress.alb.yc.io/security-profile-id: <string>
  ingress.alb.yc.io/use-regex: <string>
  ingress.alb.yc.io/balancing-panic-threshold: <string>
  ingress.alb.yc.io/balancing-locality-aware-routing: <string>
  ingress.alb.yc.io/autoscale-max-size: <string>
  ingress.alb.yc.io/autoscale-min-zone-size: <string>

Annotations (metadata.annotations)Annotations (metadata.annotations)

Annotations are collections of key:value pairs used for assigning metadata to objects. Annotation values are always of the string data type.

You can specify several <key>=<value> pairs separated by commas as the annotation value.

annotation: <key>=<value>,<key>=<value>,<key>=<value>

One key can be mapped to multiple values. For example, to add the X-Robots response header set to noarchive,nofollow,noindex, write the annotation as follows:

ingress.alb.yc.io/modify-header-response-replace: X-Robots-Tag=noarchive,X-Robots-Tag=nofollow,X-Robots-Tag=noindex

For more on annotations, see the Kubernetes documentation.

You can provide the following annotations for a ObjectMeta object:

• ingress.alb.yc.io/group-name

  Ingress resource group name. A separate load balancer is created for each group. You can combine multiple Ingress resources into one group to avoid creating a load balancer for each individual Ingress resource. For more information about the format, please see the Kubernetes documentation.

  This is a required field even if the Ingress resource is the only one in the group.

• ingress.alb.yc.io/subnets

  List of Virtual Private Cloud subnets the load balancer resides in. Subnet IDs are provided in a comma-separated list, e.g.:

  ingress.alb.yc.io/subnets: b0c2kotoidco********,e2lnhhdj9a0a********,e9bud5itjnl8********
  

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

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

  ingress.alb.yc.io/security-groups: b0c2kotoidco********,e2lnhhdj9a0a********,e9bud5itjnl8********
  

  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 the load balancer and Ingress controller to function properly, security groups must be configured as specified in Configuring security groups for Application Load Balancer tools for Managed Service for Kubernetes.

• ingress.alb.yc.io/external-ipv4-address

  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.

  If you set auto, deleting the Ingress controller will also delete the IP address from the cloud. To avoid this, use an existing reserved IP address.

  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

  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, specify 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

  Subnet ID of the load balancer's private IP address.

  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

  Connection protocol for the load balancer and backends described in Ingress:

  • http: HTTP/1.1, default
  • http2: HTTP/2
  • grpc: gRPC

• ingress.alb.yc.io/group-settings-name

  Name for the Ingress resource group settings.

  To specify the settings, create an additional resource named IngressGroupSettings.

• ingress.alb.yc.io/group-order

  Sequence number of the Ingress resource. If you specify sequence numbers for multiple resources in the Ingress resource group, it will define the order for adding internal traffic routes. Ingress resources are sorted in nondecreasing order.

  Annotation does not apply to routes specified by a single Ingress resource.

  Specify an integer in the annotation value. The default value is 0.

• ingress.alb.yc.io/transport-security

  Warning

  In ALB Ingress Controller version 0.2.0 and later, use annotation only in the Service object.

  If you annotate Ingress resources that use a single service with the same settings for backend groups, such annotation will apply correctly. However, this mechanism is obsolete and will not be supported going forward.

  Connection encryption protocol for the load balancer and backends specified in Ingress directly (without HttpBackendGroup).

  The acceptable value is 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

  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 the path or name type: for pathType: Exact, the entire path or name is replaced, for pathType: Prefix, only the specified initial portion is replaced.

  Example

  For the load balancer to send backend requests to a particular version for all incoming requests to your API, set up 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

  The Upgrade HTTP header values supported by the load balancer in incoming requests. 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

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

  The default value is 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

  Maximum load balancer node/backend connection idle timeout. Once the timeout expires, the load balancer responds to the 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.

• ingress.alb.yc.io/modify-header-response-append

  Adds a string to the response header value. The header and string should be specified in the following format:

  ingress.alb.yc.io/modify-header-response-append: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: String to be added to the header value.

• ingress.alb.yc.io/modify-header-response-replace

  It replaces the response header value. The header and its new value should be specified in the following format:

  ingress.alb.yc.io/modify-header-response-replace: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: New header value.

• ingress.alb.yc.io/modify-header-response-rename

  It renames the response header. The header and its new name should be specified in the following format:

  ingress.alb.yc.io/modify-header-response-rename: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: New header value.

• ingress.alb.yc.io/modify-header-response-remove

  It removes the response header. The header to remove should be specified in the following format:

  ingress.alb.yc.io/modify-header-response-remove: <key>=true
  

  Where <key> is the name of the header to remove.

• ingress.alb.yc.io/modify-header-request-append

  Adds a string to the request header value. The header and string should be specified in the following format:

  ingress.alb.yc.io/modify-header-request-append: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: String to be added to the header value.

• ingress.alb.yc.io/modify-header-request-replace

  Replaces the request header value. The header and its new value should be specified in the following format:

  ingress.alb.yc.io/modify-header-request-replace: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: New header value.

• ingress.alb.yc.io/modify-header-request-rename

  Renames the request header. The header and its new name should be specified in the following format:

  ingress.alb.yc.io/modify-header-request-rename: <key>=<value>
  

  Where:

  • <key>: Name of the header to modify.
  • <value>: New header value.

• ingress.alb.yc.io/modify-header-request-remove

  Removes the request header. The header to remove should be specified in the following format:

  ingress.alb.yc.io/modify-header-request-remove: <key>=true
  

  Where <key> is the name of the header to remove.

• ingress.alb.yc.io/security-profile-id

  Includes support for Yandex Smart Web Security that allows you to get protected against DDoS attacks and bots, plus enable WAF and limit the load on the resource you are protecting.

  Note

  To connect your security profile to an Application Load Balancer virtual host, the service account used to operate the Ingress controller must have the smart-web-security.editor role for the folder hosting Application Load Balancer and Smart Web Security resources. For more information, see Assigning a role to a service account.

  The service checks HTTP requests sent to the protected resource via the virtual host of the L7 load balancer. Depending on the results of the check, the service sends requests to the protected resource, blocks them or sends them to Yandex SmartCaptcha for additional verification.

  To enable support for the service, specify the Smart Web Security security profile ID in the Ingress annotation:

  ingress.alb.yc.io/security-profile-id: <security_profile_ID>
  

  The profile contains a list of verification conditions and actions applied to incoming HTTP requests based on verification results.

  If you do not have a security profile, create one.

• ingress.alb.yc.io/use-regex

  Enables support for RE2 regular expressions when matching the request path if the true string is provided. Only applies if the pathType parameter is set to Exact.

• ingress.alb.yc.io/balancing-panic-threshold

  Sets a panic mode threshold. The mode will be activated if the percentage of healthy endpoints falls below this value.

  The default value is 0 and it never activates panic mode.

• ingress.alb.yc.io/balancing-locality-aware-routing

  Sets the percentage of incoming traffic the load balancer forwards to backends from its availability zone. The remaining traffic is evenly distributed between other availability zones.

  The default value is 0.

  More on locality-aware routing.

• ingress.alb.yc.io/autoscale-max-size

  Sets the maximum total number of resource units. By default, this number is unlimited. Make sure the value is more or equal to the number of load balancer availability zones multiplied by the minimum number of resource units per zone.

  Learn more about the autoscaling settings here.

• ingress.alb.yc.io/autoscale-min-zone-size

  Sets the minimum number of resource units per availability zone. The minimum and default value is 2.

  Learn more about the autoscaling settings here.

IngressSpecIngressSpec

ingressClassName: <string>
tls:
  - <IngressTLS>
  - ...
rules:
  - <IngressRule>
  - ...
defaultBackend:
  - <IngressBackend>
  - ...

IngressTLSIngressTLS

hosts:
  - <string>
  - ...
secretName: <string>

IngressRuleIngressRule

host: <string>
http:
  paths:
    - path: <string>
      pathType: <string>
      backend: <IngressBackend>

In ALB Ingress Controller versions prior to 0.2.0, each backend group corresponds to a bundle of host, http.paths.path, and http.paths.pathType parameters. In versions 0.2.0 and later, the backend group corresponds to the backend.service parameter (IngressBackend). This may cause collisions when updating the ALB Ingress Controller. To avoid them, find out whether upgrade restrictions apply to your infrastructure.

IngressBackendIngressBackend

service:
  name: <string>
  port:
    name: <string>
    number: <int32>
resource:
  kind: HttpBackendGroup
  name: <string>
  apiGroup: alb.yc.io

DefaultBackendDefaultBackend

Default backend to redirect traffic to when no rules are set for distribution of ingress traffic among the backends. If the Ingress description has no spec.rules field, the spec.defaultBackend field must be present.

If the domain name and the requested resource mismatch those specified in the rules, traffic will also be redirected to the default backend.

The spec.defaultBackend field indicates either a service backend (service) or a backend group (resource). Populate this field in the same way as IngressBackend.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: testapp-ingress-with-default-backend
  namespace: testapp-ns
  annotations:
    ...
spec:
  defaultBackend:
    service:
      name: testapp-service
      port:
        name: http

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-1
  annotations:
    ...
spec:
  defaultBackend:
    resource:
      apiGroup: alb.yc.io
      kind: HttpBackendGroup
      name: bg-with-bucket

IngressGroupSettingsIngressGroupSettings

apiVersion: alb.yc.io/v1alpha1
kind: IngressGroupSettings
metadata:
  name: non-default-settings
logOptions:
  logGroupID: <log_group_ID>
  discardRules:
    - discardPercent: 50
      grpcCodes:
        - OK
        - CANCELLED
        - UNKNOWN
    - discardPercent: 67
      httpCodeIntervals:
        - HTTP_1XX
    - discardPercent: 20
      httpCodes:
        - 200
        - 404

Specify the log group ID and parameters of the rules for discarding logs:

• httpCodes: HTTP codes.
• httpCodeIntervals: HTTP code classes.
• grpcCodes: gRPC codes.
• discardPercent: Percentage of logs to discard.