Ingress fields and annotations
The Ingress
resource defines the rules for distributing incoming traffic to 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. This reference describes the fields and the annotations of the resource that a Application Load Balancer Ingress controller interfaces with. For a complete reference on the resource, please see the Kubernetes documentation
Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: <string>
annotations:
...
spec: <IngressSpec>
Where:
-
apiVersion
:networking.k8s.io/v1
-
kind
:Ingress
-
metadata
(ObjectMeta
, required)Resource metadata.
-
name
(string
, required)Resource name. For more information about format, please see the Kubernetes documentation
.Does not match the balancer name in Application Load Balancer.
-
annotations
(map[string]string
, required)Resource annotation. For more information, see below.
-
-
spec
(IngressSpec
, required)Resource specification. For more information, see below.
Annotations (metadata.annotations)
metadata:
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/transport-security: <string>
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>
Where:
-
ingress.alb.yc.io/group-name
(string
, required)Name of an
Ingress
resource group combined in a single load balancer. For more information about format, please see the Kubernetes documentation .The field is required even if the load balancer uses a single
Ingress
. -
ingress.alb.yc.io/subnets
(string
)List of Virtual Private Cloud subnets the load balancer is located on. Subnet IDs are provided as a comma-separated list, such as:
ingress.alb.yc.io/subnets: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1
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
(string
)List of Virtual Private Cloud security groups for a load balancer. Group IDs are provided in a comma-separated list, such as:
ingress.alb.yc.io/security-groups: b0c2kotoidcoh6haf8cu,e2lnhhdj9a0aqmr78d36,e9bud5itjnl8mkjj7td1
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 proper load balancer and Ingress controller operation, the 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
(string
)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
(string
)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, put it in the annotation. For the load balancer to get its IP automatically, specifyauto
.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
(string
)Load balancer private IP subnet ID.
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
(string
)Connection protocol for load balancer and backends described in
Ingress
:http
: HTTP/1.1. Default valuehttp2
: HTTP/2grpc
: gRPC
-
ingress.alb.yc.io/group-settings-name
(string
)Name for the Ingress group settings combined in a single load balancer.
To specify the settings, create an additional resource named
IngressGroupSettings
, such as: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
For more information, see the description of the
logOptions
parameter of the create REST API method for the LoadBalancer resource. -
ingress.alb.yc.io/transport-security
(string
)Connection encryption protocol for load balancer and backends specified in
Ingress
directly (noHttpBackendGroup
):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
(string
)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 path or name type: for
pathType: Exact
, the entire path or name is replaced, forpathType: Prefix
, only the specified initial portion is replaced.For example, to have the load balancer route backend requests to a specific version when handling all incoming API calls, configure 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
(string
)Value of the HTTP
Upgrade
header in all incoming requests supported by the load balancer. 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
(string
)Maximum load balancer node/backend connection timeout. Once the timeout expires, the load balancer responds to client with
504 Gateway Timeout
.Default:
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
(string
)Maximum load balancer node/backend connection idle timeout. Once the timeout expires, the load balancer responds to 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.
IngressSpec
tls:
- hosts:
- <string>
- ...
secretName: <string>
- ...
rules:
- host: <string>
http:
paths:
- path: <string>
pathType: <string>
backend: <IngressBackend>
- ...
Where:
-
tls
([]IngressTLS
)Incoming HTTPS traffic settings: domain name collections and the relevant TLS certificates.
If the field 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. At the same time, the traffic distribution rules for the same domain names, if explicitly specified in other
Ingress
resources lacking thetls
field will be given priority with respect to 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.
-
hosts
([]string
, required)Domain names that the
secretName
TLS certificate corresponds to.The load balancer will create a dedicated listener for each domain name serving 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 matchesfoo.example.com
,foo-bar.example.com
,foo.bar.example.com
,foo.bar.baz.example.com
, etc., but does not matchexample.com
.You cannot replace only a part of a first-level domain name with an asterisk, as in
*foo.example.com
. -
secretName
(string
, required)A reference to a TLS certificate from Yandex Certificate Manager as
yc-certmgr-cert-id-<certificate ID>
. This is the name a secret with a certificate is available as in Managed Service for Kubernetes.In Certificate Manager, you can have a certificate issued by Let's Encrypt® or load one of your own.
Warning
The
secretName
field only supports references to certificates from Certificate Manager asyc-certmgr-cert-id-<certificate ID>
. Do not enter Kubernetes internal secrets in this field.
-
-
rules
([]IngressRule
, required)A list of rules for distributing incoming traffic to the backends as a function of the domain names (
host
field) and the resource being requested (http.paths
field).In Application Load Balancer, the rules correspond to HTTP router virtual hosts.
-
host
(string
, required)Domain name (value of
Host
header for HTTP/1.1 or:authority
pseudo-header for HTTP/2), to which a rule applies.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 matchesfoo.example.com
,foo-bar.example.com
,foo.bar.example.com
,foo.bar.baz.example.com
, etc., but does not matchexample.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 routing incoming requests with the domain name specified in the
rules.host
field as a function of the resource being requested.-
paths
([]HTTPIngressPath
, required)List of routes: the resources being requested, subject to a rule and the 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, it is recommended that you place 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 sameingress.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 theIngress
resources but notacross
them.-
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 therules.http.paths.path
field.Prefix
: path in request URI or gRPC call name must begin with the value in therules.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. -
path
(string
, required)Reference to the resource being requested:
- For simple HTTP: path in the incoming request URI (if
Exact
) or its prefix (ifPrefix
). - For gRPC (with the
ingress.alb.yc.io/protocol
annotation value equal togrpc
): full gRPC call name (forExact
) or its prefix (forPrefix
). Example:/my.custom.server.Service/Method
.
In both cases, the value must begin with
/
. - For simple HTTP: path in the incoming request URI (if
-
backend
(IngressBackend
, required)Reference to a backend or a group of backends to process requests with the specified domain name or URI path or gRPC call name. For more information, see below.
-
-
-
IngressBackend
service:
name: <string>
port:
name: <string>
number: <int32>
resource:
kind: HttpBackendGroup
name: <string>
apiGroup: alb.yc.io
Where:
-
service
(IngressServiceBackend
)Reference to the Kubernetes service expected to be the backend to process the requests.
The
Service
resource this field points to must be described as in the specification.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 theService
resource. For more detail, please 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 theService
resource. For more detail, please see the resource specification.Either a number or a
name
must be specified for the service port but not both.
-
-
-
resource
(TypedLocalObjectReference
)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 as in the specification.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 theHttpBackendGroup
resource. For more detail, please see the resource specification. -
apiGroup
:alb.yc.io
-