Ingress resource fields and annotations
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 |
|
|
Required. |
|
|
Resource type. |
|
|
Required. |
|
|
Required. |
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 |
|
|
Required. |
|
|
Required. |
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 multipleIngress
resources into one group to avoid creating a load balancer for each individualIngress
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 relevantIngress
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 theseIngress
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/2grpc
: 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 theIngress
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 (withoutHttpBackendGroup
).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 theHttpBackendGroup
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, forpathType: 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 theIngress
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 thetrue
string is provided. Only applies if thepathType
parameter is set toExact
.
IngressSpec
ingressClassName: <string>
tls:
- <IngressTLS>
- ...
rules:
- <IngressRule>
- ...
Field |
Value or type |
Description |
|
|
Name of the IngressClass resource which the An |
|
|
Required. 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 If the field is not specified, only HTTP listeners will be created for the load balancer to handle traffic on port 80. |
|
|
Required. In Application Load Balancer, the rules correspond to HTTP router virtual hosts. |
IngressTLS
hosts:
- <string>
- ...
secretName: <string>
Field |
Value or type |
Description |
|
|
Required. 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 (
You cannot replace only a part of a first-level domain name with an asterisk, as in |
|
|
Required. 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 |
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 |
|
|
Required. To refer to every possible subdomain at any level, replace the first-level domain name with an asterisk (
You cannot replace only a part of a first-level domain name with an asterisk, as in |
|
|
Required. |
|
|
Required. 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 Warning If you create a load balancer for several |
|
|
Required.
In both cases, the value must begin with |
|
|
Required.
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. |
|
|
Required. |
IngressBackend
service:
name: <string>
port:
name: <string>
number: <int32>
resource:
kind: HttpBackendGroup
name: <string>
apiGroup: alb.yc.io
Field |
Value or type |
Description |
|
|
Required. The For the
|
|
|
Required. The Ingress controller implements the For the
|
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.