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

Forward requests based on domain names

Perform the following steps to create a simple Ingress with or without a domain name to forward requests.

  • Create a simple Ingress with a domain name.
    1. Use the following template to create an Ingress:
      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:
        annotations:
          alb.ingress.kubernetes.io/address-type: internet
          alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
          kubernetes.io/ingress.class: alb
        name: demo
        namespace: default
      spec:
        rules:
          - host: demo.domain.ingress.top
            http:
              paths:
                - backend:
                    serviceName: demo-service
                    servicePort: 80
                  path: /hello
                  pathType: ImplementationSpecific
    2. Run the following command to access the application by using the specified domain name.

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

      curl -H "host: demo.domain.ingress.top" <ADDRESS>/hello
      Expected output:
      {"hello":"coffee"}
  • Create a simple Ingress without a domain name.
    1. Use the following template to create an Ingress:
      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        annotations:
          alb.ingress.kubernetes.io/address-type: internet
          alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
          kubernetes.io/ingress.class: alb
        name: demo
        namespace: default
      spec:
        rules:
          - host: ""
            http:
              paths:
                - backend:
                    serviceName: demo-service
                    servicePort: 80
                  path: /hello
                  pathType: ImplementationSpecific
    2. Run the following command to access the application without using a domain name.

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

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

Forward requests based on URL paths

ALB Ingresses support request forwarding 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.

The following steps show how to configure different URL match policies.

  • Exact: exactly matches the URL path with case sensitivity.
    1. Use the following template to create an Ingress:
      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        annotations:
          alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
          kubernetes.io/ingress.class: alb
        name: demo-path
        namespace: default
      spec:
        rules:
          - http:
              paths:
              - path: /hello
                backend:
                  serviceName: demo-service
                  servicePort: 80
                pathType: Exact
    2. Run the following command to access the application.

      Replace ADDRESS with the address of the related ALB instance. You can obtain the 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 Ingresses with the Exact policy are implemented in different ways.
    1. Use the following template to create an Ingress:

      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        annotations:
          alb.ingress.kubernetes.io/address-type: internet
          alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
          kubernetes.io/ingress.class: alb
        name: demo-path
        namespace: default
      spec:
        rules:
          - http:
              paths:
              - path: /hello
                backend:
                  serviceName: demo-service
                  servicePort: 80
                pathType: ImplementationSpecific
    2. Run the following command to access the application.

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

      curl <ADDRESS>/hello
      Expected output:
      {"hello":"coffee"}
  • Prefix: matches based on a URL path prefix separated by forward slashes (/). The match is case-sensitive and performed on each element of the path.
    1. Use the following template to create an Ingress:
      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        annotations:
          alb.ingress.kubernetes.io/address-type: internet
          alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
          kubernetes.io/ingress.class: alb
        name: demo-path-prefix
        namespace: default
      spec:
        rules:
          - http:
              paths:
              - path: /
                backend:
                  serviceName: demo-service
                  servicePort: 80
                pathType: Prefix
    2. Run the following command to access the application.

      Replace ADDRESS with the address of the related ALB instance. You can obtain the 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:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/address-type: internet
    alb.ingress.kubernetes.io/vswitch-ids: "vsw-k1akdsmts6njkvhas****,vsw-k1amdv9ax94gr5iwa****"
    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:
  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
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 path at 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 special 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 the 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 path.
alb.ingress.kubernetes.io/healthcheck-protocol Optional. The protocol used by 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 used by health checks.
  • HEAD: By default, HTTP health checks send HEAD requests to a backend server. This is the default method. Make sure that your backend server supports HEAD requests. If your backend server does not support HEAD requests or HEAD requests are disabled, health checks may fail. In this case, you can use GET requests to perform health checks.
  • 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 POST requests or POST requests are disabled, health checks may fail. In this case, you can use GET requests to perform health checks.
  • GET: If the length of a response packet exceeds 8 KB, the response is truncated. However, the health check result is not affected.
alb.ingress.kubernetes.io/healthcheck-httpcode Specify the status codes that are returned when health check results are normal.
  • When the health check protocol is set to HTTP, the 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. Separate multiple value ranges with commas (,).
alb.ingress.kubernetes.io/healthcheck-timeout-seconds Specifies the timeout period of a health check. If a backend server does not respond within the specified timeout period, the server fails the health check. Valid values: 1 to 300. Default value: 5. Unit: seconds.
alb.ingress.kubernetes.io/healthcheck-interval-seconds The interval at which health checks are performed. Unit: seconds. Valid values: 1 to 50. Default value: 2. Unit: seconds.
alb.ingress.kubernetes.io/healthy-threshold-count Specifies 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 Specifies 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 match and discover the certificate based on the domain name specified in the Ingress configuration.

  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, see Upload certificates.

  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
    The following code block is an 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:
      annotations:
        alb.ingress.kubernetes.io/address-type: internet
        alb.ingress.kubernetes.io/vswitch-ids: "vsw-k1akdsmts6njkvhas****,vsw-k1amdv9ax94gr5iwa****"
        kubernetes.io/ingress.class: alb
      name: demo-https
      namespace: default
    spec:
      # 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
  4. Run the following command to query the certificate:
    curl https://demo.alb.ingress.top/tea
    Expected output:
    {"hello":"tee"}

Redirect HTTP requests to HTTPS

To redirect HTTP requests to HTTPS, you can add the alb.ingress.kubernetes.io/ssl-redirect: "true" annotation to the ALB Ingress configurations. This way, HTTP requests are redirected to HTTPS port 443.

The following code block is an 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:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/vswitch-ids: "vsw-k1akdsmts6njkvhas****,vsw-k1amdv9ax94gr5iwa****"
    alb.ingress.kubernetes.io/ssl-redirect: "true"
  name: demo-ssl
  namespace: default
spec:
  tls:
  - hosts:
    - ssl.alb.ingress.top
  rules:
    - host: ssl.alb.ingress.top
      http:
        paths:
          - backend:
              serviceName: demo-service-ssl
              servicePort: 80
            path: /
            pathType: Prefix

Use annotations to implement canary releases

ALB can handle complex traffic routing scenarios and support canary releases based on request headers, cookies, and weights. You can implement canary releases by adding annotations to Ingress configurations. To enable canary releases, you must add the nginx.ingress.kubernetes.io/canary: "true" annotation. This section describes how to use different annotations to implement canary releases.

Note Canary releases that use different rules take effect in the following order: header-based > cookie-based > weight-based.
Parameter Description Reference
alb.ingress.kubernetes.io/canary-by-header and alb.ingress.kubernetes.io/canary-by-header-value Traffic splitting based on the value of the request header. This parameter must be used in combination with alb.ingress.kubernetes.io/canary-by-header.
  • If the header and header value of a request match the rule, the request is routed to the new application version.
  • Requests whose header values do not match the rule are routed based on rules other than the request header values.
If a request has location: hz specified, the request is routed to the new application version. Otherwise, the request is routed based on other rules other than the request header.
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/albconfig.order: "1"
    alb.ingress.kubernetes.io/vswitch-ids: "vsw-k1akdsmts6njkvhas****,vsw-k1amdv9ax94gr5iwa****"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-header: "location"
    alb.ingress.kubernetes.io/canary-by-header-value: "hz"
alb.ingress.kubernetes.io/canary-by-cookie Traffic splitting based on cookies:
  • 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 does not support custom settings. The cookie value must be always or never.
Requests with the demo=always cookie are routed to the new application version.
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/albconfig.order: "2"
    alb.ingress.kubernetes.io/address-type: internet
    alb.ingress.kubernetes.io/vswitch-ids: "vsw-k1akdsmts6njkvhas****,vsw-k1amdv9ax94gr5iwa****"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-by-cookie: "demo"
alb.ingress.kubernetes.io/canary-weight Traffic splitting based on weights. The weight is a percentage value that ranges from 0 to 100. The following template specifies that 50% of the traffic is routed to the new application version.
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/albconfig.order: "3"
    alb.ingress.kubernetes.io/address-type: internet
    alb.ingress.kubernetes.io/vswitch-ids: "vsw-2zeqgkyib34gw1fxs****,vsw-2zefv5qwao4przzlo****"
    alb.ingress.kubernetes.io/canary: "true"
    alb.ingress.kubernetes.io/canary-weight: "50"