Contact UsGet started

Ingress resource fields and annotations

Written by
Updated at August 31, 2024

The Ingress resource defines the rules for distributing 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 Kubernetes standard 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.

Ingress

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

Field

Value or type

Description

apiVersion

networking.k8s.io/v1

Required.
Kubernetes API version.

kind

Ingress

Resource type.

metadata

ObjectMeta

Required.
Resource metadata.

spec

IngressSpec

Required.
Resource specification.
Example
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

ObjectMeta

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/security-profile-id: <string>
  ingress.alb.yc.io/use-regex: <string>

Field

Value or type

Description

name

string

Required.
Resource name.
This name is not the balancer name in Application Load Balancer.

annotations

map[string]string

Required.
Resource 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. For more on annotations, see the Kubernetes documentation.

You can provide the following annotations for the 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.

    The field is mandatory 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. 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

    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 proper load balancer and Ingress controller operation, 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 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 resource named IngressGroupSettings.

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

    The 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

    HTTP Upgrade 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 be modified.
    • 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 be modified.
    • <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 be modified.
    • <value>: New header name.

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

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

IngressSpec

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

Field

Value or type

Description

ingressClassName

string

Name of the IngressClass resource which the Ingress resource refers to.

An IngressClass is required to route traffic within a single application using multiple Ingress controllers. If you do not use the ingressClassName parameter but use multiple Ingress controllers, create an IngressClass resource to apply by default.

tls

[]IngressTLS

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

If the filed 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. The traffic distribution rules for the same domain names explicitly specified in other Ingress resources, without the tls field, will be prioritized over 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.

rules

[]IngressRule

Required.
List of rules for distribution of incoming traffic among the backends depending on the domain name (host field) and requested resource (http.paths field).

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

IngressTLS

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

Field

Value or type

Description

hosts

[]string

Required.
Domain names the secretName TLS certificate corresponds to.

The load balancer will create a dedicated listener for each domain name used 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 (*). In this case, the value must be wrapped in quotes.

For instance, the "*.example.com" value matches foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com, etc., but does not match example.com.

You cannot replace only a part of a first-level domain name with an asterisk, as in *foo.example.com.

secretName

string

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

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

If a certificate is not added to Certificate Manager yet, specify a Kubernetes secret containing the certificate in the secretName field. Application Load Balancer Ingress controller will automatically add the certificate to Certificate Manager.

IngressRule

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 (IngressBackend) parameter. This may cause collisions when updating the ALB Ingress Controller. To avoid them, find out whether upgrade restrictions apply to your infrastructure.

Field

Value or type

Description

host

string

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

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

For instance, the "*.example.com" value matches foo.example.com, foo-bar.example.com, foo.bar.example.com, foo.bar.baz.example.com, etc., but does not match example.com.

You cannot replace only a part of a first-level domain name with an asterisk, as in *foo.example.com.

http

HTTPIngressRuleValue

Required.
Rule for distribution of incoming requests with the domain name specified in the host field depending on the requested resource.

http.paths

[]HTTPIngressPath

Required.
List of routes: the requested resources the rule applies to and their 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, we recommend placing 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 between them.

http.paths.path

string

Required.
Reference to the requested resource:

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

In both cases, the value must begin with /.

http.paths.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 the 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.

http.paths.backend

IngressBackend

Required.
Reference to a backend or group of backends to process requests with the specified domain name and URI path or gRPC call name.

IngressBackend

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

Field

Value or type

Description

service

IngressServiceBackend

Required.
Reference to the Kubernetes service expected to process requests as a backend.

The Service resource this field refers to must be described in line with the standard configuration.

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 information, 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 information, see the resource specification.

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

resource

TypedLocalObjectReference

Required.
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 in line with the standard configuration.

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 information, see the resource configuration.

  • apiGroup: alb.yc.io

IngressGroupSettings

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 status codes.
  • httpCodeIntervals: Classes of HTTP status codes.
  • grpcCodes: gRPC codes.
  • discardPercent: Percentage of logs to discard.
Previous
Overview
Next
HttpBackendGroup