An Application Load Balancer (ALB) Ingress is an API object that provides Layer 7 load balancing to manage external access to Services in a Kubernetes cluster. This topic describes how to use ALB Ingresses to forward requests to backend server groups based on domain names and URL paths, redirect HTTP requests to HTTPS, and implement canary releases.

Prerequisites

Table of contents

This topic describes the following advanced ALB Ingress configurations:

Forward requests based on domain names

Perform the following steps to create an Ingress with a domain name and an Ingress without a domain name, and then use the Ingresses to forward requests.

  • Create an Ingress with a domain name.
    1. Use the following template to create a Deployment, a Service, and an Ingress. Requests to the domain name of the Ingress are forwarded to the Service. 
      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: NodePort
---
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
      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: NodePort
---
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

    2. Run the following command to access the application by using the specified domain name.

      Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the kubectl get ing command. 

      curl -H "host: demo.domain.ingress.top" <ADDRESS>/hello
      Expected output.
      {"hello":"coffee"}
  • Create an Ingress without a domain name.
    1. The following template shows the configuration of the Ingress: 
      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
      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
    2. Run the following command to access the application without using a domain name.

      Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the kubectl get ing command. 

      curl <ADDRESS>/hello
      Expected output.
      {"hello":"coffee"}

Forward requests based on URL paths

ALB Ingresses can forward requests based on URL paths. You can use the pathType parameter to configure different URL match policies. The valid values of pathType are Exact, ImplementationSpecific, and Prefix.

You can perform the following steps to configure different URL match policies.

  • Exact: matches the entire URL path with case sensitivity.
    1. The following template shows the configuration of the Ingress: 
      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
      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
    2. Run the following command to access the application.

      Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the kubectl get ing command. 

      curl <ADDRESS>/hello
      Expected output.
      {"hello":"coffee"}
  • ImplementationSpecific: the default match policy. For ALB Ingresses, the ImplementationSpecific policy has the same effect as the Exact policy. However, the controllers of Ingresses with the ImplementationSpecific policy and the controllers of Ingresses with the Exact policy are implemented in different ways.

    1. The following template shows the configuration of the Ingress: 

      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: ImplementationSpecific
      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
    2. Run the following command to access the application.

      Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the kubectl get ing command. 

      curl <ADDRESS>/hello
      Expected output.
      {"hello":"coffee"}
  • Prefix: matches a specified prefix against URL paths. The elements in URL paths are separated by forward slashes (/). The prefix is case-sensitive and matched against each element of the path.
    1. The following template shows the configuration of the Ingress: 
      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
      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
    2. Run the following command to access the application.

      Replace ADDRESS with the IP address of the related ALB instance. You can query the IP address by running the kubectl get ing command. 

      curl <ADDRESS>/hello
      Expected output.
      {"hello":"coffee"}

Configure health checks

You can configure health checks for ALB Ingresses by using the following annotations.

The following YAML template provides an example on how to create an Ingress that has health check enabled: 

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 a context path. 
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      # Configure a context path. 
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80
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:
      # Configure a context path.
      - path: /tea
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      # Configure a context path.
      - path: /coffee
        backend:
          service:
            name: coffee-svc
            port:
              number: 80

The following table describes the parameters in the YAML template.
Parameter Description
alb.ingress.kubernetes.io/healthcheck-enabled Optional. Specifies whether to enable health check. Default value: true.
alb.ingress.kubernetes.io/healthcheck-path Optional. The URL path based on which health checks are performed. Default value: /.
  • Enter the URL of the web page based on which you want to perform health checks. We recommend that you enter the URL of a static web page. The URL must be 1 to 80 characters in length, and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), and ampersands (&). The URL can also contain the following extended characters: _ ; ~ ! ( ) * [ ] @ $ ^ : ' , +. The URL must start with a forward slash (/).
  • By default, to perform health checks, the ALB instance sends HTTP HEAD requests to the default application homepage configured on a backend Elastic Compute Service (ECS) instance. The ALB instance sends the requests to the private IP address of the ECS instance. If you do not want to use the default application homepage for health checks, you must specify a URL.
alb.ingress.kubernetes.io/healthcheck-protocol Optional. The protocol that is used for health checks.
  • HTTP: The ALB instance sends HEAD or GET requests to a backend server to simulate access from a browser and check whether the backend server is healthy. This is the default protocol.
  • TCP: The ALB instance sends TCP SYN packets to a backend server to check whether the port of the backend server is available to receive requests.
  • GRPC: The ALB instance sends POST or GET requests to a backend server to check whether the backend server is healthy.
alb.ingress.kubernetes.io/healthcheck-method Optional. The request method that is used for health checks.
  • HEAD: By default, the ALB instance sends HEAD requests to a backend server to perform HTTP health checks. Make sure that your backend server supports HEAD requests. If your backend server does not support the HEAD method or the HEAD method is disabled, health checks may fail. In this case, you can use the GET method.
  • POST: By default, gRPC health checks use the POST method. Make sure that your backend servers support POST requests. If your backend server does not support the POST method or the POST method is disabled, health checks may fail. In this case, you can use the GET method.
  • GET: If the size of a response exceeds 8 KB, the response is fragmented. This does not affect the health check result.
alb.ingress.kubernetes.io/healthcheck-httpcode The status codes that are returned when backend servers pass health checks.
  • When the health check protocol is set to HTTP, valid values are http_2xx, http_3xx, http_4xx, and http_5xx. The default value for HTTP health checks is http_2xx.
  • When the health check protocol is set to GRPC, valid values are 0 to 99. Value ranges are supported. You can enter at most 20 value ranges and separate them with commas (,).
alb.ingress.kubernetes.io/healthcheck-timeout-seconds The timeout period of a health check. If a backend server does not respond within the specified timeout period, the server fails to pass the health check. Valid values: 1 to 300. Default value: 5. Unit: seconds.
alb.ingress.kubernetes.io/healthcheck-interval-seconds The interval between two consecutive health checks. Unit: seconds. Valid values: 1 to 50. Default value: 2. Unit: seconds.
alb.ingress.kubernetes.io/healthy-threshold-count The number of times that an unhealthy backend server must consecutively pass health checks before the server is considered healthy. Valid values: 2 to 10. Default value: 3.
alb.ingress.kubernetes.io/unhealthy-threshold-count The number of times that a healthy backend server must consecutively fail health checks before the server is considered unhealthy. Valid values: 2 to 10. Default value: 3.

Configure automatic certificate discovery

The ALB Ingress controller supports automatic certificate discovery. You must first create a certificate in the SSL Certificates console. Then, specify the domain name of the certificate in the Transport Layer Security (TLS) configurations of the Ingress. This way, the ALB Ingress controller can automatically discover and match the certificate based on the TLS configurations of the Ingress.

  1. Run the following openssl commands to create a certificate: 
    openssl genrsa -out albtop-key.pem 4096
openssl req -subj "/CN=demo.alb.ingress.top" -sha256  -new -key albtop-key.pem -out albtop.csr
echo subjectAltName = DNS:demo.alb.ingress.top > extfile.cnf
openssl x509 -req -days 3650 -sha256 -in albtop.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out albtop-cert.pem -extfile extfile.cnf
  2. Upload the certificate to the SSL Certificates console.

    For more information about how to attach the policy to the RAM role, see Upload a certificate.

  3. Add the following setting to the YAML template of the Ingress to specify the domain name in the created certificate: 
    tls:
  - hosts:
    - demo.alb.ingress.top

    Example:

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

  4. Run the following command to query the certificate: 
    curl https://demo.alb.ingress.top/tea
    Expected output.
    {"hello":"tea"}

Redirect HTTP requests to HTTPS

You can configure an ALB Ingress to redirect HTTP requests to HTTPS port 443 by adding the alb.ingress.kubernetes.io/ssl-redirect: "true" annotation.

Example:

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

Configure the HTTPS or gRPC protocol

ALB Ingresses support the HTTPS or gRPC protocol. To configure HTTPS or gRPC, add the alb.ingress.kubernetes.io/backend-protocol: "grpc" or alb.ingress.kubernetes.io/backend-protocol: "https" annotation. If you want to use an Ingress to distribute requests to a gRPC service, you must configure an SSL certificate for the gRPC service and use the TLS protocol to communicate with the gRPC service. Example: 

apiVersion: networking.k8s.io/v1beta1
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:
          - backend:
              serviceName: grpc-demo-svc
              servicePort: 9080
            path: /
            pathType: Prefix
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

Configure rewrite rules

ALB Ingresses support rewrite rules. To configure rewrite rules, add the alb.ingress.kubernetes.io/rewrite-target: /path/${2} annotation.

Note
  • In the rewrite-target annotation, you must set the type of the path parameter to Prefix for a capturing group of the ${number} type.
  • By default, the path parameter does not support characters that are supported by regular expressions, such as asterisks (*) and question marks (?). To specify characters that are supported by regular expressions in the path parameter, you must add the rewrite-target annotation.
  • The value of the path parameter must start with a forward slash (/). 
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/rewrite-target: /path/${2}
  name: rewrite-ingress
spec:
  ingressClassName: alb
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: rewrite-svc
              servicePort: 9080
            path: /something(/|$)(.*)
            pathType: Prefix
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    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

Configure custom listening ports

ALB Ingresses allow you to configure custom listening ports. This allows you to expose port 80 and port 443 for a Service at the same time. Example: 

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

Configure forwarding rule priorities

You can add an annotation to the configuration of an Ingress to configure the priorities of the forwarding rules of the Ingress.

Note The priority of each forwarding rule within a listener must be unique. You can use the alb.ingress.kubernetes.io/order annotation to specify the priorities of the forwarding rules of an Ingress. Valid values: 1 to 1000. A lower value indicates a higher priority. 
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-svc
            pathType: ImplementationSpecific
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

Use annotations to perform phased releases

ALB allows you to configure phased releases based on request headers, cookies, and weights to handle complex traffic routing. You can add the alb.ingress.kubernetes.io/canary: "true" annotation to enable the phased release feature. Then, you can use the following annotations to configure different phased release rules.

Note Phased releases that use different rules take effect in the following order: header-based > cookie-based > weight-based.
  • alb.ingress.kubernetes.io/canary-by-header and alb.ingress.kubernetes.io/canary-by-header-value: This rule matches the headers and header values of requests. You must add both annotations if you want to use this rule.
    • If the header and header value of a request match the rule, the request is routed to the new application version.
    • If the header of a request fails to match the header-based rule, the request is matched against other types of rules based on the priorities of the rules.
    If you set the alb.ingress.kubernetes.io/canary-by-header annotation to location: hz, requests that match the rule are routed to the new application version. Requests that fail to match the rule are routed based on weight-based rules. Example: 
    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
    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

  • alb.ingress.kubernetes.io/canary-by-cookie: This rule matches the cookies of requests.
    • If you set cookie to always, requests that match the rule are routed to the new application version.
    • If you set cookie to never, requests that match the rule are routed to the old application version.
    Note Cookie-based phased release rules do not support other settings. The cookie value must be always or never.
    Requests that contain the demo=always cookie are routed to the new application version. Example: 
    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
    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

  • alb.ingress.kubernetes.io/canary-weight: This rule allows you to set the percentage of requests that are sent to a specified Service. You can enter an integer from 0 to 100.

    In the following example, the percentage of requests that are routed to the new application version is set to 50%: 

    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
    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 by using annotations

ALB Ingresses allow you to configure session persistence by using the following annotations:
  • alb.ingress.kubernetes.io/sticky-session: specifies whether to enable session persistence. Valid values: true and false. Default value: false.
  • alb.ingress.kubernetes.io/sticky-session-type: the method that is used to handle a cookie. Valid values: Insert and Server. Default value: Insert.
    • Insert: inserts a cookie. ALB inserts a cookie (SERVERID) into the first HTTP or HTTPS response packet that is sent to a client. The next request from the client contains this cookie and the listener distributes this request to the recorded backend server.
    • Server: rewrites a cookie. When CLB detects a user-defined cookie, it overwrites the original cookie with the user-defined cookie. The next request from the client will contain the user-defined cookie, and the listener will distribute this request to the recorded backend server.
    Note This parameter takes effect when the StickySessionEnabled parameter is set to true for the server group.
  • alb.ingress.kubernetes.io/cookie-timeout: specifies the timeout period of cookies. Valid values: 1 to 86400. Default value: 1000. Unit: seconds. 
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"
    alb.ingress.kubernetes.io/cookie-timeout: "1800"
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
# Configure a context path. 
      - path: /tea2
        backend:
          serviceName: tea-svc
          servicePort: 80
# Configure a context path. 
      - path: /coffee2
        backend:
          serviceName: coffee-svc
          servicePort: 80
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:
# Configure a context path. 
      - path: /tea2
        backend:
          service:
            name: tea-svc
            port: 
             number: 80
# Configure a context path. 
       - path: /coffee2
         backend:
           service:
              name: coffee-svc
              port: 
               number: 80