Ingress resource fields and annotations

The Ingress resource defines rules for incoming traffic distribution across Kubernetes services. The Application Load Balancer ingress controller uses these rules to create a load balancer, its listeners, and HTTP routers. You can specify Application Load Balancer backend services in Ingress directly or as part of HttpBackendGroup backend groups.

Ingress is a standard Kubernetes resource. Below, we describe its fields and annotations used by the Application Load Balancer ingress controller. For resource configuration details, see this Kubernetes guide.

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 for versions up to but not including 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>
  ingress.alb.yc.io/session-affinity-header: <string>
  ingress.alb.yc.io/session-affinity-cookie: <string>
  ingress.alb.yc.io/session-affinity-connection: <string>

Metadata.annotationsMetadata.annotations

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

You can specify the annotation value as a comma-separated list of multiple <key>=<value> pairs:

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

You can map one key to multiple values. For example, to add an X-Robots response header with the noarchive,nofollow,noindex value, 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 information on annotations, see this Kubernetes guide.

You can add the following annotations to ObjectMeta:

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

  Ingress resource group name. The system will create a separate load balancer for each group. You can group multiple Ingress resources to avoid creating load balancers for each individual resource. For more information about the format, see this Kubernetes guide.

  This is a required field even for one Ingress resource in a group.

• ingress.alb.yc.io/subnets

  Virtual Private Cloud subnets where the load balancer resides. This is a comma-separated list of subnet IDs, e.g.:

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

  This field is required for at least one Ingress in a group, i.e., the ingress.alb.yc.io/group-name annotation, to create one load balancer. The load balancer will use all subnets specified in the relevant Ingress resources.

  All subnets of a single load balancer must be in the same network. You cannot specify more than one network per availability zone.

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

  List of Virtual Private Cloud security groups for a load balancer. This is a comma separated list of group IDs, e.g.:

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

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

  For the proper load balancer and Ingress controller operation, make sure to configure security groups as specified in Configuring security groups for Managed Service for Kubernetes Application Load Balancer tools.

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

  Configuring the load balancer external IP address.

  To use a reserved IP address, put it in the annotation value. To enable automatic IP assignment for the load balancer, specify auto.

  If you set auto, deleting the ingress controller will also remove its associated IP address from the cloud. To avoid this, use a reserved IP address.

  A load balancer must be configured with either an external or internal IP address, i.e., the ingress.alb.yc.io/internal-ipv4-address annotation, but not both.

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

  Configuring the load balancer internal IP address.

  The IP address must belong to the subnet specified in the ingress.alb.yc.io/internal-alb-subnet annotation. To use an IP address from this subnet, specify it in the annotation. To enable automatic IP assignment for the load balancer, specify auto.

  A load balancer must be configured with either an internal or external IP address, i.e., the ingress.alb.yc.io/external-ipv4-address annotation, but not both.

• ingress.alb.yc.io/internal-alb-subnet

  Subnet ID of the load balancer internal IP address.

  This field is required if you configure your load balancer with an internal IP address, i.e., the ingress.alb.yc.io/internal-ipv4-address annotation.

• ingress.alb.yc.io/protocol

  Protocol for connections between the load balancer and backends defined in Ingress:

  • http: HTTP/1.1. This is a default value.
  • 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 IngressGroupSettings resource.

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

  Ingress resource sequence number. Ingress group resource sequence numbers will define the order in which internal traffic routes will be added. Ingress resources are sorted in non-decreasing order.

  This annotation does not apply to routes specified in a single Ingress resource.

  Specify an integer value for this annotation. The default value is 0.

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

  Warning

  In ALB Ingress Controller version 0.2.0 or later, you can only use this annotation in the Service object.

  Annotations specified in Ingress resources sharing a single service with the same backend group settings apply correctly. However, this feature is deprecated and will be discontinued.

  Encryption protocol for connections between the load balancer and backends specified in Ingress directly, without using HttpBackendGroup.

  The acceptable value is tls: TLS without certificate validation.

  If this annotation is not specified, the load balancer will connect to the backends without encryption.

  This annotation is ignored for grouped backends. To configure encryption for connections between the load balancer and grouped backends, use the spec.backend.tls field of the HttpBackendGroup resource. For more information, see this article.

• ingress.alb.yc.io/prefix-rewrite

  URI path / gRPC call name replacements applied when routing requests to backends. The relevant paths and names are listed in the Ingress specification under rules.http.paths.

  The system will overwrite the entire path / name or its prefix based on the pathType value: pathType: Exact or pathType: Prefix, respectively.

  Example

  Specify the replacement instructing the load balancer to route incoming requests to backends with specific API versions:

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

  Application Load Balancer will apply this replacement rule to all HTTP routers created for the Ingress resource.

• ingress.alb.yc.io/upgrade-types

  Upgrade HTTP header values of incoming requests supported by the load balancer. Specify these values as a comma-separated list.

  For example, you can use this annotation to enable WebSocket support:

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

  Application Load Balancer will apply the Upgrade values to all HTTP routers created for the Ingress resource.

• ingress.alb.yc.io/request-timeout

  Maximum duration for a connection between a load balancer node and a backend. Once this timeout expires, the load balancer will respond to the client with 504 Gateway Timeout.

  The default value is 60s.

  Application Load Balancer will apply this timeout to all HTTP routers created for the Ingress resource.

• ingress.alb.yc.io/idle-timeout

  Maximum inactivity time for a connection between a load balancer node and a backend. Once this timeout expires, the load balancer will respond to the client with 504 Gateway Timeout.

  If this annotation is omitted, a connection can remain idle for any length of time before the timeout, i.e., the ingress.alb.yc.io/request-timeout annotation.

  Application Load Balancer will apply this timeout to all HTTP routers created for the Ingress resource.

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

  Appends a string to the response header value. To specify the header and string, use this format:

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

  Where:

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

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

  Replaces the response header value. To specify the header and its new value, use this 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

  Renames the response header. To specify the header and its new name, use this format:

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

  Where:

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

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

  Removes the response header. To specify the header to remove, use this 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

  Appends a string to the request header value. To specify the header and string, use this format:

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

  Where:

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

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

  Replaces the request header value. To specify the header and its new value, use this 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. To specify the header and its new name, use this format:

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

  Where:

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

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

  Removes the request header. To specify the header to remove, use this 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

  Enables support for Yandex Smart Web Security, including DDoS protection, WAF, and resource overload protection.

  Note

  To connect your security profile to an Application Load Balancer virtual host, the service account used by 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.

  This service checks HTTP requests to a protected resource through an L7 load balancer virtual host. Depending on check results, it forwards the requests to the protected resource, blocks them, or sends them to Yandex SmartCaptcha for additional verification.

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

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

  This profile contains verification conditions and actions applied to incoming HTTP requests following the check 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. This setting only applies when pathType is set to Exact.

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

  Specifies the panic mode threshold. If the percentage of healthy endpoints falls below the specified threshold, it will trigger the panic mode.

  The default value is 0, which means the panic mode will never be activated.

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

  Percentage of incoming traffic the load balancer forwards to its availability zone backends. The remaining traffic is evenly distributed across other availability zones.

  The default value is 0.

  For more information on locality-aware routing, see this guide.

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

  Maximum total number of resource units. By default, it is unlimited. Make sure this value is no less than 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

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

  Learn more about the autoscaling settings here.

• ingress.alb.yc.io/session-affinity-header

  HTTP header for session affinity.

  • name: HTTP header name.

• ingress.alb.yc.io/session-affinity-cookie

  Cookie parameters for session affinity.

  • name: Cookie name.

  • ttl: Cookie lifetime. The value must be specified with units of measurement, e.g., 300ms or 1.5h. Acceptable units of measurement include:

    • ns, nanoseconds
    • us, microseconds
    • ms, milliseconds
    • s, seconds
    • m, minutes
    • h, hours

  The parameters are given as a comma-separated list. Here is an example:

  ...
  annotations:
    ingress.alb.yc.io/session-affinity-cookie: name=X-Example,ttl=30m
    ...
  

• ingress.alb.yc.io/session-affinity-connection

  Indicator of using a client IP address for session affinity.

  • source-ip: true or false.

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>

Pre-0.2.0 ALB Ingress Controller versions map each backend group to a distinct combination of host, http.paths.path, and http.paths.pathType values. ALB Ingress Controller 0.2.0 and later maps backend groups directly to the backend.service configuration, i.e., IngressBackend. This may cause collisions when upgrading the controller. To avoid them, check the upgrade restrictions for your infrastructure.

IngressBackendIngressBackend

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

DefaultBackendDefaultBackend

Default backend for requests if no incoming traffic distribution rules are specified. If the spec.rules field is not specified in the Ingress description, the spec.defaultBackend field becomes mandatory.

The default backend handles requests if the domain name and requested resource do not match the ones set in the rules.

The spec.defaultBackend field defines either a service backend, i.e., service, or a backend group, i.e., resource. Specify this field 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 log discard rule settings:

• httpCodes: HTTP codes.
• httpCodeIntervals: HTTP code classes.
• grpcCodes: gRPC codes.
• discardPercent: Log discard rate.