Enable gRPC, HTTPS Redirect & Canary Routing via ALB Ingress on ACK - Container Service for Kubernetes - Alibaba Cloud - Container Service for Kubernetes

Forward requests based on domain names

Create an Ingress to forward requests based on a domain name or an empty domain name.

Domain name

This example sets the routing path to/hello. Requests todemo.domain.ingress.top/hello are forwarded to the backend service.

Deploy the following manifest to create a Service, a Deployment, and an Ingress that forwards requests based on the specified domain name.

Example YAML

Kubernetes 1.19 or 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

Kubernetes earlier than 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

Runkubectl get ing to obtain the address of the ALB instance. Then, run the following command, replacing ADDRESS with the instance's address.
```
curl -H "host: demo.domain.ingress.top" ADDRESS/hello
```
Expected output:
```
{"hello":"coffee"}
```

Empty domain name

With an empty domain name and routing path/hello, requests to ADDRESS/hello are forwarded to the backend service.

Deploy the following manifest to create a Service, a Deployment, and an Ingress.

Example YAML

Kubernetes 1.19 or 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

Kubernetes earlier than 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

Runkubectl get ing to obtain the address of the ALB instance. Then, run the following command, replacing ADDRESS with the instance's address.
```
curl ADDRESS/hello
```
Expected output:
```
{"hello":"coffee"}
```

Path-based forwarding

ALB Ingress forwards requests based on URL paths. Specify the match mode in the pathType field. pathType supports three modes.

Exact match (Exact): Matches the URL path exactly.
Default (ImplementationSpecific): ALB Ingress Controller treats this as an exact match. If path is not specified, defaults to /.
Prefix match (Prefix): Matches the prefix of the URL path.

Important

When pathType is Exact or Prefix, path must be a non-empty absolute path. Otherwise, validation fails.
If URL matching policies conflict, requests are forwarded based on forwarding rule priority.

Simple paths (/, /foo, /foo/)

Match mode	Rule path	Request path	Matched?
Prefix match (Prefix)	/	/ (matches all paths)	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/)

Match mode	Rule path	Request path	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. The rule path is a prefix of the request path.

Two rule paths

Match mode	Rule path	Request path	Matched?
Prefix match (Prefix)	/ /aaa	/aaa/ccc	Yes. The request path matches the `/aaa` rule path.
	/aaa /	/aaa/ccc	Yes. The request path matches the `/aaa` rule path.
	/aaa /	/ccc	Yes. The request path matches the `/` rule path.
	/aaa /bbb	/ccc	No. The prefix does not match.

Examples for each match mode:

Prefix match (Prefix)

This mode performs a case-sensitive prefix match on URL path elements, which are separated by /.

Rule path / matches all paths starting with /, such as /hello.

Deploy the following manifest to create the ingress resource.

Example YAML

Kubernetes 1.19 or 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

Kubernetes earlier than 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 kubectl get ing to get the address of the ALB instance. Then, run the following command, replacing ADDRESS with the retrieved address.
```
curl ADDRESS/hello
```
Expected output:
```
{"hello":"coffee"}
```

Exact match or default

Rule path /hello matches only requests to /hello.

Deploy the following manifest to create the ingress resource.

Example YAML

Kubernetes 1.19 or 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

Kubernetes earlier than 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 kubectl get ing to get the address of the ALB instance. Then, run the following command, replacing ADDRESS with the retrieved address.
```
curl ADDRESS/hello
```
Expected output:
```
{"hello":"coffee"}
```

Configure health checks

Use annotations to configure health checks for ALB Ingress.

Click to view the full YAML example

Kubernetes 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

Kubernetes earlier than 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

Example 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
`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 path used for health checks.	`/`
`alb.ingress.kubernetes.io/healthcheck-protocol`	The protocol used for health checks. `HTTP`: Sends a HEAD or GET request to verify server health. `HTTPS`: Sends a HEAD or GET request to verify server health. `TCP`: Sends a SYN handshake packet to verify port availability. `GRPC`: Sends a POST or GET request to verify server health.	`HTTP`
`alb.ingress.kubernetes.io/healthcheck-httpversion`	HTTP protocol version. Takes effect only when `healthcheck-protocol` is set to `HTTP` or `HTTPS`. `HTTP1.0` `HTTP1.1`	`HTTP1.1`
`alb.ingress.kubernetes.io/healthcheck-method`	The method used for health checks. `HEAD` `POST` `GET` Important If `healthcheck-protocol` is set to `GRPC`, you must set this parameter to `POST` or `GET`.	`HEAD`
`alb.ingress.kubernetes.io/healthcheck-httpcode`	Status code(s) indicating a healthy backend server. Specify one or more options, separated by commas. `http_2xx` `http_3xx` `http_4xx` `http_5xx`	`http_2xx`
`alb.ingress.kubernetes.io/healthcheck-code`	Status code(s) indicating a healthy backend server. Takes precedence over `healthcheck-httpcode` if both are specified. Valid values depend on `healthcheck-protocol`: `HTTP or HTTPS`: Specify one or more options, separated by commas. `http_2xx` `http_3xx` `http_4xx` `http_5xx` `GRPC`: The value must be an integer from 0 to 99. Specify up to 20 value ranges, separated by commas.	`HTTP or HTTPS` `http_2xx` `GRPC` `0`
`alb.ingress.kubernetes.io/healthcheck-timeout-seconds`	The health check timeout in seconds. Valid values: 1 to 300.	`5`
`alb.ingress.kubernetes.io/healthcheck-interval-seconds`	The health check interval in seconds. Valid values: 1 to 50.	`2`
`alb.ingress.kubernetes.io/healthy-threshold-count`	The number of consecutive successful health checks required to mark a backend server as healthy. Valid values: 2 to 10.	`3`
`alb.ingress.kubernetes.io/unhealthy-threshold-count`	The number of consecutive failed health checks required to mark a backend server as unhealthy. Valid values: 2 to 10.	`3`
`alb.ingress.kubernetes.io/healthcheck-connect-port`	The port used for health checks.	`0` Note A value of `0` indicates that the port of the backend server is used for the health check.

Redirect HTTP requests to HTTPS

Add the following annotation to redirect HTTP requests to HTTPS port 443.

Important

This feature applies only to HTTP forwarding rules on listener port 80.
This annotation must be used with annotations for custom forwarding actions, such as RemoveHeader, InsertHeader, and Cors.
Before using this annotation, ensure an HTTPS listener is configured on port 443 in the AlbConfig. See Use an AlbConfig to configure an ALB listener.

YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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 ... ...`

Configure backend HTTPS or gRPC

Add the following annotation to use HTTPS or gRPC as the backend protocol.

YAML examples

Kubernetes 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

Kubernetes earlier than 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

The backend protocol cannot be modified after ingress creation. Delete and recreate the ingress to change it.

Parameter	Description	YAML example
`alb.ingress.kubernetes.io/backend-protocol`	https: Specifies HTTPS as the backend protocol. grpc: Specifies gRPC as the backend protocol. When forwarding requests to a gRPC service through an ingress, you must configure an SSL certificate for the domain name and use the TLS protocol.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/backend-protocol: "grpc" name: demo-alb-ingress ... ...`

Configure regular expressions

Use the alb.ingress.kubernetes.io/use-regex: "true" annotation to enable regular expression matching for path rules in spec.rules with pathType: Prefix.

Important

Applies only to path rules with pathType: Prefix. Enables regex syntax in the path field of spec.rules, independent of custom forwarding conditions.
This annotation enables regex matching regardless of its value (true or false). Remove the annotation to disable.
Without this annotation, Ingress creation fails if the path contains special characters such as =^()[]|, etc..
Path values in a custom forwarding condition (alb.ingress.kubernetes.io/conditions.YOUR-SVC-NAME) are passed directly to ALB and do not require the use-regex annotation. To enable regex matching, add the ~* or ~ prefix to the path value. The use-regex annotation affects only the path field in spec.rules.

Custom forwarding rules

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/conditions.YOUR-SVC-NAME: | ## Replace YOUR-SVC-NAME with the actual Service name. It must match backend.service.name below.
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "~*/pathvalue1", ## Add the ~* or ~ prefix to a regular expression. The text after the prefix is the regular expression itself. ~* indicates a case-sensitive match, and ~ indicates a case-insensitive match.
              "/pathvalue2"    ## An exact match does not require a prefix.
           ]
       }
      }]
  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 match the Service name specified in the custom forwarding condition annotation to define the association.
            port:
              number: 88

Spec.rules

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/use-regex: "true"  ## Allows the path in spec.rules to use a regular expression.
  name: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test-[a-z]-alb[()^]*
        pathType: Prefix
        backend:
          service:
            name: tea-svc
            port:
              number: 88

Parameter

Description

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

Enables regular expressions for path rules in spec.rules with pathType: Prefix.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true"
  name: demo-alb-ingress
... ...

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

Configures a custom forwarding condition. See Customize forwarding rules for an ALB Ingress.

Replace YOUR-SVC-NAME with the actual Service name. This name must match backend.service.name below.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/conditions.YOUR-SVC-NAME: | ## Replace YOUR-SVC-NAME with the actual Service name. It must match backend.service.name below.
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "~*/pathvalue1", ## Add the ~* or ~ prefix to a regular expression. The text after the prefix is the regular expression itself. ~* indicates a case-sensitive match, and ~ indicates a case-insensitive match.
              "/pathvalue2"    ## An exact match does not require a prefix.
           ]
       }
      }]
  name: ingress-example
... ...

The following table describes the regular expression matching rules.

Object	Prefix	Rule example	Client path	Match?	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.

Regex prefix match

Regex matching defaults to a 'contains match'. To match only paths that start with specific content, add ^ to the beginning of the expression. For example, ^/api matches only paths starting with /api.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-example
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true"  ## Enable regex matching.
    alb.ingress.kubernetes.io/conditions.YOUR-SVC-NAME: |     ## Replace YOUR-SVC-NAME with the actual service name. This must match backend.service.name below.
      [
        {
          "type": "Path",
          "pathConfig": {
            "values": [
              "~*^/pathvalue1",  # A path that starts with ~* or ~ indicates a regex match. The caret (^) indicates "starts with /pathvalue1".
              "/pathvalue2"     # For a standard prefix or exact match, do not add ~* or ~.
            ]
          }
        }
      ]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /test-path-for-alb
            pathType: Prefix
            backend:
              service:
                name: YOUR-SVC-NAME   # Replace with the actual service name, which must match the annotation.
                port:
                  number: 88

Configure rewrites

ALB Ingress rewrites request paths before forwarding to the backend Service. Use the following two annotations:

alb.ingress.kubernetes.io/rewrite-target: /path/${number}: Specifies the path to which requests are rewritten.
Important
- Use ${number} variables to reference capture groups from the regular expression in the Ingress path. Up to three capture groups can be referenced using ${1}, ${2}, and ${3}.
- The pathType of the Ingress must be set to Prefix.
alb.ingress.kubernetes.io/use-regex: true: Enables the use of a regular expression in the path. This is enabled by default when you configure rewrite-target.
Important
- This annotation enables regex matching regardless of its value (true or false). Remove the annotation to disable.
- Without this annotation, Ingress creation fails if the path contains special characters such as "%#;!()[]^,"\"".

Configuration examples

Example 1: Remove a prefix

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

/something: Matches the prefix to be removed.
(/|$): The first capture group, which matches either a / after /something or the end of the path ($).
(.*): The second capture group, which matches all characters after /something/ and is referenced as ${2} in the rewritten path.

The alb.ingress.kubernetes.io/rewrite-target annotation specifies the rewritten path as / followed by ${2}. The following table shows the rewrite results.

Original client path	Path regex match	Rewritten path
`/something`	Match. The second capture group is empty.	`/`
`/something/`	Match. The second capture group is empty.	`/`
`/something/new`	Match. The second capture group is `new`.	`/new`
`/something-new/item`	No match. In this example, because the request does not match any routing rule, 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 a regular expression.
    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

Example 2: Capture and rearrange multiple parts

The following example captures and rearranges multiple parts of the path /items/(.*)/(.*)/(.*). It also converts path segments into query parameters, which requires no client-side changes. The rewritten path is constructed as /, followed by the second capture group ${2}, the string ?code=, and the third capture group ${3}. The following table shows the rewrite results.

This example requires the client to use a fixed path format with four segments.

Original client path	Path regex match	Rewritten path
`/items/electronics/computers/554`	Match. The second capture group is `computers`, and the third is `554`.	`/computers?code=554`
`/items/produce/fruits/12`	Match. The second capture group is `fruits`, and the third is `12`.	`/fruits?code=12`
`/items/headphones/5`	No match. In this example, because the request does not match any routing rule, ALB Ingress returns a 503 status code.
`/drinks/41`	No match. In this example, because the request does not match any routing rule, 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 a regular expression.
    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

Example 3: Rewrite multiple paths to a single path

The following example uses a regular expression to match multiple paths (/app-a(/|$)(.*) and /app-b(/|$)(.*)) and rewrites them to a single path. The rewritten path is /app-c/ followed by ${2}. The following table shows the rewrite results.

Original client path	Path regex match	Rewritten path
`/app-a/item1`	Match. The second capture group is `item1`.	`/app-c/item1`
`/app-a/item2`	Match. The second capture group is `item2`.	`/app-c/item2`
`/app-a` or `/app-a/`	Match. The second capture group is empty.	`/app-c/`
`/drinks/41`	No match. In this example, because the request does not match any routing rule, 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 a regular expression.
    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

Example 4: Rewrite domain name

The alb.ingress.kubernetes.io/rewrite-target annotation only supports changing the path. To change other parts of the URL, such as the domain name or query parameters, use a custom forwarding rule.

Test rewrite rules

Use the sed command to test whether a client path matches the path's regular expression and to preview the rewritten path.

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

Save the following sample paths to a file named 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:

The following command adapts the example's path regular expression (/items/(.*)/(.*)/(.*)) and rewritten path (/${2}?code=${3}) for sed. When using sed, special characters like / must be escaped with a backslash (\), and capture group references are written as \2 instead of ${2}.
```
sed -E 's#\/items\/(.*)\/(.*)\/(.*)#Matched: []  ---  Rewritten: [/\2?code=\3]#' path2.txt
```
The following output is expected. The first two paths match the rule and are rewritten, while the last two do not match and remain unchanged.
```
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

Add an annotation to expose a service on both port 80 (HTTP) and port 443 (HTTPS).

Full YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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 listeners directly in an Ingress. First create the required listener ports and protocols in an AlbConfig, then reference them in the Ingress. See Use an AlbConfig to configure an ALB listener.

Parameter	Description	YAML example
`alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]'`	Exposes the service on ports 80 and 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, ALB prioritizes forwarding rules based on the following criteria:

The system sorts Ingress resources lexicographically by namespace/name. An Ingress with a smaller lexicographical value has a higher priority.

Namespaces are compared first, then names character by character.
Within a single Ingress, rules are prioritized by their order in the rules field. Rules listed first have a higher priority.
```
rules:
  - host: www.example.com
    http: ...
  - host: www.test.com
    http: ...
```

To specify the priority of an ALB forwarding rule without changing the namespace/name of the Ingress, add the following Ingress annotation:

Click to view the full YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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

YAML example

alb.ingress.kubernetes.io/order

Specifies the priority of the ALB forwarding rule. A lower value indicates a higher priority.

The priority of each rule must be unique within the same listener.

[1, 1000]

Default: 10

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

Implement canary releases with annotations

ALB supports canary releases based on headers, cookies, and weights. See Implement canary releases by using an ALB Ingress for best practices.

Parameter	Description	Description
`alb.ingress.kubernetes.io/canary: "true"`	Enables the canary release feature.	Canary traffic can be distributed based on headers, cookies, or weights. ALB applies these rules in the following order of priority (from highest to lowest): header > cookie > weight. Do not delete the original Ingress during a canary release. After verifying the canary version is stable, update the original Ingress to use the new Service, then delete the canary Ingress.

Distribute canary traffic based on a specified header

Parameter

Description

YAML example

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

These annotations define a custom request header and value for traffic routing. Both annotations are required.

When the header and header-value in a request match the configured values, request traffic is directed to the canary service entry point.
Unmatched requests are evaluated against lower-priority rules.

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 a request contains thelocation: hzheader, ALB routes the traffic to the canary Service. Other requests are evaluated against lower-priority rules, such as those based on a cookie or weight.

Full YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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

Distribute canary traffic based on a specified cookie

Parameter

Cookie value

YAML example

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

always: Routes all requests to the canary Service.
never: Never routes requests to the canary Service.

Cookie-based canary releases do not support custom values, 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 a request contains theCookie: demo=alwaysheader, ALB routes traffic to the canary Service. If the header containsCookie: demo=never, ALB does not route traffic to the canary Service.

Full YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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

Distribute traffic by weight

Parameter

Description

YAML example

alb.ingress.kubernetes.io/canary-weight

Percentage of traffic routed to the canary Service. Valid values: 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

Full YAML example

Kubernetes 1.19 or 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

Kubernetes earlier than 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

Configure session persistence with annotations

Use the following annotations to configure session persistence for an ALB Ingress.

YAML example

Kubernetes 1.19 or 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"   # To use a custom cookie, set this annotation to 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

Kubernetes earlier than 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"  # To use a custom cookie, set this annotation to Server.
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      # Configure a context path.
      - path: /tea2
        pathType: ImplementationSpecific
        backend:
          serviceName: tea-svc
          servicePort: 80
      # Configure a context path.
      - path: /coffee2
        pathType: ImplementationSpecific
        backend:
          serviceName: coffee-svc
          servicePort: 80

Example 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: "Server"   # To use a custom cookie, set this annotation to Server.
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
... ...

Parameter	Description	Default
`alb.ingress.kubernetes.io/sticky-session`	Specifies whether to enable session persistence. `true`: Enables session persistence. `false`: Disables session persistence.	`false`
`alb.ingress.kubernetes.io/sticky-session-type`	Specifies how the load balancer handles the cookie. `Insert`: The load balancer inserts a `SERVERID` cookie into the first response. Subsequent requests with this cookie are routed to the same backend server. `Server`: The load balancer rewrites the original cookie with a custom cookie. Subsequent requests with the new cookie are routed to the same backend server. Note Applies only when `alb.ingress.kubernetes.io/sticky-session` is set to `"true"`. See Create a server group for server group parameters.	`Insert`
`alb.ingress.kubernetes.io/cookie-timeout`	The cookie timeout in seconds. Valid values: 1 to 86400. Applies only when `alb.ingress.kubernetes.io/sticky-session-type` is set to `Insert`.	1000
`alb.ingress.kubernetes.io/cookie`	The value of the custom cookie. Required (non-empty) when `alb.ingress.kubernetes.io/sticky-session-type` is set to `Server`.	""

Specify the load balancing algorithm

Use an annotation to specify the load balancing algorithm for a backend server group.

YAML example

Kubernetes 1.19 and later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # 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

Kubernetes earlier than 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # 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. Servers with higher weights receive more requests. (Default)	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/backend-scheduler: "uch" # 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`	Distributes requests based on weight and current connection count. If weights are equal, the server with fewest connections is selected.
	`sch`	Routes requests from the same source IP to the same backend server.
	`uch`	Routes requests based on a hash of a specified URL parameter. Use the `alb.ingress.kubernetes.io/backend-scheduler-uch-value` annotation to specify which URL parameter to use for the hash.

CORS configuration

Use the following annotations to configure Cross-Origin Resource Sharing (CORS) for ALB Ingress.

Click to view the full YAML example

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 origin domain name"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cloud-nodeport
            port:
              number: 80

Example 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 origin domain name"
spec:
... ...

Parameter	Description	Default
`alb.ingress.kubernetes.io/enable-cors`	Enables Cross-Origin Resource Sharing (CORS).	Default value: `"false"`
`alb.ingress.kubernetes.io/cors-allow-origin`	Specifies which origins can access resources on the server. Use a comma (,) to separate multiple origins. Each value must start with `http://` or `https://` followed by a valid domain name or a 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`	Specifies the allowed HTTP methods for cross-origin requests. The values are case-insensitive. Use a comma (,) to separate multiple HTTP methods.	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`	Specifies the allowed request headers for cross-origin requests. Set this parameter to `*` or a comma-separated list of header values. Each value can contain only uppercase letters, lowercase letters, and digits. A value cannot start or end with an underscore (_) or a hyphen (-). The maximum length of a single value 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`	Specifies which response headers to expose to the client. Set this parameter to `*` or a comma-separated list of header values. Each value can contain only uppercase letters, lowercase letters, and digits. A value cannot start or end with an underscore (_) or a hyphen (-). The maximum length of a single value 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 include credentials in cross-origin requests.	Default value: `true` Example: `alb.ingress.kubernetes.io/cors-allow-credentials: "false"`
`alb.ingress.kubernetes.io/cors-max-age`	Cache duration for preflight responses, in seconds. Valid values: 0 to 172,800.	Default value: `172800`

Backend persistent connection

Backend persistent connections let ALB reuse TCP connections to backend servers, reducing connection overhead in high-throughput scenarios.

YAML Example

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 to reduce TCP connection overhead.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: alb-ingress annotations: alb.ingress.kubernetes.io/backend-keepalive: "true" spec:`

IPv6 backend attachment for server groups

IPv6 backend attachment allows both IPv4 and IPv6 Pods in a server group, but requires a dual-stack cluster. See Create an ACK managed cluster.

Note

The following limitations apply when IPv6 backend attachment is enabled:

To enable IPv6 backend attachment for a server group, IPv6 must be enabled for the server group's VPC.
IPv6 backend attachment is not supported for server groups of type IP or Function Compute when attached using a custom forwarding action.
If an Ingress is associated with an IPv4-only ALB instance, you cannot enable IPv6 backend attachment for its server groups.

Sample YAML

apiVersion: v1
kind: Service
metadata:
  name: tea-svc
spec:
  # To configure dual-stack, set ipFamilyPolicy to RequireDualStack or PreferDualStack and specify both IPv4 and IPv6 in ipFamilies.
  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

Configure the Service and ALB Ingress for dual-stack. After you create a dual-stack ALB instance, you can attach both IPv4 and IPv6 backend servers to the server group.

Configuration object	Parameter	Value	Description	YAML example
Service	`ipFamilies`	`IPv4` `IPv6`	Specifies the available IP address types for the Service.	`apiVersion: v1 kind: Service metadata: name: tea-svc spec: # To configure dual-stack, set ipFamilyPolicy to RequireDualStack or PreferDualStack and specify both IPv4 and IPv6 in ipFamilies. ipFamilyPolicy: RequireDualStack ipFamilies: - IPv4 - IPv6 ... ...`
Service	`ipFamilyPolicy`	`RequireDualStack` `PreferDualStack`	Sets the IP policy for the Service, enabling dual-stack networking.
ALB Ingress	`alb.ingress.kubernetes.io/enable-ipv6`	`"true"`	Enables IPv6 backend attachment for the server group.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/enable-ipv6: "true" spec: ... ...`

Configure QPS throttling

Add the following annotation to enable QPS throttling for forwarding rules.

View full YAML example

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`	Specifies the QPS limit for forwarding rules. Valid values: 1 to 1,000,000.	`apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: alb.ingress.kubernetes.io/traffic-limit-qps: "50" spec: ... ...`

Slow start

Slow start gradually ramps up traffic to newly added Pods, preventing overload from sudden traffic surges.

YAML example

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 slow start. 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

Slow start ramp-up duration in seconds. Valid values: 30–900. Default: 30.

Connection draining

When a Pod enters the Terminating state, ALB Ingress removes it from the server group but does not immediately close existing connections, which may cause request errors or prevent graceful shutdown. Connection draining keeps existing connections open for a configurable timeout before closing them. See Use connection draining with an ALB Ingress to gracefully shut down a service.

Important

ALB Ingress does not guarantee Pods remain running until connection draining completes. To control Pod availability during termination, configure spec.terminationGracePeriodSeconds or use a preStop Hook.

YAML example

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.

true: Enables connection draining.
false: Disables connection draining. (Default)

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

Specifies the connection draining timeout in seconds. Valid values: [0, 900]. Default: 300.

Disable cross-AZ load balancing

ALB distributes traffic across availability zones by default. Disabling cross-AZ load balancing restricts traffic to backend services in the same zone.

Important

If you disable cross-AZ load balancing, ensure each availability zone has sufficient backend resources.

Use the following example to disable cross-AZ load balancing:

Full YAML example

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 enable cross-AZ load balancing. Enabled by default.

true: Enables cross-AZ load balancing.
false: Disables cross-AZ load balancing.

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