DocsICP FilingConsole
官方文档
首页

Advanced ALB Ingress configurations

更新时间：
复制 MD 格式
产品详情
我的收藏

Configure ALB Ingress annotations for routing, HTTPS redirect, health checks, and canary releases.

Prerequisites

Before you begin, ensure that you have:

Annotation quick reference

ALB Ingress features are configured with annotations in the metadata.annotations field. The following table lists supported annotations by category.

Category Annotation Description
Health check alb.ingress.kubernetes.io/healthcheck-enabled Enable or disable health checks
alb.ingress.kubernetes.io/healthcheck-path Health check path
alb.ingress.kubernetes.io/healthcheck-protocol Protocol: HTTP, HTTPS, TCP, GRPC
alb.ingress.kubernetes.io/healthcheck-httpversion HTTP version: HTTP1.0, HTTP1.1
alb.ingress.kubernetes.io/healthcheck-method Method: HEAD, POST, GET
alb.ingress.kubernetes.io/healthcheck-code Expected status code (takes precedence over healthcheck-httpcode)
alb.ingress.kubernetes.io/healthcheck-httpcode Expected HTTP status code (clusters earlier than 1.19)
alb.ingress.kubernetes.io/healthcheck-timeout-seconds Timeout in seconds (1–300)
alb.ingress.kubernetes.io/healthcheck-interval-seconds Check interval in seconds (1–50)
alb.ingress.kubernetes.io/healthy-threshold-count Consecutive successes to mark healthy (2–10)
alb.ingress.kubernetes.io/unhealthy-threshold-count Consecutive failures to mark unhealthy (2–10)
alb.ingress.kubernetes.io/healthcheck-connect-port Port for health checks (0 = backend port)
TLS / HTTPS alb.ingress.kubernetes.io/ssl-redirect Redirect HTTP port 80 to HTTPS port 443
Backend protocol alb.ingress.kubernetes.io/backend-protocol Backend protocol: https, grpc
Path matching alb.ingress.kubernetes.io/use-regex Enable regular expressions in path rules
Rewrite alb.ingress.kubernetes.io/rewrite-target Rewrite the request path before forwarding
Listener ports alb.ingress.kubernetes.io/listen-ports Custom listener ports, e.g., [{"HTTP": 80},{"HTTPS": 443}]
Forwarding priority alb.ingress.kubernetes.io/order Forwarding rule priority (1–1000; lower = higher priority)
Canary release alb.ingress.kubernetes.io/canary Enable canary routing
alb.ingress.kubernetes.io/canary-by-header Route by request header name
alb.ingress.kubernetes.io/canary-by-header-value Route by exact header value
alb.ingress.kubernetes.io/canary-by-cookie Route by cookie name (always or never)
alb.ingress.kubernetes.io/canary-weight Percentage of traffic to route to canary (0–100)
Session persistence alb.ingress.kubernetes.io/sticky-session Enable session persistence
alb.ingress.kubernetes.io/sticky-session-type Cookie mode: Insert or Server
alb.ingress.kubernetes.io/cookie-timeout Cookie timeout in seconds (1–86400)
alb.ingress.kubernetes.io/cookie Custom cookie name (required when type is Server)
Load balancing algorithm alb.ingress.kubernetes.io/backend-scheduler Algorithm: wrr, wlc, sch, uch
alb.ingress.kubernetes.io/backend-scheduler-uch-value URL parameter name for uch hashing
CORS alb.ingress.kubernetes.io/enable-cors Enable Cross-Origin Resource Sharing (CORS)
alb.ingress.kubernetes.io/cors-allow-origin Allowed origins
alb.ingress.kubernetes.io/cors-allow-methods Allowed HTTP methods
alb.ingress.kubernetes.io/cors-allow-headers Allowed request headers
alb.ingress.kubernetes.io/cors-expose-headers Headers exposed to the browser
alb.ingress.kubernetes.io/cors-allow-credentials Whether to allow credentials
alb.ingress.kubernetes.io/cors-max-age Preflight cache duration in seconds (−1–172800)
Backend connections alb.ingress.kubernetes.io/backend-keepalive Enable persistent backend connections
Rate limiting alb.ingress.kubernetes.io/traffic-limit-qps QPS limit per forwarding rule (1–100,000)
Slow start alb.ingress.kubernetes.io/slow-start-enabled Enable slow start for new pods
alb.ingress.kubernetes.io/slow-start-duration Ramp-up duration in seconds (30–900)
Connection draining alb.ingress.kubernetes.io/connection-drain-enabled Enable connection draining
alb.ingress.kubernetes.io/connection-drain-timeout Draining timeout in seconds (0–900)

Forward requests based on domain names

Create an Ingress to forward requests by domain name. ALB Ingress supports standard and empty domain names.

Forward requests based on a standard domain name

The following example sets the routing path to /hello. Requests to demo.domain.ingress.top/hello are forwarded to the backend Service.

  1. Deploy the following template to create a Service, a Deployment, and an Ingress. Requests are forwarded to the Service through the domain name 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

  2. Test the routing. Replace ADDRESS with the ALB instance domain name (kubectl get ing to retrieve it).

    curl -H "host: demo.domain.ingress.top" <ADDRESS>/hello

    Expected output:

    {"hello":"coffee"}

Forward requests based on an empty domain name

When the host field is empty, the Ingress matches all requests regardless of domain. The following example routes requests to <ADDRESS>/hello to the backend Service.

  1. 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

  2. Test the routing. Replace ADDRESS with the ALB instance domain name.

    curl <ADDRESS>/hello

    Expected output:

    {"hello":"coffee"}

Forward requests based on URL paths

ALB Ingress forwards requests based on URL paths using the pathType field. Three matching types are supported:

pathType Behavior
Prefix Matches the path prefix, segment by segment, case-sensitive
Exact Exact match only
ImplementationSpecific Handled as exact match (Exact) by the ALB Ingress controller. If path is not set, ALB uses / as the default
Important

If pathType is set to Exact or Prefix, path must be a non-empty absolute path. Otherwise, Ingress creation fails with a validation error. When multiple URL matching rules conflict, ALB evaluates them by forwarding rule priority.

Path matching reference

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

Matching type Rule path Request path Matched?
Prefix / / (matches all) Yes
Prefix /foo /foo Yes
Prefix /foo /foo/ Yes
Prefix /foo/ /foo Yes
Prefix /foo/ /foo/ Yes
Prefix /aaa /ccc No — prefix does not match
Exact or ImplementationSpecific /foo /foo Yes
Exact or ImplementationSpecific /foo /bar No
Exact or ImplementationSpecific /foo /foo/ No
Exact or ImplementationSpecific /foo/ /foo No

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

Matching type Rule path Request path Matched?
Prefix /aaa/bb /aaa/bbb No
Prefix /aaa/bbb /aaa/bbb Yes
Prefix /aaa/bbb/ /aaa/bbb Yes — trailing slash in rule is ignored
Prefix /aaa/bbb /aaa/bbb/ Yes — trailing slash in request is matched
Prefix /aaa/bbb /aaa/bbb/ccc Yes — subpath is matched

Multiple rule paths

Matching type Rule paths Request path Matched?
Prefix /, /aaa /aaa/ccc Yes — matches the / prefix
Prefix /aaa, / /aaa/ccc Yes — matches the /aaa prefix
Prefix /aaa, / /ccc Yes — matches the / prefix
Prefix /aaa, /bbb /ccc No — prefix does not match

Prefix match (Prefix)

Prefix matching compares path segments separated by /, case-sensitive. The following example sets the rule path to /, which matches all paths including /hello.

  1. 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

  2. Test the routing. Replace ADDRESS with the ALB instance domain name.

    curl <ADDRESS>/hello

    Expected output:

    {"hello":"coffee"}

Exact match (Exact or ImplementationSpecific)

The following example sets the rule path to /hello. Only the exact path /hello is matched.

  1. 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

  2. Test the routing. Replace ADDRESS with the ALB instance domain name.

    curl <ADDRESS>/hello

    Expected output:

    {"hello":"coffee"}

Redirect HTTP to HTTPS

Add the alb.ingress.kubernetes.io/ssl-redirect: "true" annotation to redirect HTTP requests to HTTPS port 443.

Important

This annotation only applies to HTTP forwarding rules on listener port 80. This feature works only with RemoveHeader, InsertHeader, and cross-domain CORS annotations. Before adding this annotation, configure an HTTPS listener on port 443 in the AlbConfig.

Clusters that run 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: ClusterIP
---
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

Clusters that run Kubernetes versions 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: ClusterIP
---
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

Configure health checks

Configure health checks for the backend server group with the following annotations.

Expand to view the full sample YAML

Add the following annotations to enable and configure health checks for the backend server group.

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:
  ...

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:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - 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:
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

Annotation reference:

Annotation Description Default
alb.ingress.kubernetes.io/healthcheck-enabled Enable health checks: true or false false
alb.ingress.kubernetes.io/healthcheck-path Health check path /
alb.ingress.kubernetes.io/healthcheck-protocol Protocol: HTTP, HTTPS, TCP, or GRPC. HTTP/HTTPS use HEAD or GET; TCP uses SYN; gRPC uses POST or GET HTTP
alb.ingress.kubernetes.io/healthcheck-httpversion HTTP version: HTTP1.0 or HTTP1.1. Applies to HTTP and HTTPS protocols HTTP1.1
alb.ingress.kubernetes.io/healthcheck-method Request method: HEAD, POST, or GET. Use POST or GET when protocol is GRPC HEAD
alb.ingress.kubernetes.io/healthcheck-code Expected status codes. Takes precedence over healthcheck-httpcode. For HTTP/HTTPS: http_2xx, http_3xx, http_4xx, http_5xx (comma-separated). For gRPC: integer ranges in [0, 99] (up to 20 ranges, comma-separated) HTTP/HTTPS: http_2xx; gRPC: 0
alb.ingress.kubernetes.io/healthcheck-httpcode Expected status codes for clusters earlier than 1.19. Options: http_2xx, http_3xx, http_4xx, http_5xx (comma-separated) http_2xx
alb.ingress.kubernetes.io/healthcheck-timeout-seconds Timeout in seconds. Range: [1, 300] 5
alb.ingress.kubernetes.io/healthcheck-interval-seconds Check interval in seconds. Range: [1, 50] 2
alb.ingress.kubernetes.io/healthy-threshold-count Consecutive successes required to mark a backend server healthy. Range: [2, 10] 3
alb.ingress.kubernetes.io/unhealthy-threshold-count Consecutive failures required to mark a backend server unhealthy. Range: [2, 10] 3
alb.ingress.kubernetes.io/healthcheck-connect-port Health check port. 0 uses the backend server port 0

Use HTTPS and gRPC as backend protocols

Add the alb.ingress.kubernetes.io/backend-protocol annotation to use HTTPS or gRPC as the backend protocol.

After an Ingress is created, the backend protocol cannot be changed. To switch protocols, delete the Ingress and create a new one.
Important

When forwarding gRPC traffic through an Ingress, configure a TLS certificate for the domain name and use TLS for communication.

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
Annotation Values Description
alb.ingress.kubernetes.io/backend-protocol https The backend Service uses HTTPS
grpc The backend Service uses gRPC. Requires TLS configuration on the domain name

Configure regular expressions

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

Annotation Description
alb.ingress.kubernetes.io/use-regex: "true" Enables regular expressions in path rules
alb.ingress.kubernetes.io/conditions.<YOUR-SVC-NAME> Configures custom forwarding conditions. Replace <YOUR-SVC-NAME> with the actual Service name, which must match backend.service.name

Regular expression matching rules:

Target Prefix Rule example Client path Matched? Notes
Domain name Starts with ~ ~test.example.com test.EXAMPLE.com Yes Domain names support case-insensitive matching
Path Starts with ~ ~/api /API Yes Case-insensitive matching
Path Starts with ~* ~*/api /Api No Case-sensitive matching

Expand to view the full sample YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/use-regex: "true"  # Enables regular expression matching
   alb.ingress.kubernetes.io/conditions.<YOUR-SVC-NAME>: | # Replace <YOUR-SVC-NAME> with the Service name — must match backend.service.name
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "~*/pathvalue1", # ~* = case-sensitive regex; ~ = case-insensitive regex
              "/pathvalue2"    # No prefix needed for exact match
           ]
       }
      }]
  name: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test-path-for-alb
        pathType: Prefix
        backend:
          service:
            name: <YOUR-SVC-NAME> # Must match the service name in the annotation above
            port:
              number: 88

Configure rewrites

ALB Ingress rewrites the request path before forwarding. Two annotations control rewrite behavior:

  • alb.ingress.kubernetes.io/rewrite-target: /<path>/${number} — enables rewriting and sets the target path. Use the ${number} format to reference a capturing group from the original path (up to three groups: ${1}, ${2}, ${3}). pathType must be Prefix.

  • alb.ingress.kubernetes.io/use-regex — specifies whether to use regular expressions in the path. Automatically enabled when rewrite-target is configured. Set to "false" to disable; note that paths with special characters (%#;!()[]^,"\") cannot be created when regex is disabled.

Scenario 1: Remove a prefix

The path path: /something(/|$)(.*) uses three capturing groups:

  • /something — matches the prefix to remove

  • (/|$) — first group: matches / or end of path

  • (.*) — second group: captures everything after /something/, referenced as ${2} in the rewrite target

The rewrite target / + ${2} removes the /something prefix:

Original path Matched? Rewritten path
/something Yes (second group is empty) /
/something/ Yes (second group is empty) /
/something/new Yes (second group: new) /new
/something-new/item No 503 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true"
    alb.ingress.kubernetes.io/rewrite-target: /${2}
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 path /items/(.*)/(.*)/(.*) captures three segments. The rewrite target /${2}?code=${3} restructures the URL using the second and third groups.

This pattern requires exactly four path segments. Clients must use a fixed path format.
Original path Matched? Rewritten path
/items/electronics/computers/554 Yes (group 2: computers, group 3: 554) /computers?code=554
/items/produce/fruits/12 Yes (group 2: fruits, group 3: 12) /fruits?code=12
/items/headphones/5 No 503
/drinks/41 No 503 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true"
    alb.ingress.kubernetes.io/rewrite-target: /${2}?code=${3}
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 routes both /app-a and /app-b to /app-c by defining two path rules with the same rewrite target /${2} → /app-c/${2}.

Original path Matched? Rewritten path
/app-a/item1 Yes (group 2: item1) /app-c/item1
/app-a/item2 Yes (group 2: item2) /app-c/item2
/app-a or /app-a/ Yes (group 2 is empty) /app-c/
/drinks/41 No 503 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/use-regex: "true"
    alb.ingress.kubernetes.io/rewrite-target: /app-c/${2}
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 rewrite-target annotation changes only the path. To rewrite other parts of the URL such as the domain name or query parameters, use custom forwarding rules.

Verify rewrite rules locally

Use sed to test path regex matches and preview rewritten results before deploying.

The following example tests the path regex /items/(.*)/(.*)/(.*) and rewrite rule /${2}?code=${3} from Scenario 2.

  1. Save the test paths to path2.txt:

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

  2. Simulate the rewrite with sed. Escape / as \/ in the path regex, and use \2 instead of ${2} for capturing groups:

    sed -E 's#\/items\/(.*)\/(.*)\/(.*)#Matched: [&]  --->  Rewritten: [/\2?code=\3]#' path2.txt

    Expected output — the first two paths match the rewrite rule; the last two do not:

    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

Use the alb.ingress.kubernetes.io/listen-ports annotation to expose a Service on multiple ports, such as HTTP 80 and HTTPS 443.

Important

ALB does not create listeners from an Ingress. Create the required listener ports and protocols in the AlbConfig first, then associate them with the Ingress.

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
Annotation Description
alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]' Configures the Service to listen on both port 80 and port 443

Configure forwarding rule priority

By default, ALB sorts forwarding rules in the following order:

  • Across Ingresses: sorted by namespace/name lexicographically. Smaller values have higher priority. Namespace is compared first, then name.

  • Within the same Ingress: sorted by order in the rules field. Rules listed earlier have higher priority.

    rules:
  - host: www.example.com   # Higher priority
    http: ...
  - host: www.test.com      # Lower priority
    http: ...

To override the default sort order without renaming the Ingress, use the alb.ingress.kubernetes.io/order annotation.

Important

Priorities within the same listener must be unique.

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
Annotation Range Default Description
alb.ingress.kubernetes.io/order [1, 1000] 10 Forwarding rule priority. Lower values have higher priority

Implement canary releases using annotations

ALB supports canary releases based on request headers, cookies, and traffic weights. Create a separate canary Ingress alongside the production Ingress.

Canary routing priority: Header > Cookie > Weight (from highest to lowest).

Important

Do not delete the production Ingress during the canary release. After the canary release is validated, update the backend Service in the production Ingress to point to the new version, then delete the canary Ingress.

See Implement phased releases through ALB Ingress.

Route by header

Use canary-by-header and canary-by-header-value together to route requests matching a specific header value to the canary Service. Requests that do not match fall through to the next canary rule (cookie or weight).

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

With this configuration, requests with location: hz are routed to the canary Service. All other requests fall through to the next canary rule.

Annotation Description
alb.ingress.kubernetes.io/canary-by-header Request header name to match
alb.ingress.kubernetes.io/canary-by-header-value Exact header value to match. Both annotations must be configured together

Route by cookie

Use canary-by-cookie to route requests based on a cookie name. Set the cookie value to always to always route to the canary Service, or never to always exclude it.

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

With this configuration, requests with Cookie: demo=always are routed to the canary Service. Requests with Cookie: demo=never bypass the canary Service entirely.

Annotation Values Description
alb.ingress.kubernetes.io/canary-by-cookie always All requests are routed to the canary Service
never No requests are routed to the canary Service

Cookie-based canary routing supports only always and never. Custom cookie values are not supported.

Route by weight

Use canary-weight to send a percentage of traffic to the canary Service. The following example routes 50% of traffic to the canary:

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
Annotation Range Description
alb.ingress.kubernetes.io/canary-weight 0–100 Percentage of requests routed to the canary Service

Implement session persistence using annotations

ALB Ingress supports cookie-based session persistence. Add the following annotations to enable and configure it.

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"   # Use "Server" for custom cookies
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
  ...

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"   # Use "Server" for custom cookies
    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"  # Use "Server" for custom cookies
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
    alb.ingress.kubernetes.io/cookie: "test"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /tea2
        pathType: ImplementationSpecific
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee2
        pathType: ImplementationSpecific
        backend:
          serviceName: coffee-svc
          servicePort: 80
Annotation Description Default
alb.ingress.kubernetes.io/sticky-session Enable session persistence: true or false false
alb.ingress.kubernetes.io/sticky-session-type Cookie handling mode. Insert: ALB inserts a SERVERID cookie to route subsequent requests to the same backend. Server: ALB rewrites a custom cookie for routing. Requires StickySessionEnabled set to true on the server group. See Create a server group Insert
alb.ingress.kubernetes.io/cookie-timeout Cookie timeout in seconds. Range: [1, 86400]. Applies when sticky-session-type is Insert 1000
alb.ingress.kubernetes.io/cookie Custom cookie name. Required and cannot be blank when sticky-session-type is Server ""

Specify a load balancing algorithm

Use the alb.ingress.kubernetes.io/backend-scheduler annotation to set the load balancing algorithm for a backend server group.

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"
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # Required only for uch
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"
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # Required only for uch
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: tea-svc
              servicePort: 80
            path: /tea
            pathType: ImplementationSpecific
Value Algorithm Description
wrr Weighted round-robin Backend servers with higher weights receive more requests. Default algorithm
wlc Weighted least connections Routes to the server with the fewest active connections, weighted by server weight
sch Source IP consistent hashing Routes requests from the same client IP to the same backend server
uch URL parameter consistent hashing Routes by URL parameter hash. Set the parameter name with alb.ingress.kubernetes.io/backend-scheduler-uch-value

Configure cross-origin resource sharing

Add CORS annotations to allow browsers to make cross-origin requests to the Service.

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"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: cloud-nodeport
            port:
              number: 80
Annotation Description Default
alb.ingress.kubernetes.io/cors-allow-origin Allowed origins. Must start with http:// or https://, followed by a valid domain or top-level wildcard domain. Separate multiple origins with commas. Example: "https://example.com:4443, http://aliyundoc.com, https://example.org:1199" *
alb.ingress.kubernetes.io/cors-allow-methods Allowed cross-origin methods. Case-insensitive. Separate multiple methods with commas. Example: "PUT, GET, POST, OPTIONS" GET, PUT, POST, DELETE, PATCH, OPTIONS
alb.ingress.kubernetes.io/cors-allow-headers Allowed request headers. Headers may contain letters, digits, underscores (_), and hyphens (-). Separate multiple headers with commas. Example: "X-Forwarded-For, X-app123-XPTO" DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization
alb.ingress.kubernetes.io/cors-expose-headers Headers exposed to the browser. May contain letters, digits, underscores (_), hyphens (-), and asterisks (*). Separate multiple headers with commas. Example: "*, X-CustomResponseHeader" Empty
alb.ingress.kubernetes.io/cors-allow-credentials Whether to allow credentials in cross-origin requests. Example: "false" true
alb.ingress.kubernetes.io/cors-max-age Maximum cache duration in seconds for OPTIONS preflight responses. Range: [−1, 172800] 172800

Enable persistent backend connections

Persistent backend connections reuse TCP connections to backend servers, reducing the overhead of opening and closing connections per request.

Add the alb.ingress.kubernetes.io/backend-keepalive: "true" annotation to enable this feature:

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

Set QPS rate limits

Add the alb.ingress.kubernetes.io/traffic-limit-qps annotation to set QPS throttling at the forwarding rule level:

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 Range Description
alb.ingress.kubernetes.io/traffic-limit-qps [1, 100,000] Maximum QPS for the forwarding rule

Configure slow start for new pods

Slow start gradually ramps up traffic to new pods over a configured duration, preventing transient CPU or memory spikes from full traffic hitting a cold pod.

Annotation Description Default
alb.ingress.kubernetes.io/slow-start-enabled Enable slow start: true or false false
alb.ingress.kubernetes.io/slow-start-duration Ramp-up duration in seconds. Longer durations slow the traffic increase. Range: [30, 900] 30

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

Configure connection draining

When a pod enters the Terminating state, ALB removes it from the backend server group. Without connection draining, in-flight requests on existing connections may fail.

Connection draining keeps active connections open for a configured period, allowing in-flight requests to complete before the pod goes offline.

Important

Before the draining timeout ends, ALB cannot guarantee that the pod remains healthy. Configure spec.terminationGracePeriodSeconds on the pod or use a preStop hook to control pod availability during the Terminating state.

See Achieve smooth business offline through ALB connection draining.

Annotation Description Default
alb.ingress.kubernetes.io/connection-drain-enabled Enable connection draining: true or false false
alb.ingress.kubernetes.io/connection-drain-timeout Maximum time in seconds ALB waits before closing connections after a pod is removed or fails a health check. Range: [0, 900] 300

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:
Previous：ALB quota calculation methodNext：ALB Ingress configuration with annotations