Container Compute Service:Advanced ALB Ingress configurations

Prerequisites

Before you begin, ensure that you have:

• An ACS cluster. For more information, see Create an ACS cluster.

• An AlbConfig object. For more information, see Getting started with ALB Ingress.

Annotation quick reference

All ALB Ingress configurations use Kubernetes annotations. The following table lists the annotations covered in this topic.

Forward requests based on domain names

ALB Ingress routes incoming requests to Services based on the host field in Ingress rules. This section shows how to forward requests using a named domain and without a domain.

Forward requests based on URL paths

Set the pathType field to control how ALB Ingress matches URL paths. Three match types are supported: Exact, ImplementationSpecific (default), and Prefix.

URL match policies can conflict with each other. When conflicts exist, requests are matched in descending order of policy priority. For details, see Set forwarding rule priorities.

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

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

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

curl <ADDRESS>/hello

{"hello":"coffee"}

Configure health checks

Add health check annotations to an Ingress to let ALB probe backend servers and remove unhealthy ones from the rotation automatically.

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

Redirect HTTP to HTTPS

Set alb.ingress.kubernetes.io/ssl-redirect: "true" to redirect all HTTP requests to HTTPS port 443.

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

Set the backend protocol

ALB supports HTTPS and gRPC as backend protocols. Set the alb.ingress.kubernetes.io/backend-protocol annotation to "https" or "grpc".

The backend protocol cannot be changed after the Ingress is created. To change the protocol, delete the Ingress and recreate it.

For gRPC, the domain must have an SSL certificate and use TLS. The following example configures a gRPC backend:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-protocol: "grpc"
  name: lxd-grpc-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

Use regular expressions

Set alb.ingress.kubernetes.io/use-regex: "true" to enable regular expression matching in the path field. Use the alb.ingress.kubernetes.io/conditions.<service-name> annotation to define custom path conditions.

The Service named in the annotation must exist in the cluster and match the Service name in the backend field of the rule.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/use-regex: "true"
   alb.ingress.kubernetes.io/conditions.service-a: |
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "~*^/pathvalue1",
              "/pathvalue2"
           ]
       }
      }]
  name: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test
        pathType: Prefix
        backend:
          service:
            name: service-a
            port:
              number: 88

Regular expression patterns must use the ~* flag prefix (for example, ~*^/pathvalue1). Exact match paths do not require the ~* prefix.

Configure rewrite rules

Use alb.ingress.kubernetes.io/rewrite-target together with alb.ingress.kubernetes.io/use-regex: "true" to rewrite request paths before they reach the backend.

Rules:

• Variables in ${number} format must be used on a path whose pathType is Prefix.

• Up to three capture group variables are supported: ${1}, ${2}, and ${3}.

• The path must start with /.

• By default, * and ? are not allowed in the path field. Enable use-regex to use them.

The following example rewrites paths matching /something(/|$)(.*):

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

The ${2} variable captures the path segment after /something/. The backend receives the following paths:

For multi-group rewrites, consider this example: path set to /sys/(.*)/(.*)/aaa and rewrite-target set to /${1}/${2}. A request to /sys/ccc/bbb/aaa matches the pattern — ${1} is replaced with ccc and ${2} with bbb — so the backend receives /ccc/bbb.

Configure custom listening ports

Set alb.ingress.kubernetes.io/listen-ports to expose a Service on multiple ports simultaneously — for example, HTTP on port 80 and HTTPS on port 443.

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

Set forwarding rule priorities

By default, ALB Ingress prioritizes forwarding rules as follows:

• Ingresses are ranked by the lexicographical order of namespace/name. A lower value means higher priority.

• Within the same Ingress, rules are matched top-to-bottom in the order they appear in the rules field.

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

Priorities must be unique within the same listener. The value must be an integer from 1 to 1,000. A lower value means higher priority. The default is 10.

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

Canary releases

ALB Ingress supports canary releases that route a subset of traffic to a new version of your Service. Three traffic-splitting methods are available: header-based, cookie-based, and weight-based.

Enable canary releases on an Ingress by setting alb.ingress.kubernetes.io/canary: "true", then add the appropriate routing annotations.

Canary rule priority: header-based > cookie-based > weight-based.

During canary testing, do not modify the original Ingress rules — doing so may interrupt traffic. After the new version passes testing, update the backend Service in the original Ingress and delete the canary Ingress.

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

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

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

Configure session persistence

ALB Ingress routes requests from the same client to the same backend server across multiple connections. Configure session persistence using the following annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /tea2
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      - path: /coffee2
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

Set the load balancing algorithm

Use alb.ingress.kubernetes.io/backend-scheduler to set the load balancing algorithm for a backend server group. The cluster version must be 1.19 or later.

Four algorithms are supported:

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"
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Configure CORS

Set alb.ingress.kubernetes.io/enable-cors: "true" to enable Cross-Origin Resource Sharing (CORS) on an ALB Ingress.

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

Enable backend persistent connections

By default, ALB uses short-lived connections to backend server groups — each request opens and then closes a TCP connection. Persistent connections reuse existing TCP connections across multiple requests, reducing connection overhead and improving throughput under high load.

Set alb.ingress.kubernetes.io/backend-keepalive: "true" 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

Configure QPS throttling

Set alb.ingress.kubernetes.io/traffic-limit-qps to limit the number of queries per second (QPS) for a forwarding rule. The value must be an integer from 1 to 100,000.

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

What's next

• Use AlbConfigs to configure ALB listeners

• Getting started with ALB Ingress

• Create an ACS cluster