Ingress resource fields and annotations

The Ingress resource defines rules for incoming traffic distribution between 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 the relevant Kubernetes article.

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>

Metadata.annotationsMetadata.annotations

Annotations are collections of key:value pairs for assigning metadata to objects. Annotation values have 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 a noarchive,nofollow,noindex X-Robots response header, 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 the relevant Kubernetes article.

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 combine Ingress resources into a group to avoid creating load balancers for each individual resource. For more information about the group name format, see the relevant Kubernetes article.

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

  A load balancer’s subnets must all be in the same network. You cannot specify more than one network per availability zone.

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

  Load balancer Virtual Private Cloud security groups. 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., ingress.alb.yc.io/group-name, uses all security groups specified in their annotations.

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

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

  Specifying the load balancer public IP address.

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

  With auto setting, 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., ingress.alb.yc.io/internal-ipv4-address annotation, but not both.

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

  Configuring a load balancer with an 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., ingress.alb.yc.io/external-ipv4-address annotation, but not both.

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

  Load balancer IP subnet ID.

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

• ingress.alb.yc.io/protocol

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

  • 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 these settings, create the IngressGroupSettings resource.

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

  Ingress resource number. Ingress group resource 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

  For ALB Ingress Controllers v0.2.0 or later, you can only use this annotation in the Service object.

  Annotations applied to Ingress resources sharing the same service and backend group settings will be processed correctly. However, this mechanism is obsolete and will not be supported going forward.

  Encryption protocol for connections between the load balancer and backends specified in Ingress directly, as opposed to the HttpBackendGroup.

  The acceptable annotation value is tls: TLS without certificate validation.

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

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

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

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

  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

  The Upgrade HTTP header values of incoming requests supported by the load balancer. Specify them 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 configuration 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 time 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 configuration 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 time 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., ingress.alb.yc.io/request-timeout annotation.

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

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

  Appends a string value to the response header. Specify the target header and the string to append in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: String to append.

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

  Overwrites the response header value. Specify the target header and its replacement value in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: New header value.

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

  Renames the response header. Specify the target header and its new name in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: New header name.

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

  Removes the response header. Specify the header to be removed in the following format:

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

  Where <key> is the name of the header to be removed.

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

  Appends a string value to the request header. Specify the target header and the string to append in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: String to append.

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

  Replaces the request header value. Specify the target header and its replacement value in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: New header value.

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

  Renames the request header. Specify the target header and its new name in the following format:

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

  Where:

  • <key>: Response header.
  • <value>: New header name.

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

  Removes the request header. Specify the header to be removed in the following format:

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

  Where <key> is the name of the header to be removed.

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

  This service checks HTTP requests sent to the protected resource through the 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 validation conditions and actions performed on incoming HTTP requests following the check results.

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

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

  If set to true, enables RE2 regular expression support for matching the request path. This setting only works when the 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, meaning the panic mode will never be activated.

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

  Share of incoming traffic the load balancer will forward to its availability zone backends. The remaining traffic will be evenly distributed across other availability zones.

  The default value is 0.

  Read more about locality-aware routing here.

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

  Resource unit maximum total. By default, it is unlimited. Make sure this value is no less than (number of load balancer availability zones) × (minimum number of resource units per zone).

  Learn more about the autoscaling settings here.

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

  Resource unit minimum 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>

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 Controllers v0.2.0 and later map backend groups directly to the backend.service configuration, i.e., IngressBackend. This may cause collisions when upgrading the ALB Ingress Controller. To avoid them, check the upgrade restrictions applying to 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 that do not match any ingress traffic rules. If the spec.rules field is undefined in the Ingress description, the spec.defaultBackend field becomes mandatory to ensure all traffic has a valid destination.

The default backend handles requests when no rules are defined in the Ingress or the request’s domain/path matches no existing rules.

The spec.defaultBackend field defines either a service backend, i.e.,service, or a backend group, i.e., resource. Configure this field using the same schema 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.