This reference covers all annotations supported by Application Load Balancer (ALB) Ingresses and the fields of the AlbConfig custom resource. Use these annotations to configure health checks, forwarding rules, session persistence, and more.
All annotation values in Kubernetes are strings. When setting boolean or integer values, quote them in YAML:'true','false','5'. JSON values must also be quoted:'[{"HTTP": 80}]'.
Annotations quick reference
The following table lists all ALB Ingress annotations. Click an annotation name to jump to its full description.
Annotations supported by ALB Ingresses
Health check
These annotations configure health checks for backend server groups.
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/healthcheck-enabled |
true | false |
false |
Enables health checks for backend server groups. |
alb.ingress.kubernetes.io/healthcheck-path |
string | / |
The path to which health check requests are sent. |
alb.ingress.kubernetes.io/healthcheck-protocol |
HTTP | TCP
|
HTTP |
The protocol used for health checks. |
alb.ingress.kubernetes.io/healthcheck-method |
HEAD | POST | GET |
HEAD |
The HTTP method used for health checks. |
alb.ingress.kubernetes.io/healthcheck-httpcode |
http_2xx, http_3xx, http_4xx, http_5xx
|
http_2xx |
The HTTP status codes that indicate a healthy backend. Specify one or more values as a comma-separated string. |
alb.ingress.kubernetes.io/healthcheck-timeout-seconds |
1–300 |
5 |
The health check timeout in seconds. |
alb.ingress.kubernetes.io/healthcheck-interval-seconds |
1–50 |
2 |
The interval between health checks in seconds. |
alb.ingress.kubernetes.io/healthy-threshold-count |
2–10 |
3 |
The number of consecutive successful health checks required before a backend is considered healthy. |
alb.ingress.kubernetes.io/unhealthy-threshold-count |
2–10 |
3 |
The number of consecutive failed health checks required before a backend is considered unhealthy. |
alb.ingress.kubernetes.io/healthcheck-connect-port |
0–65535 |
0 |
The port used for health checks. Set to 0 to use the backend server's own port. |
Redirect
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/ssl-redirect |
true | false |
false |
Redirects HTTP requests (port 80) to HTTPS (port 443) with a 301 status code. |
Backend protocol
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/backend-protocol |
http | https | grpc |
http |
The protocol used to communicate with backend server groups. HTTP listeners support http and https. HTTPS listeners support http, https, and grpc. QUIC listeners support http only. |
Rewrite
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/rewrite-target |
string | None | Overwrites the request path before forwarding to the backend. |
Listeners
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/listen-ports |
JSON array | '[{"HTTP": 80},{"HTTPS": 443}]' |
Associates listener protocols with ports. Valid values: '[{"HTTP": 80}]', '[{"HTTPS": 443}]', '[{"HTTP": 80},{"HTTPS": 443}]', '[{"QUIC": 443}]'. |
Priorities
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/order |
1–1000 |
10 |
The priority of forwarding rules. |
Canary
Use these annotations to route a subset of traffic to a canary deployment for staged rollouts.
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/canary |
true | false |
false |
Enables canary routing for this Ingress. Must be set to true before other canary annotations take effect. |
alb.ingress.kubernetes.io/canary-by-header |
string | None | The header of the requests that are routed to the canary. |
alb.ingress.kubernetes.io/canary-by-header-value |
string | None | The value of the header of the requests that are routed to the canary. |
alb.ingress.kubernetes.io/canary-by-cookie |
string | None | The cookie of the requests that are routed to the canary. |
alb.ingress.kubernetes.io/canary-weight |
integer (0–100) |
None | The percentage of requests to route to the canary. Specify an integer between 0 and 100. |
Session persistence
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/sticky-session |
true | false |
false |
Enables session persistence (sticky sessions). |
alb.ingress.kubernetes.io/sticky-session-type |
Insert | Server |
Insert |
The method that is used to handle a cookie. |
alb.ingress.kubernetes.io/cookie-timeout |
1–86400 |
1000 |
The session persistence timeout in seconds. |
Load balancing
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/backend-scheduler |
wrr | wlc | sch | uch |
wrr |
The load balancing algorithm. wrr = weighted round-robin, wlc = weighted least connections, sch = source IP address hash, uch = URI hash. |
alb.ingress.kubernetes.io/backend-scheduler-uch-value |
string | None | This annotation is available when the load balancing algorithm is set to uch. |
Cross-origin resource sharing (CORS)
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/enable-cors |
true | false |
false |
Enables CORS for this Ingress. |
alb.ingress.kubernetes.io/cors-allow-origin |
string | * |
The origins from which you want to allow cross-domain requests. |
alb.ingress.kubernetes.io/cors-expose-headers |
string array | None | The response headers that can be exposed to the browser. |
alb.ingress.kubernetes.io/cors-allow-methods |
GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH |
"GET, PUT, POST, DELETE, PATCH, OPTIONS" |
The HTTP methods allowed in cross-domain requests. Specify one or more methods as a comma-separated string. |
alb.ingress.kubernetes.io/cors-allow-credentials |
true | false |
true |
Specifies whether credentials (cookies, authorization headers) are included in cross-domain requests. |
alb.ingress.kubernetes.io/cors-max-age |
–1 to 172800 |
172800 |
The maximum time in seconds that the browser caches preflight request results. |
alb.ingress.kubernetes.io/cors-allow-headers |
string array | "DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization" |
The request headers allowed in cross-domain requests. |
Custom forwarding
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/actions.{svcName} |
JSON | None | Custom forwarding actions for the named service. Replace {svcName} with the service name. |
alb.ingress.kubernetes.io/conditions.{svcName} |
JSON | None | Custom forwarding conditions for the named service. Replace {svcName} with the service name. |
alb.ingress.kubernetes.io/rule-direction.{svcName} |
Request | Response |
Request |
The direction in which the custom forwarding rule applies. |
Other annotations
| Annotation | Valid value | Default | Description |
|---|---|---|---|
alb.ingress.kubernetes.io/backend-keepalive |
true | false |
false |
Enables persistent TCP connections between the load balancer and backend servers. |
alb.ingress.kubernetes.io/traffic-limit-qps |
1–100,000 |
None | QPS throttling limit for this Ingress. |
alb.ingress.kubernetes.io/use-regex |
true | false |
false |
Allows regular expressions in the path field. Valid only when the path type is Prefix. |
AlbConfig fields
An AlbConfig is a CustomResourceDefinition (CRD) that describes an ALB instance and its listeners. The following tables cover all fields.
AlbConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
apiVersion |
alibabacloud.com/v1 |
None | The API version of the object. |
kind |
AlbConfig |
None | The REST resource type of the object. |
metadata |
ObjectMeta | None | Standard Kubernetes object metadata. For details, see metadata. |
spec |
AlbConfigSpec | None | The attributes of the ALB instance and its listeners. |
status |
AlbConfigStatus | None | The current status of the ALB instance, written after reconciliation. |
AlbConfigSpec
| Field | Valid value | Default | Description |
|---|---|---|---|
config |
LoadBalancerSpec | None | The attributes of the ALB instance. |
listeners |
ListenerSpec | None | The attributes of the ALB instance's listeners. |
LoadBalancerSpec
| Field | Valid value | Default | Description |
|---|---|---|---|
id |
string | "" |
The ID of the ALB instance. The ALB instance can be reused if an instance ID is specified. |
name |
string | k8s-{namespace}-{name}-{hashCode} |
The name of the ALB instance. |
addressAllocatedMode |
Dynamic | Fixed |
Dynamic |
The IP address allocation mode of the ALB instance. |
addressType |
Internet | Intranet |
Internet |
The network type of the IPv4 CIDR block. |
ipv6AddressType |
Internet | Intranet |
Intranet |
The network type of the IPv6 CIDR block. |
addressIpVersion |
IPv4 | DualStack |
IPv4 |
The IP protocol version of the ALB instance. |
resourceGroupId |
string | Default resource group | The ID of the resource group to which the ALB instance belongs. |
edition |
Standard | StandardWithWaf |
Standard |
The feature edition of the ALB instance. |
deletionProtectionEnabled |
*bool |
null |
Reserved. Not configurable. |
forceOverride |
*bool |
false |
In reuse mode, forcefully overwrites the attributes of the ALB instance. |
listenerForceOverride |
*bool |
null |
Specifies whether to forcefully overwrite the attributes of the listeners in reuse mode. |
zoneMappings |
ZoneMapping | None | The zone and elastic IP address (EIP) configuration. |
accessLogConfig |
AccessLogConfig | None | The access log collection configuration. |
billingConfig |
BillingConfig | None | The billing configuration. |
modificationProtectionConfig |
ModificationProtectionConfig | None | The read-only protection configuration. |
tags |
Tag | None | Tags to apply to the ALB instance. |
ZoneMapping
| Field | Valid value | Default | Description |
|---|---|---|---|
vSwitchId |
string | "" |
Required. The ID of the vSwitch in the zone. |
zoneId |
string | "" |
The zone of the vSwitch. Set automatically. |
allocationId |
string | "" |
The ID of the EIP to associate with this zone. |
eipType |
string | "" |
Reserved. |
AccessLogConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
logStore |
string | "" |
The name of the Simple Log Service Logstore. |
logProject |
string | "" |
The name of the Simple Log Service Log Project. |
BillingConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
internetBandwidth |
int | 0 |
Reserved. |
internetChargeType |
string | "" |
Reserved. |
payType |
PostPay |
PostPay |
The billing method. Only pay-as-you-go (PostPay) is supported. |
bandWidthPackageId |
string | "" |
The ID of the Internet Shared Bandwidth instance to associate. The association cannot be removed after it is set. |
ModificationProtectionConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
reason |
string | "" |
Reserved. |
status |
string | "" |
Reserved. |
Tag
| Field | Valid value | Default | Description |
|---|---|---|---|
key |
string | "" |
The tag key. |
value |
string | "" |
The tag value. |
ListenerSpec
| Field | Valid value | Default | Description |
|---|---|---|---|
port |
int | string | 0 |
Required. The listening port. |
protocol |
HTTP | HTTPS | QUIC |
"" |
Required. The listener protocol. |
gzipEnabled |
null | true | false |
null |
Enables response compression. |
http2Enabled |
null | true | false |
null |
Enables HTTP/2 on the listener. |
securityPolicyId |
string | "" |
The ID of the TLS security policy to apply. |
idleTimeout |
int | 60 |
The idle connection timeout in seconds. A value of 0 uses the default. |
requestTimeout |
int | 60 |
The request timeout in seconds. |
description |
string | ingress-auto-listener-{port} |
The name of the listener. |
certificates |
Certificate | null |
The server certificate associated with the listener. |
xForwardedForConfig |
XForwardedForConfig | None | The X-Forwarded-For header configuration. |
aclConfig |
AclConfig | None | The access control configuration. |
quicConfig |
QuicConfig | None | The QUIC listener configuration. |
loadBalancerId |
string | "" |
Reserved. |
caEnabled |
bool | false |
Reserved. |
defaultActions |
Action | null |
Reserved. |
caCertificates |
Certificate | null |
Reserved. |
logConfig |
LogConfig | None | Reserved. |
QuicConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
quicUpgradeEnabled |
bool | false |
Specifies whether to enable QUIC upgrades. |
quicListenerId |
string | "" |
The QUIC listener. |
Certificate
| Field | Valid value | Default | Description |
|---|---|---|---|
IsDefault |
bool | false |
Marks this certificate as the default. Each service or system can have only one default certificate. |
CertificateId |
string | "" |
The ID of the certificate. |
XForwardedForConfig
All fields default to false unless otherwise noted. The *Alias fields are only valid when their corresponding *Enabled field is set to true.
| Field | Valid value | Default | Description |
|---|---|---|---|
XForwardedForEnabled |
bool | false |
Enables the X-Forwarded-For header to pass the client IP address to backends. |
XForwardedForProtoEnabled |
bool | false |
Enables the X-Forwarded-Proto header to pass the listener protocol to backends. |
XForwardedForSLBIdEnabled |
bool | false |
Enables the X-Forwarded-For-SLB-ID header to pass the ALB instance ID to backends. |
XForwardedForSLBPortEnabled |
bool | false |
Enables the X-Forwarded-Port header to pass the listener port to backends. |
XForwardedForClientSrcPortEnabled |
bool | false |
Enables the X-Forwarded-Client-Port header to pass the client port to backends. |
XForwardedForClientCertSubjectDNEnabled |
bool | false |
Enables the X-Forwarded-Clientcert-subjectdn header to pass the client certificate owner information to backends. |
XForwardedForClientCertSubjectDNAlias |
string | "" |
A custom header name to use instead of X-Forwarded-Clientcert-subjectdn. Valid only when XForwardedForClientCertSubjectDNEnabled is true. |
XForwardedForClientCertIssuerDNEnabled |
bool | false |
Enables the X-Forwarded-Clientcert-issuerdn header to pass the client certificate authority information to backends. |
XForwardedForClientCertIssuerDNAlias |
string | "" |
A custom header name to use instead of X-Forwarded-Clientcert-issuerdn. Valid only when XForwardedForClientCertIssuerDNEnabled is true. |
XForwardedForClientCertFingerprintEnabled |
bool | false |
Enables the X-Forwarded-Clientcert-fingerprint header to pass the client certificate fingerprint to backends. |
XForwardedForClientCertFingerprintAlias |
string | "" |
A custom header name to use instead of X-Forwarded-Clientcert-fingerprint. Valid only when XForwardedForClientCertFingerprintEnabled is true. |
XForwardedForClientCertClientVerifyEnabled |
bool | false |
Enables the X-Forwarded-Clientcert-clientverify header to pass the client certificate verification result to backends. |
XForwardedForClientCertClientVerifyAlias |
string | "" |
A custom header name to use instead of X-Forwarded-Clientcert-clientverify. Valid only when XForwardedForClientCertClientVerifyEnabled is true. |
AclConfig
| Field | Valid value | Default | Description |
|---|---|---|---|
aclName |
string | None | The name of the network ACL (used in AclEntry mode). |
aclType |
Black | White |
"" |
The ACL type: Black for a blocklist, White for an allowlist. |
aclEntries |
string | null |
The ACL rules to apply inline. |
aclIds |
string array | null |
The IDs of existing network ACLs to apply. |
AlbConfigStatus
The status field is written after reconciliation and reflects the current state of the ALB instance.
| Field | Output | Description |
|---|---|---|
loadBalancer |
LoadBalancerStatus | The status of the ALB instance. |
LoadBalancerStatus
| Field | Output | Description |
|---|---|---|
dnsname |
string | The DNS name of the ALB instance. |
id |
string | The ID of the ALB instance. |
listeners |
ListenerStatus | The status of the listeners. |
ListenerStatus
| Field | Output | Example | Description |
|---|---|---|---|
portAndProtocol |
string | 80/HTTP |
The listener port and protocol. |
certificates |
AppliedCertificate | None | The certificates associated with the listener. |
AppliedCertificate
| Field | Output | Example | Description |
|---|---|---|---|
certificateId |
string | xxxx-cn-hangzhou |
The ID of the certificate. |
isDefault |
bool | true |
Whether this is the default certificate for the listener. |
What's next
-
To get started with ALB Ingresses, see Access services by using an ALB Ingress.
-
For examples of advanced configurations using these annotations, see Advanced ALB Ingress configurations.