Advanced ALB Ingress configurations for ACK managed clusters and ACK dedicated clusters - Container Service for Kubernetes

In an ACK cluster, ALB Ingress provides Layer 7 load balancing for services by managing externally accessible API objects. This topic describes how to use ALB Ingress to forward requests from different domain names or URL paths to different backend server groups, redirect HTTP requests to HTTPS, and implement features such as phased releases.

Index

Feature classification	Configuration examples
ALB Ingress configuration	Configure health checks
Port/Protocol configuration	Configure custom listener ports Support HTTPS and gRPC protocols for backends
Forwarding rule configuration	Forward requests based on domain names Forward requests based on URL paths Configure HTTP to HTTPS redirection Configure regular expressions Configure rewrites Configure forwarding rule priority Implement phased releases using annotations Cross-domain configuration
Advanced configuration	Implement session persistence using annotations Specify a load balancing algorithm for a backend server group Backend persistent connections Support QPS throttling Backend slow start Connection draining Support for mounting IPv6 to backend server groups Disable cross-zone

Forward requests based on domain names

You can create a simple Ingress to forward requests based on a specified standard domain name or an empty domain name. The following sections provide examples.

Forward requests based on a standard domain name

In the following YAML example, the routing path is set to /hello. A request to demo.domain.ingress.top/hello is forwarded to the backend service.

Deploy the following template to create a Service, a deployment, and an Ingress. Requests are forwarded to the Service through the domain name specified in the Ingress.

Expand to view the sample YAML

For clusters of version 1.19 and later

apiVersion: v1
kind: Service
metadata:
  name: demo-service
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - host: demo.domain.ingress.top
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: v1
kind: Service
metadata:
  name: demo-service
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - host: demo.domain.ingress.top
      http:
        paths:
          - backend:
              serviceName: demo-service
              servicePort: 80
            path: /hello
            pathType: ImplementationSpecific

Run the following command to access the service using the specified standard domain name.
Replace ADDRESS with the domain name of the ALB instance. You can run kubectl get ing to obtain the domain name.
```
curl -H "host: demo.domain.ingress.top" <ADDRESS>/hello
```
Expected output:
```
{"hello":"coffee"}
```

Forward requests based on an empty domain name

In the following YAML example, the domain name is empty and the routing path is set to /hello. A request to <ADDRESS>/hello is forwarded to the backend service.

Deploy the following template to create an Ingress.

Expand to view the sample YAML

For clusters of version 1.19 and later

apiVersion: v1
kind: Service
metadata:
  name: demo-service
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - host: ""
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: v1
kind: Service
metadata:
  name: demo-service
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo
  sessionAffinity: None
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - host: ""
      http:
        paths:
          - backend:
              serviceName: demo-service
              servicePort: 80
            path: /hello
            pathType: ImplementationSpecific

Run the following command to access the service using an empty domain name.
Replace ADDRESS with the domain name of the ALB instance. You can run kubectl get ing to obtain the domain name.
```
curl <ADDRESS>/hello
```
Expected output:
```
{"hello":"coffee"}
```

Forward requests based on URL paths

ALB Ingress supports forwarding requests based on URLs. You can set different URL matching policies using the pathType field. The pathType field supports the following three matching types.

Exact match (Exact): Exactly matches the request URL path.
Default (ImplementationSpecific): The specific logic is determined by the Ingress controller. In ALB Ingress Controller, this is an exact match (Exact). If the path field is not specified, ALB Ingress uses / as the default path.
Prefix match (Prefix): Matches the prefix of the request URL path.

Important

If pathType is set to Exact or Prefix, you must set the path to a non-empty absolute path. Otherwise, the Ingress resource cannot be created because of a validation failure.
URL matching policies may conflict. In this case, the forwarding rules are sorted by priority before the request is forwarded. For more information, see Configure forwarding rule priority.

Simple paths (/ /foo, /foo/)

Matching type	Rule path (routing rule)	Request path (user access)	Is the rule matched?
Prefix match (Prefix)	/	/ (matches all rules)	Yes
	/foo	/foo /foo/	Yes
	/foo/	/foo /foo/	Yes
	/aaa	/ccc	No, the prefix does not match.
Exact match (Exact) or Default (ImplementationSpecific)	/foo	/foo	Yes
		/bar	No
		/foo/	No
	/foo/	/foo	No

Hierarchical paths (/aaa/bb, /aaa/bbb, /aaa/bbb/)

Matching type	Rule path (routing rule)	Request path (user access)	Is the rule matched?
Prefix match (Prefix)	/aaa/bb	/aaa/bbb	No
	/aaa/bbb	/aaa/bbb	Yes
	/aaa/bbb/	/aaa/bbb	Yes, the trailing slash in the rule path is ignored.
	/aaa/bbb	/aaa/bbb/	Yes, the trailing slash in the request path is matched.
	/aaa/bbb	/aaa/bbb/ccc	Yes, a subpath of the request path is matched.

Set two rule paths at the same time

Matching type	Rule path (routing rule)	Request path (user access)	Is the rule matched?
Prefix match (Prefix)	/ /aaa	/aaa/ccc	Yes, the request path matches the `/` prefix of the rule path.
	/aaa /	/aaa/ccc	Yes, the request path matches the `/aaa` prefix of the rule path.
	/aaa /	/ccc	Yes, the request path matches the `/` prefix of the rule path.
	/aaa /bbb	/ccc	No, the prefix does not match.

The following sections provide examples of the three matching types:

Prefix match (Prefix)

The URL path uses a prefix matching method where path segments are separated by /. The matching is case-sensitive and compares each element in the path segment by segment.

In the following YAML example, the routing rule is configured as /. All paths that start with /, such as /hello, are matched.

Deploy the following template to create an Ingress.

Expand to view the sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-path-prefix
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
        - path: /
          backend:
            service:
              name: demo-service
              port:
                number: 80
          pathType: Prefix

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo-path-prefix
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
        - path: /
          backend:
            serviceName: demo-service
            servicePort: 80
          pathType: Prefix

Run the following command to access the service.
Replace ADDRESS with the domain name of the ALB instance. You can run kubectl get ing to obtain the domain name.
```
curl <ADDRESS>/hello
```

Expected output:

{"hello":"coffee"}

Exact match (Exact) or Default (ImplementationSpecific)

In the following YAML example, the routing rule is configured as /hello. Only the /hello path is matched.

Deploy the following template to create an Ingress.

Expand to view the sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-path
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
        - path: /hello
          backend:
            service:
              name: demo-service
              port: 
                number: 80
          pathType: Exact

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo-path
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
        - path: /hello
          backend:
            serviceName: demo-service
            servicePort: 80
          pathType: Exact

Run the following command to access the service.
Replace ADDRESS with the domain name of the ALB instance. You can run kubectl get ing to obtain the domain name.
```
curl <ADDRESS>/hello
```
Expected output:
```
{"hello":"coffee"}
```

Configure health checks

ALB Ingress supports health checks. You can configure health checks by setting the following annotations.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/healthcheck-enabled: "true"
    alb.ingress.kubernetes.io/healthcheck-path: "/"
    alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP"
    alb.ingress.kubernetes.io/healthcheck-httpversion: "HTTP1.1"
    alb.ingress.kubernetes.io/healthcheck-method: "HEAD"
    alb.ingress.kubernetes.io/healthcheck-code: "http_2xx"
    alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5"
    alb.ingress.kubernetes.io/healthcheck-interval-seconds: "2"
    alb.ingress.kubernetes.io/healthy-threshold-count: "3"
    alb.ingress.kubernetes.io/unhealthy-threshold-count: "3"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      # Configure the context path
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      # Configure the context path
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/healthcheck-enabled: "true"
    alb.ingress.kubernetes.io/healthcheck-path: "/"
    alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP"
    alb.ingress.kubernetes.io/healthcheck-method: "HEAD"
    alb.ingress.kubernetes.io/healthcheck-httpcode: "http_2xx"
    alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5"
    alb.ingress.kubernetes.io/healthcheck-interval-seconds: "2"
    alb.ingress.kubernetes.io/healthy-threshold-count: "3"
    alb.ingress.kubernetes.io/unhealthy-threshold-count: "3"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      # Configure the context path.
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      # Configure the context path.
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

The following code block shows an example of the annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/healthcheck-enabled: "true"
    alb.ingress.kubernetes.io/healthcheck-path: "/"
    alb.ingress.kubernetes.io/healthcheck-protocol: "HTTP"
    alb.ingress.kubernetes.io/healthcheck-httpversion: "HTTP1.1"
    alb.ingress.kubernetes.io/healthcheck-method: "HEAD"
    alb.ingress.kubernetes.io/healthcheck-code: "http_2xx"
    alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5"
    alb.ingress.kubernetes.io/healthcheck-interval-seconds: "2"
    alb.ingress.kubernetes.io/healthy-threshold-count: "3"
    alb.ingress.kubernetes.io/unhealthy-threshold-count: "3"
spec:
... ...

Parameter	Description	Default value
`alb.ingress.kubernetes.io/healthcheck-enabled`	Specifies whether to enable health checks for the backend server group. `true`: Enables health checks. `false`: Disables health checks.	`false`
`alb.ingress.kubernetes.io/healthcheck-path`	The health check path.	`/`
`alb.ingress.kubernetes.io/healthcheck-protocol`	The protocol used for health checks. `HTTP`: Uses the HTTP protocol. It sends HEAD or GET requests to simulate browser access and check if the server application is healthy. `HTTPS`: Uses the HTTPS protocol. It sends HEAD or GET requests to simulate browser access and check if the server application is healthy. `TCP`: Uses the TCP protocol. It sends SYN handshake messages to check if the server port is active. `GRPC`: Uses the gRPC protocol. It sends POST or GET requests to check if the server application is healthy.	`HTTP`
`alb.ingress.kubernetes.io/healthcheck-httpversion`	The HTTP protocol version. This parameter is effective when `healthcheck-protocol` is set to `HTTP` or `HTTPS`. `HTTP1.0` `HTTP1.1`	`HTTP1.1`
`alb.ingress.kubernetes.io/healthcheck-method`	The health check method. `HEAD` `POST` `GET` Important If `healthcheck-protocol` is set to `GRPC`, select `POST` or `GET`.	`HEAD`
`alb.ingress.kubernetes.io/healthcheck-httpcode`	The health check status code. The backend server is considered healthy only when the probe request is successful and returns the specified status code. You can enter one or more of the following options. Separate multiple status codes with a comma (,). `http_2xx` `http_3xx` `http_4xx` `http_5xx`	`http_2xx`
`alb.ingress.kubernetes.io/healthcheck-code`	The health check status code. The backend server is considered healthy only when the probe request is successful and returns the specified status code. If you use this parameter with `healthcheck-httpcode`, this parameter takes precedence. The available options depend on the value of `healthcheck-protocol`: `HTTP or HTTPS`: You can enter one or more of the following options. Separate multiple status codes with a comma (,). `http_2xx` `http_3xx` `http_4xx` `http_5xx` `GRPC`: The value range is [0, 99]. You can enter a range of values. You can enter up to 20 ranges. Separate multiple ranges with a comma (,).	`HTTP or HTTPS` Default value: `http_2xx` `GRPC` Default value: `0`
`alb.ingress.kubernetes.io/healthcheck-timeout-seconds`	The health check timeout period in seconds (s). The value range is [1, 300].	`5`
`alb.ingress.kubernetes.io/healthcheck-interval-seconds`	The health check interval in seconds (s). The value range is [1, 50].	`2`
`alb.ingress.kubernetes.io/healthy-threshold-count`	The number of consecutive successful health checks required to declare a backend server as healthy. The value range is [2, 10].	`3`
`alb.ingress.kubernetes.io/unhealthy-threshold-count`	The number of consecutive failed health checks required to declare a backend server as unhealthy. The value range is [2, 10].	`3`
`alb.ingress.kubernetes.io/healthcheck-connect-port`	The port used for health checks.	`0` Note `0` indicates that the port of the backend server is used for health checks.

Configure HTTP to HTTPS redirection

ALB Ingress uses the following annotation to redirect HTTP requests to HTTPS port 443.

Important

This feature can be configured only on HTTP forwarding rules that use listener port 80.
This feature can be used only with annotations related to the custom forwarding actions RemoveHeader, InsertHeader, and cross-domain Cors.
To configure this annotation, you must make sure that an HTTPS listener for port 443 is configured in the AlbConfig. For more information, see Configure ALB listeners through an AlbConfig.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: v1
kind: Service
metadata:
  name: demo-service-ssl
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo-ssl
  sessionAffinity: None
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-ssl
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-ssl
  template:
    metadata:
      labels:
        app: demo-ssl
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo-ssl
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/ssl-redirect: "true"
  name: demo-ssl
  namespace: default
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - ssl.alb.ingress.top
  rules:
    - host: ssl.alb.ingress.top
      http:
        paths:
          - backend:
              service:
                name: demo-service-ssl
                port: 
                  number: 80
            path: /
            pathType: Prefix

For clusters earlier than version 1.19

apiVersion: v1
kind: Service
metadata:
  name: demo-service-ssl
  namespace: default
spec:
  ports:
    - name: port1
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: demo-ssl
  sessionAffinity: None
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-ssl
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-ssl
  template:
    metadata:
      labels:
        app: demo-ssl
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/alb-sample/cafe:v1
          imagePullPolicy: IfNotPresent
          name: demo-ssl
          ports:
            - containerPort: 8080
              protocol: TCP
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/ssl-redirect: "true"
  name: demo-ssl
  namespace: default
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - ssl.alb.ingress.top
  rules:
    - host: ssl.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: demo-service-ssl
              servicePort: 80
            path: /
            pathType: Prefix

Parameter	Description	Annotation example
`alb.ingress.kubernetes.io/ssl-redirect: "true"`	Redirects HTTP requests to HTTPS port 443.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/ssl-redirect: "true" name: demo-ssl ... ...`

Support HTTPS and gRPC protocols for backends

ALB supports HTTPS and gRPC as backend protocols. To use them, you can add the following annotation to your Ingress.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-protocol: "grpc"
  name: demo-alb-ingress
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - demo.alb.ingress.top
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:  
      - path: /
        pathType: Prefix
        backend:
          service:
            name: grpc-demo-svc
            port:
              number: 9080

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-protocol: "grpc"
  name: demo-alb-ingress
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - demo.alb.ingress.top
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: grpc-demo-svc
              servicePort: 9080
            path: /
            pathType: Prefix

Note

After an Ingress is created, the backend protocol cannot be modified. To change the protocol, you must delete the Ingress and create a new one.

Parameter	Description	YAML example
`alb.ingress.kubernetes.io/backend-protocol`	https: The backend service uses the HTTPS protocol. grpc: The backend service uses the gRPC protocol. When you use an Ingress to forward gRPC services, configure an SSL certificate for the domain name and use the TLS protocol for communication.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/backend-protocol: "grpc" name: demo-alb-ingress ... ...`

Configure regular expressions

You can use the alb.ingress.kubernetes.io/use-regex: "true" annotation to enable regular expression mode. Then, you can configure the regular expressions in custom forwarding conditions or actions.

Important

This annotation applies only to path rules with pathType: Prefix.

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/use-regex: "true"  ## Allows the use of regular expressions.
   alb.ingress.kubernetes.io/conditions.<YOUR-SVC-NAME>: | ## Replace <YOUR-SVC-NAME> with the actual Service name. It must be the same as backend.service.name below.
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "~*/pathvalue1", ## Add ~* or ~ before the regular expression as a flag. The content after ~* or ~ is the effective regular expression. ~* indicates a case-sensitive regular expression match, and ~ indicates a case-insensitive regular expression match.
              "/pathvalue2"    ## No ~* is needed for an exact match.
           ]
       }
      }]
  name: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test-path-for-alb
        pathType: Prefix
        backend:
          service:
            name: <YOUR-SVC-NAME> ## <YOUR-SVC-NAME> here must be the same as the service name specified in the custom forwarding condition annotation to indicate the relationship.
            port:
              number: 88

Parameter

Description

alb.ingress.kubernetes.io/use-regex: "true"

Enables regular expressions.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/use-regex: "true"  ## Allows the use of regular expressions.
   alb.ingress.kubernetes.io/conditions.<YOUR-SVC-NAME>: | ## Replace <YOUR-SVC-NAME> with the actual Service name. It must be the same as backend.service.name below.
     [{
       "type": "Path",         ## Supports Host
       "pathConfig": {
           "values": [
              "~*/pathvalue1", ## Add ~* or ~ before the regular expression as a flag. The content after ~* or ~ is the effective regular expression. ~* indicates a case-sensitive regular expression match, and ~ indicates a case-insensitive regular expression match.
              "/pathvalue2"    ## No ~* is needed for an exact match.
           ]
       }
      }]
... ...

alb.ingress.kubernetes.io/conditions.<YOUR-SVC-NAME>

Configures custom forwarding conditions. For more information, see Forwarding conditions.

<YOUR-SVC-NAME> with the actual Service name. It must be the same as backend.service.name below.

Regular expression matching rules:

Matching object	Prefix	Rule example	Client path	Is matched?	Description
Domain name	Starts with `~`	`~test.example.com`	test.EXAMPLE.com	Yes	Domain names support case-insensitive regular expression matching.
Path	Starts with `~`	`~/api`	/API	Yes	Paths support case-insensitive regular expression matching.
Path	Starts with `~*`	`~*/api`	/Api	No	Paths support case-sensitive regular expression matching.

Configure rewrites

ALB Ingress supports the rewrite feature. After ALB Ingress receives a client request, it modifies the path of the request and then sends the request to the backend Service. Rewrites are implemented using the following two annotations:

alb.ingress.kubernetes.io/rewrite-target: /<path>/${number}: Enables rewriting and specifies the rewritten path.
Important
- Use the ${number} format to represent a variable that is obtained from the original path using a regular expression. You can configure one or more variables, such as ${1}, ${2}, or ${3}. You can obtain a maximum of three variables from the original path.
- The pathType of the Ingress must be set to Prefix.
alb.ingress.kubernetes.io/use-regex: Specifies whether to use a regular expression in the path. This is enabled by default after you configure rewrite-target.
- "true": Use regular expressions.
- "false": Do not use regular expressions. If the path contains special characters, such as “%#;!()[]^,”\", the Ingress resource cannot be created.

Configuration examples

Scenario 1: Remove a prefix

In the following YAML example, path: /something(/|$)(.*) uses a regular expression to divide the client request path into three parts:

/something: Matches the prefix to be removed.
(/|$): The first capturing group, which matches the / character or the end of the path ($) that follows /something.
(.*): The second capturing group, which matches all content that follows /something/. It is used in the rewritten path as ${2}.

The rewritten path that is configured in the alb.ingress.kubernetes.io/rewrite-target annotation is / (standard path prefix) + ${2} (content of the second capturing group). The following table describes the path rewrite effect.

Original client path	Does it match the path regular expression?	Rewritten path
`/something`	Matched. The second capturing group is empty.	`/`
`/something/`	Matched. The second capturing group is empty.	`/`
`/something/new`	Matched. The content of the second capturing group is `new`.	`/new`
`/something-new/item`	Not matched. In this example, no routing rule is matched, and ALB Ingress returns a 503 status code.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true" # Allows the path field to use regular expressions.
    alb.ingress.kubernetes.io/rewrite-target: /${2} # This annotation supports regular expression replacement.
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /something(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: rewrite-svc
            port:
              number: 9080

Scenario 2: Capture and rearrange multiple parts

The following example captures and rearranges multiple parts of the path /items/(.*)/(.*)/(.*). It also changes the URL format to a format similar to a POST request without the user noticing. The rewritten path is / (standard path prefix) + ${2} (content of the second capturing group) + ?code= + ${3} (content of the third capturing group). The following table describes the path rewrite effect.

The example explicitly requires four segments in the path. This method requires the client to use a fixed path format.

Original client path	Does it match the path regular expression?	Rewritten path
`/items/electronics/computers/554`	Matched. The content of the second capturing group is `computers`, and the content of the third capturing group is `554`.	`/computers?code=554`.
`/items/produce/fruits/12`	Matched. The content of the second capturing group is `fruits`, and the content of the third capturing group is `12`.	`/fruits?code=12`
`/items/headphones/5`	Not matched. In this example, no routing rule is matched, and ALB Ingress returns a 503 status code.
`/drinks/41`	Not matched. In this example, no routing rule is matched, and ALB Ingress returns a 503 status code.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true" # Allows the path field to use regular expressions.
    alb.ingress.kubernetes.io/rewrite-target: /${2}?code=${3} # This annotation supports regular expression replacement.
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /items/(.*)/(.*)/(.*)
        pathType: Prefix
        backend:
          service:
            name: rewrite-svc
            port:
              number: 9080

Scenario 3: Rewrite multiple paths to a single path

The following example rewrites multiple paths to a single path by matching multiple paths (/app-a(/|$)(.*) and /app-b(/|$)(.*)) with regular expressions. The rewritten path is /app-c/ + ${2} (content of the second capturing group). The following table describes the path rewrite effect.

Original client path	Does it match the path regular expression?	Rewritten path
`/app-a/item1`	Matched. The content of the second capturing group is `item1`.	`/app-c/item1`
`/app-a/item2`	Matched. The content of the second capturing group is `item2`.	`/app-c/item2`
`/app-a` or `/app-a/`	Matched. The second capturing group is empty.	`/app-c/`
`/drinks/41`	Not matched. In this example, no routing rule is matched, and ALB Ingress returns a 503 status code.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true" # Allows the path field to use regular expressions.
    alb.ingress.kubernetes.io/rewrite-target: /app-c/${2} # This annotation supports regular expression replacement.
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /app-a(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: rewrite-svc
            port:
              number: 9080
      - path: /app-b(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: rewrite-svc
            port:
              number: 9080

Scenario 4: Rewrite a domain name

The alb.ingress.kubernetes.io/rewrite-target annotation supports changing only the path. To change other parts of the URL, such as the domain name and parameters, you can use custom forwarding rules.

Verify rewrite rule matching

You can use the sed command to test in advance whether a specific path used by the client matches the regular expression configured in the path and to view the new rewritten path.

This section uses the capturing path /items/(.*)/(.*)/(.*) and rewrite rule /${2}?code=${3} from Scenario 2: Capture and rearrange multiple parts as an example:

Save the following sample command to path2.txt:

/items/electronics/computers/554
/items/produce/fruits/12
/items/headphones/5
/drinks/41

Check whether the paths match and view the rewritten paths:
In the following command, the path regular expression (/items/(.*)/(.*)/(.*)) and the rewritten path (/${2}?code=${3}) from the example are modified. In the sed command, the special character / must be escaped with an escape character \, and the capturing group content is written as \2 instead of ${2}.
```
sed -E 's#\/items\/(.*)\/(.*)\/(.*)#Matched: [&]  --->  Rewritten: [/\2?code=\3]#' path2.txt
```
The expected output is as follows. The first two paths match the rewrite rule and are rewritten to new paths. The last two paths do not match the rewrite rule and are not rewritten.
```
Matched: [/items/electronics/computers/554]  --->  Rewritten: [/computers?code=554]
Matched: [/items/produce/fruits/12]  --->  Rewritten: [/fruits?code=12]
/items/headphones/5
/drinks/41
```

Configure custom listener ports

ALB Ingress supports custom listener ports through an annotation. This allows a service to expose both port 80 (HTTP) and port 443 (HTTPS) at the same time.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
   alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]'
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - demo.alb.ingress.top
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]'
  name: cafe-ingress
spec:
  ingressClassName: alb
  tls:
  - hosts:
    - demo.alb.ingress.top
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: tea-svc
              servicePort: 80
            path: /tea
            pathType: ImplementationSpecific

Important

ALB does not support creating new listeners directly in an Ingress. To ensure that the Ingress works as expected, you must first create the required listener ports and protocols in the AlbConfig. Then, you can associate these listeners with the service in the Ingress. For information about how to create an ALB listener, see Configure ALB listeners through an AlbConfig.

Parameter	Description	YAML example
`alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]'`	Makes the service listen on both port 80 and port 443.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]' ... ...`

Configure forwarding rule priority

By default, the priority of ALB forwarding rules is sorted as follows:

Different Ingresses are sorted by the lexicographical order of namespace/name. A smaller lexicographical order indicates a higher priority.
The namespace is compared first. If the namespaces are the same, the name is compared character by character.
Within the same Ingress, rules are sorted by their order in the rule field. Rules that are configured earlier have higher priority.
```
rules:
  - host: www.example.com
    http: ...
  - host: www.test.com
    http: ...
```

If you do not modify the namespace/name field of the Ingress, you can configure the following Ingress annotation to define the priority of ALB forwarding rules:

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
   alb.ingress.kubernetes.io/order: "2"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "2" 
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: tea-svc
              servicePort: 80
            path: /tea
            pathType: ImplementationSpecific

Parameter

Description

Value range

YAML example

alb.ingress.kubernetes.io/order

Defines the priority of the ALB forwarding rule. A smaller value indicates a higher priority.

The priority of rules within the same listener must be unique.

[1,1000]

Default value: 10

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
   alb.ingress.kubernetes.io/order: "2"
spec:
... ...

Implement phased releases using annotations

ALB supports complex routing and provides phased release capabilities based on headers, cookies, and weights. You can configure the following annotations to flexibly implement various phased release policies. For more information about best practices for phased releases, see Implement phased releases through ALB Ingress.

Parameter	Description	Description
`alb.ingress.kubernetes.io/canary: "true"`	Enables the phased release capability.	Canary traffic can be allocated based on headers, cookies, or weights. The allocation priority is: Header > Cookie > Weight (from highest to lowest). Do not delete the original rule during the phased release process. This can cause service exceptions. After the phased release is verified, update the backend Service in the original Ingress to the new Service, and then delete the canary Ingress.

Allocate canary traffic based on a specified header

Parameter

Description

YAML example

alb.ingress.kubernetes.io/canary-by-header

This rule lets you customize the request header and its corresponding value. You must configure both annotations.

When the header and header-value in the request match the set values, the request traffic is allocated to the canary service endpoint.
Other non-matching requests are allocated to the subsequent canary service according to the canary priority.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "1"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-header: "location"
    alb.ingress.kubernetes.io/canary-by-header-value: "hz"
  name: demo-canary
spec:
... ...

alb.ingress.kubernetes.io/canary-by-header-value

If the request header contains location: hz, the traffic is routed to the canary service. Other requests are allocated to the canary service based on the canary weight policy. The following is a configuration example.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "1"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-header: "location"
    alb.ingress.kubernetes.io/canary-by-header-value: "hz"
  name: demo-canary
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-hello
                port: 
                  number: 80
            path: /hello
            pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "1"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-header: "location"
    alb.ingress.kubernetes.io/canary-by-header-value: "hz"
  name: demo-canary
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              serviceName: demo-service-hello
              servicePort: 80
            path: /hello
            pathType: ImplementationSpecific

Allocate canary traffic based on a specified cookie

Parameter

Cookie value

YAML example

alb.ingress.kubernetes.io/canary-by-cookie

always: All request traffic is allocated to the canary service endpoint.
never: Request traffic is not allocated to the canary service endpoint.

Cookie-based canary releases do not support custom settings, only always and never.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "2"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-cookie: "demo"
  name: demo-canary-cookie
  ... ...

If the request header contains Cookie: demo=always, the traffic is routed to the canary service. If the request header contains Cookie: demo=never, the traffic is not routed to the canary service. The following is a configuration example.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "2"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-cookie: "demo"
  name: demo-canary-cookie
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-hello
                port: 
                  number: 80
            path: /hello
            pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "2"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-cookie: "demo"
  name: demo-canary-cookie
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              serviceName: demo-service-hello
              servicePort: 80
            path: /hello
            pathType: ImplementationSpecific

Allocate traffic by weight

Parameter

Description

YAML example

alb.ingress.kubernetes.io/canary-weight

Sets the percentage of requests to the specified service. The value is an integer from 0 to 100.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "3"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-weight: "50"
  name: demo-canary-weight

The following example configures the weight of the canary service to 50%:

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "3"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-weight: "50"
  name: demo-canary-weight
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-hello
                port: 
                  number: 80
            path: /hello
            pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/order: "3"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-weight: "50"
  name: demo-canary-weight
  namespace: default
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - backend:
              serviceName: demo-service-hello
              servicePort: 80
            path: /hello
            pathType: ImplementationSpecific

Implement session persistence using annotations

ALB Ingress supports session persistence through the following annotations.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"   # When using a custom cookie, the cookie insertion type must be Server.
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - backend:
          service:
            name: tea-svc
            port:
              number: 80
        path: /tea2
        pathType: ImplementationSpecific
      - backend:
          service:
            name: coffee-svc
            port:
              number: 80
        path: /coffee2
        pathType: ImplementationSpecific

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"  # When using a custom cookie, the cookie insertion type must be Server.
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      #Configure the context path.
      - path: /tea2
        pathType: ImplementationSpecific
        backend:
          serviceName: tea-svc
          servicePort: 80
      #Configure the context path.
      - path: /coffee2
        pathType: ImplementationSpecific
        backend:
          serviceName: coffee-svc
          servicePort: 80

The following code block shows an example of the annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"   # When using a custom cookie, the cookie insertion type must be Server.
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
... ...

Parameter	Description	Default value
`alb.ingress.kubernetes.io/sticky-session`	Specifies whether to enable session persistence. `true`: Enabled `false`: The instance is shut down.	`false`
`alb.ingress.kubernetes.io/sticky-session-type`	The method for handling cookies. `Insert`: Inserts a cookie. When a client accesses the service for the first time, Server Load Balancer inserts a cookie (SERVERID) into the HTTP or HTTPS response. When the client accesses the service again with this cookie, Server Load Balancer forwards the request to the previously recorded backend server. `Server`: Rewrites a cookie. If Server Load Balancer detects a custom cookie, it rewrites the original cookie. When the client accesses the service again with the new cookie, Server Load Balancer forwards the request to the previously recorded backend server. Note This parameter is effective when `StickySessionEnabled` for the server group is `true`. For more information about server group parameters, see Create a server group.	`Insert`
`alb.ingress.kubernetes.io/cookie-timeout`	The cookie timeout period in seconds. The value range is [1, 86400]. This annotation is effective when `sticky-session-type` is set to `Insert`.	1000
`alb.ingress.kubernetes.io/cookie`	The custom cookie value. This annotation is required and cannot be empty when `sticky-session-type` is set to `Server`.	""

Specify a load balancing algorithm for a backend server group

ALB Ingress can specify the load balancing algorithm for a backend server group using the following annotation. The possible values and their descriptions are shown in the following table.

Expand to view the full sample YAML

For clusters of version 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # You can set this to wrr, sch, or wlc as needed.
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # This parameter is required only when the load balancing algorithm is uch. It is not needed for wrr, sch, or wlc.
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80

For clusters earlier than version 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # You can also set this to wrr, sch, or wlc as needed.
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # This parameter is required only when the load balancing algorithm is uch. It is not needed for wrr, sch, or wlc.
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: tea-svc
              servicePort: 80
            path: /tea
            pathType: ImplementationSpecific

Parameter	Value	Description
`alb.ingress.kubernetes.io/backend-scheduler`	`wrr`	Weighted round-robin. Backend servers with higher weights are more likely to be polled (default value).	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/backend-scheduler: "uch" # You can set this to wrr, sch, or wlc as needed. alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # This parameter is required only when the load balancing algorithm is uch. It is not needed for wrr, sch, or wlc. spec: ... ...`
	`wlc`	Polling is based on the weight value set for each backend server and the actual load (number of connections) of the backend server. If the weights are the same, the server with fewer connections is prioritized.
	`sch`	Source IP consistent hashing. Requests are distributed based on a hash of the client's source IP. Requests from the same IP address are allocated to the same backend server.
	`uch`	URL parameter consistent hashing. Use the `alb.ingress.kubernetes.io/backend-scheduler-uch-value` annotation to specify the URL parameter for consistent hashing.

Cross-domain configuration

ALB Ingress supports the following annotation parameters to control cross-domain behavior. You can specify allowed sites, request methods, request and response headers, credential carrying, and preflight (OPTIONS) cache time to meet cross-domain access requirements in different security and business scenarios.

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-ingress
  annotations:
    alb.ingress.kubernetes.io/enable-cors: "true"
    alb.ingress.kubernetes.io/cors-expose-headers: ""
    alb.ingress.kubernetes.io/cors-allow-methods: "GET,POST"
    alb.ingress.kubernetes.io/cors-allow-credentials: "true"
    alb.ingress.kubernetes.io/cors-max-age: "600"
    alb.ingress.kubernetes.io/cors-allow-origin: "Allowed-cross-domain-name"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cloud-nodeport
            port:
              number: 80

The following code block shows an example of the annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-ingress
  annotations:
    alb.ingress.kubernetes.io/enable-cors: "true"
    alb.ingress.kubernetes.io/cors-expose-headers: ""
    alb.ingress.kubernetes.io/cors-allow-methods: "GET,POST"
    alb.ingress.kubernetes.io/cors-allow-credentials: "true"
    alb.ingress.kubernetes.io/cors-max-age: "600"
    alb.ingress.kubernetes.io/cors-allow-origin: "Allowed-cross-domain-name"
spec:
... ...

Parameter	Description	Default value
`alb.ingress.kubernetes.io/enable-cors`	Enables CORS cross-domain configuration.	Default value: `"true"`
`alb.ingress.kubernetes.io/cors-allow-origin`	The sites that are allowed to access server resources through a browser. Separate sites with a comma (,). A single value must start with http:// or https:// followed by a valid domain name or a first-level wildcard domain name. IP addresses are not supported.	Default value: `*` Example: `alb.ingress.kubernetes.io/cors-allow-origin: "https://example.com:4443, http://aliyundoc.com, https://example.org:1199"`
`alb.ingress.kubernetes.io/cors-allow-methods`	The allowed cross-domain methods. The methods are not case-sensitive. Separate cross-domain methods with a comma (,).	Default value: `GET, PUT, POST, DELETE, PATCH, OPTIONS` Example: `alb.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"`
`alb.ingress.kubernetes.io/cors-allow-headers`	The request headers that can be propagated across domains. You can set this to `*` or configure one or more values. Separate multiple values with a comma (,). A single value can only contain uppercase letters, lowercase letters, and numbers. It cannot start or end with an underscore (_) or a hyphen (-). The maximum length is 32 characters.	Default value: `DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization` Example: `alb.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"`
`alb.ingress.kubernetes.io/cors-expose-headers`	The list of headers that can be exposed. You can set this to `*` or configure one or more values. Separate multiple values with a comma (,). A single value can only contain uppercase letters, lowercase letters, and numbers. It cannot start or end with an underscore (_) or a hyphen (-). The maximum length is 32 characters.	Default value: `""` Example: `alb.ingress.kubernetes.io/cors-expose-headers: "*,X-CustomResponseHeader"`
`alb.ingress.kubernetes.io/cors-allow-credentials`	Specifies whether to allow credentials to be carried during cross-domain access.	Default value: `true` Example: `alb.ingress.kubernetes.io/cors-allow-credentials: "false"`
`alb.ingress.kubernetes.io/cors-max-age`	For non-simple requests, this sets the maximum cache time in seconds for OPTIONS preflight requests in the browser. The value range is [0, 172800].	Default value: `172800`

Backend persistent connections

Traditional load balancing uses short-lived connections to access backend server groups. Each request requires a TCP connection to be established and terminated. This makes network connectivity a bottleneck for high-performance systems. With backend persistent connection support from the load balancer, the resource consumption for handling the connection layer is greatly reduced, which significantly improves processing performance. The following code block shows a sample configuration:

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-ingress
  annotations:
    alb.ingress.kubernetes.io/backend-keepalive: "true"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cloud-nodeport
            port:
              number: 80

Parameter	Description	YAML example
`alb.ingress.kubernetes.io/backend-keepalive: "true"`	Enables backend persistent connections. This reduces TCP connection establishment and termination for each request, lowers resource consumption, and improves the processing capability of high-performance systems.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: alb-ingress annotations: alb.ingress.kubernetes.io/backend-keepalive: "true" spec:`

Support for mounting IPv6 to backend server groups

After you enable IPv6 mounting for a server group, to mount both IPv4 and IPv6 pods to the server group, you must make sure that the cluster has dual-stack capability enabled. For more information, see Create an ACK managed cluster.

Note

The following limitations apply when you enable IPv6 mounting:

If the VPC where the server group is located does not have IPv6 enabled, you cannot enable IPv6 mounting for the server group.
When you mount IP-type or Function Compute-type server groups using custom forwarding actions, IPv6 mounting is not supported.
For an Ingress that is associated with an IPv4-type ALB instance, IPv6 mounting for the server group is not supported.

Expand to view the full sample YAML

apiVersion: v1
kind: Service
metadata:
  name: tea-svc
  annotations:
spec:
  # When configuring dual-stack, ipFamilies must be set to IPv4 or IPv6, and ipFamilyPolicy must be set to RequireDualStack or PreferDualStack.
  ipFamilyPolicy: RequireDualStack
  ipFamilies:
  - IPv4
  - IPv6
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  selector:
    app: tea
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tea
spec:
  replicas: 2
  selector:
    matchLabels:
      app: tea
  template:
    metadata:
      labels:
        app: tea
    spec:
      containers:
      - name: tea
        image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
        ports:
        - containerPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/enable-ipv6: "true"
spec:
  ingressClassName: alb
  rules:
   - host: demo.alb.ingress.top
     http:
      paths:
      - path: /tea
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Both the Service and the ALB Ingress must be configured as required for dual-stack. After you create a dual-stack ALB instance, the server group can mount both IPv4 and IPv6 backend servers.

Configuration object	Configuration parameter	Value	Description	YAML example
Service	`ipFamilies`	`IPv4` `IPv6`	Specifies the IP address types available for the Service.	`apiVersion: v1 kind: Service metadata: name: tea-svc annotations: spec: # When configuring dual-stack, ipFamilies must be set to IPv4 or IPv6, and ipFamilyPolicy must be set to RequireDualStack or PreferDualStack. ipFamilyPolicy: RequireDualStack ipFamilies: - IPv4 - IPv6 ... ...`
Service	`ipFamilyPolicy`	`RequireDualStack` `PreferDualStack`	Sets the IP policy for the Service, supporting dual-stack.
ALB Ingress	`alb.ingress.kubernetes.io/enable-ipv6`	`"true"`	Enables IPv6 mounting for the server group.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/enable-ipv6: "true" spec: ... ...`

Support QPS throttling

ALB supports Queries Per Second (QPS) throttling for forwarding rules. You can configure QPS throttling by setting the following annotation.

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/traffic-limit-qps: "50"
spec:
  ingressClassName: alb
  rules:
   - host: demo.alb.ingress.top
     http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

Annotation	Description	YAML example
`alb.ingress.kubernetes.io/traffic-limit-qps`	Sets the QPS throttling limit for the forwarding rule. The value range is [1, 1000000].	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/traffic-limit-qps: "50" spec: ... ...`

Backend slow start

After a new pod is added to the Service backend, if ALB Ingress immediately allocates traffic to the new pod, it may cause a transient high CPU or memory pressure, which leads to access exceptions. Using slow start, ALB Ingress can gradually transfer traffic to the new pod, which mitigates the impact of sudden traffic bursts. The following code block shows a sample configuration:

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/slow-start-enabled: "true"
    alb.ingress.kubernetes.io/slow-start-duration: "100"
  name: alb-ingress
spec:
  ingressClassName: alb
  rules:
  - host: alb.ingress.alibaba.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Parameter

Description

YAML example

alb.ingress.kubernetes.io/slow-start-enabled

Specifies whether to enable the slow start feature. It is disabled by default.

true: Enables the slow start feature.
false: Disables the slow start feature.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/slow-start-enabled: "true"
    alb.ingress.kubernetes.io/slow-start-duration: "100"
  name: alb-ingress
... ...

alb.ingress.kubernetes.io/slow-start-duration

The longer the time for the traffic to gradually increase after the slow start is completed, the slower the traffic increase rate. This parameter is in seconds (s). The value range is [30, 900], and the default value is 30 seconds.

Connection draining

When a pod enters the Terminating state, ALB Ingress removes it from the backend server group. The connections that are already established between ALB and the pod are not immediately interrupted. Client access continues to forward requests to these backend servers. This may cause the business in the pod to be unable to go offline for a long time or cause request errors. To avoid this issue, you can use the connection draining feature of ALB. When a pod is removed or a health check is abnormal, ALB Ingress maintains normal transmission for a period of time and then actively disconnects the connection after the interruption time is reached. This ensures a smooth business offline process. For more information, see Achieve smooth business offline through ALB connection draining.

Important

Before the connection draining time ends, ALB Ingress cannot guarantee that the pod is in a running state. You can configure spec.terminationGracePeriodSeconds for the pod or use a preStop Hook to control the availability of the pod in the Terminating state.

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/connection-drain-enabled: "true"
    alb.ingress.kubernetes.io/connection-drain-timeout: "199"
  name: alb-ingress
spec:
  ingressClassName: alb
  rules:
  - host: alb.ingress.alibaba.com
    http:
      paths:
      - path: /test
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Parameter

Description

YAML example

alb.ingress.kubernetes.io/connection-drain-enabled

Specifies whether to enable connection draining. It is disabled by default.

true: Enables connection draining.
false: Disables connection draining.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/connection-drain-enabled: "true"
    alb.ingress.kubernetes.io/connection-drain-timeout: "199"
  name: alb-ingress
... ...

alb.ingress.kubernetes.io/connection-drain-timeout

The connection draining timeout period in seconds (s). The value range is [0, 900], and the default value is 300 seconds.

Disable cross-zone load balancing

By default, ALB enables cross-zone load balancing. This means that traffic is evenly distributed to backend services across different zones in the same region. If you disable cross-zone load balancing for an ALB server group, traffic is distributed only among backend services within the same zone in the same region.

Important

To disable cross-zone load balancing, you must make sure that ALB has available backend services configured in each zone and that these servers have sufficient resources. To avoid affecting your business, perform this operation with caution.

You can refer to the following example to disable cross-zone load balancing:

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-ingress
  namespace: default
  annotations:
    alb.ingress.kubernetes.io/cross-zone-enabled: "false"
spec:
  ingressClassName: alb
  rules:
  - host: alb.ingress.alibaba.com
    http:
      paths:
      - path: /test
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Parameter

Description

YAML example

alb.ingress.kubernetes.io/cross-zone-enabled

Specifies whether to disable cross-zone forwarding. It is enabled by default.

true: Enables cross-zone forwarding.
false: Disables cross-zone forwarding.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: alb-ingress
  namespace: default
  annotations:
    alb.ingress.kubernetes.io/cross-zone-enabled: "false"
... ...