All Products
Search
Document Center

Container Service for Kubernetes:Advanced ALB Ingress configurations for registered clusters

Last Updated:Jan 04, 2024

Application Load Balancer (ALB) Ingresses in registered clusters are API objects used to manage external user access to Services in the clusters and provide Layer 7 load balancing capabilities. This topic describes how to create ALB Ingresses to route traffic destined for different domain names or URLs to backend server groups, redirect requests from HTTP to HTTPS, and perform canary releases.

Prerequisites

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.

    Clusters that run Kubernetes versions earlier than 1.19

    apiVersion: v1
    kind: Service
    metadata:
      name: demo-service
      namespace: default
    spec:
      ports:
        - name: port1
          port: 80
          protocol: TCP
          targetPort: 8080
      selector:
        app: demo
      sessionAffinity: None
      type: 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

    Clusters that run Kubernetes 1.19 or later

    apiVersion: v1
    kind: Service
    metadata:
      name: demo-service
      namespace: default
    spec:
      ports:
        - name: port1
          port: 80
          protocol: TCP
          targetPort: 8080
      selector:
        app: demo
      sessionAffinity: None
      type: 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:

    Clusters that run Kubernetes versions earlier than 1.19

    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

    Clusters that run Kubernetes 1.19 or later

    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.

Note

URL match policies may conflict with each other. When conflicting URL match policies exist, requests are matched against these policies in the descending order of policy priorities. For more information, see Configure forwarding rule priorities.

Match mode

Rule

URL path

Whether the URL path matches the rule

Prefix

/

(All paths)

Yes

Prefix

/foo

  • /foo

  • /foo/

Yes

Prefix

/foo/

  • /foo

  • /foo/

Yes

Prefix

/aaa/bb

/aaa/bbb

No

Prefix

/aaa/bbb

/aaa/bbb

Yes

Prefix

/aaa/bbb/

/aaa/bbb

Yes. The rule ignores the trailing forward slash (/).

Prefix

/aaa/bbb

/aaa/bbb/

Yes. The rule matches the trailing forward slash.

Prefix

/aaa/bbb

/aaa/bbb/ccc

Yes. The rule matches subpaths.

Prefix

Set two rules at the same time:

  • /

  • /aaa

/aaa/ccc

Yes. The URL path matches the / rule.

Prefix

Set two rules at the same time:

  • /aaa

  • /

/aaa/ccc

Yes. The URL path matches the /aaa rule.

Prefix

Set two rules at the same time:

  • /aaa

  • /

/ccc

Yes. The URL path matches the / rule.

Prefix

/aaa

/ccc

No

Exact or ImplementationSpecific

/foo

/foo

Yes

Exact or ImplementationSpecific

/foo

/bar

No

Exact or ImplementationSpecific

/foo

/foo/

No

Exact or ImplementationSpecific

/foo/

/foo

No

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

Exact

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

    Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

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

The ALB Ingress configuration is the same as that for the Exact match policy.

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

  2. Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: demo-path
      namespace: default
    spec:
      ingressClassName: alb
      rules:
        - http:
            paths:
            - path: /hello
              backend:
                service:
                  name: demo-service
                  port:
                    number: 80
              pathType: ImplementationSpecific
  3. Run the following command to access the application.

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

  5. curl <ADDRESS>/hello

    Expected output:

    {"hello":"coffee"}

Prefix

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

  2. Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: demo-path-prefix
      namespace: default
    spec:
      ingressClassName: alb
      rules:
        - http:
            paths:
            - path: /
              backend:
                service:
                  name: demo-service
                  port:
                    number: 80
              pathType: Prefix
  3. Run the following command to access the application.

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

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

Clusters that run Kubernetes versions earlier than 1.19

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

Clusters that run Kubernetes 1.19 or 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-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 based on which health checks are performed. Default value: /.

  • Enter the URL of the web page 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.

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.

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

Valid values: http_2xx (default), http_3xx, http_4xx, and http_5xx.

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 a redirection from HTTP requests to HTTPS requests

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

Important

When you add the annotation for redirection, make sure that you specify the listening ports and listening protocols that are used before and after the redirection in ALB Ingress configurations.

Example:

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

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: 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 annotation alb.ingress.kubernetes.io/backend-protocol: "grpc" or alb.ingress.kubernetes.io/backend-protocol: "https". If you want to use an Ingress to distribute requests to the gRPC service, you must configure an SSL certificate for the gRPC service and use the TLS protocol to communicate with the gRPC service. Example:

Note

You cannot modify the backend protocol. If you need to change the protocol, delete and rebuild the Ingress.

Clusters that run Kubernetes versions earlier than 1.19

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

Clusters that run Kubernetes 1.19 or later

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 annotation alb.ingress.kubernetes.io/rewrite-target: /path/${2}. The following rules apply:

  • 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 used 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 (/).

Note

If you want to specify regular expressions in rewrite rules, take note of the following items:

  • You can specify one or more regular expressions in the path parameter of an ALB Ingress and use parentheses () to enclose the regular expressions. However, you can use at most three variables (${1}, ${2}, and ${3}) in the rewrite-target annotation to form the path that overwrites the original path.

  • Variables that match the regular expressions are concatenated to form the path that overwrites the original path.

  • The original path is overwritten by the variables that match the regular expressions only if the following requirements are met: Multiple regular expressions that are enclosed in parentheses () are specified and the rewrite-target annotation is set to one or more of the following variables: ${1}, ${2}, and ${3}.

Assume that the path parameter of an ALB Ingress is set to /sys/(.*)/(.*)/aaa and the rewrite-target annotation is set to /${1}/${2}. If the client sends a request to the /sys/ccc/bbb/aaa path, the request matches the regular expression /sys/(.*)/(.*)/aaa. The rewrite-target annotation takes effect and replaces ${1} with ccc and ${2} with bbb. As a result, the request is redirected to /ccc/bbb.

Clusters that run Kubernetes versions earlier than 1.19

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

Clusters that run Kubernetes 1.19 or later

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 a service through ports 80 and 443 at the same time.

Clusters that run Kubernetes versions earlier than 1.19

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

Clusters that run Kubernetes 1.19 or later

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

Configure forwarding rule priorities

By default, forwarding rules are prioritized based on the following rules:

  • Forwarding rules of different ALB Ingresses are prioritized in the lexicographical order of the values of the namespace/name parameter. A forwarding rule whose namespace/name value appears the first among all forwarding rules in the lexicographical order has the highest priority.

  • The forwarding rules of an ALB Ingress are displayed in descending order of priority in the rule parameter.

If you do not want to use the namespace/name parameter of an ALB Ingress to prioritize forwarding rules, you can use the following annotation instead:

Note

The priority of each forwarding rule within a listener must be unique. You can use the annotation alb.ingress.kubernetes.io/order to specify the priorities of the forwarding rules of an ALB Ingress. Valid values: 1 to 1000. A smaller value indicates a higher priority. The default value is 10. If you want to specify a higher priority, set the value to a smaller number.

Clusters that run Kubernetes versions earlier than 1.19

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

Clusters that run Kubernetes 1.19 or later

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

Use annotations to perform phased releases

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

Note
  • Canary releases that use different rules take effect in the following order: header-based > cookie-based > weight-based.

  • When you perform canary releases to test a new application version, do not modify the original Ingress rules. Otherwise, access to the application may be interrupted. After the new application version passes the test, replace the backend Service used by the earlier application version with the backend Service used by the new application version. Then, delete the Ingress rules for implementing canary releases.

  • 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 does not 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:

    Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

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

    Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

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

    Clusters that run Kubernetes versions earlier than 1.19

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

    Clusters that run Kubernetes 1.19 or later

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

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

Clusters that run Kubernetes versions earlier than 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"
    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

Clusters that run Kubernetes 1.19 or later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress-v3
  annotations:
    alb.ingress.kubernetes.io/sticky-session: "true"
    alb.ingress.kubernetes.io/sticky-session-type: "Insert"
    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

Specify a load balancing algorithm for backend server groups

ALB Ingresses allow you to specify a load balancing algorithm for backend server groups by using the annotation alb.ingress.kubernetes.io/backend-scheduler. Example:

Clusters that run Kubernetes versions earlier than 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # Replace uch with wrr, sch, or wlc based on your business requirements. 
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # This parameter is required only when the load balancing algorithm is uch. You do not need to configure this parameter when the scheduling algorithm is wrr, sch, or wlc. 
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
    - host: demo.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: tea-svc
              servicePort: 80
            path: /tea-svc
            pathType: ImplementationSpecific

Clusters that run Kubernetes 1.19 or later

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    alb.ingress.kubernetes.io/backend-scheduler: "uch" # Replace uch with wrr, sch, or wlc based on your business requirements. 
    alb.ingress.kubernetes.io/backend-scheduler-uch-value: "test" # This parameter is required only when the load balancing algorithm is uch. You do not need to configure this parameter when the scheduling algorithm is wrr, sch, or wlc. 
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80

Set the annotation alb.ingress.kubernetes.io/backend-scheduler based on the following description:

  • wrr: Backend servers that have higher weights receive more requests than those that have lower weights. This is the default value.

  • wlc: Requests are distributed based on the weight and load of each backend server. The load refers to the number of connections to a backend server. If multiple backend servers have the same weight, requests are forwarded to the backend server with the least connections.

  • sch: consistent hashing that is based on source IP addresses.

  • uch: consistent hashing that is based on URL parameters. You can add the annotation alb.ingress.kubernetes.io/backend-scheduler-uch-value to the ALB Ingress to specify URL parameters for consistent hashing when the load balancing algorithm for backend server groups is uch.

Configure CORS

The following code block shows an example of the Cross-Origin Resource Sharing (CORS) configuration supported by the 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

Parameter

Description

alb.ingress.kubernetes.io/cors-allow-origin

The URLs that can be used to access resources on the origin server by using a browse. Separate multiple URLs with commas (,). Each URL must start with http:// or https:// and contain a valid domain name or a top-level wildcard domain name.

Default value: *. Example: alb.ingress.kubernetes.io/cors-allow-origin: "https://example.com:4443, http://aliyundoc.com, https://example.org:1199".

alb.ingress.kubernetes.io/cors-allow-methods

The HTTP methods that are allowed to use. The values are not case-sensitive. Separate multiple HTTP methods with commas (,).

Default value: GET, PUT, POST, DELETE, PATCH, OPTIONS. Example: alb.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS".

alb.ingress.kubernetes.io/cors-allow-headers

The request headers that are allowed to use. The request headers can contain letters, digits, underscores (_), and hyphens (-). Separate multiple request headers with commas (,).

Default value: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization. Example: alb.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO".

alb.ingress.kubernetes.io/cors-expose-headers

The headers that are allowed to expose. The headers can contain letters, digits, underscores (_), hyphens (-), and asterisks (*). Separate multiple headers with commas (,).

Default value: empty. Example: alb.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader".

alb.ingress.kubernetes.io/cors-allow-credentials

Specifies whether to carry credentials in CORS requests.

Default value: true. Example: alb.ingress.kubernetes.io/cors-allow-credentials: "false".

alb.ingress.kubernetes.io/cors-max-age

Specifies the maximum amount of time for which a preflight request that uses the OPTIONS method can be cached. Set this parameter for complex requests. Valid values: -1 to 172800. Unit: seconds.

Default value: 172800.

Configure persistent TCP connections

Traditional load balancers access backend servers over short-lived connections. A traditional load balancer needs to create a connection and then close the connection each time it forwards a request to a backend server. Consequently, network connections become the performance bottleneck. To reduce the amount of resources consumed by establishing network connections and improve the forwarding performance, you can use the persistent TCP connection feature. You can add the alb.ingress.kubernetes.io/backend-keepalive annotation to the ALB Ingress to enable the persistent TCP connection feature. Example:

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

Configure QPS throttling

ALB supports QPS throttling based on forwarding rules. You can limit the QPS to a range of 1 to 100000. You can add the alb.ingress.kubernetes.io/traffic-limit-qps annotation to the ALB Ingress to enable the QPS throttling feature. Example:

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