Use ALB Ingress in Container Service ACK

Updated at:

ALB Ingress offers advanced Ingress traffic management, built on Alibaba Cloud Application Load Balancer (ALB). It is compatible with NGINX Ingress, supports complex business routing and automatic certificate discovery, and works with the HTTP, HTTPS, and QUIC protocols to meet the demands for elasticity and large-scale Layer 7 load balancing in cloud-native applications. Use this topic to learn how to deploy services in an ACK cluster and access them through an ALB Ingress.

Background information

This section explains the key concepts of ALB Ingress.

  • ALB Ingress controller: An Ingress controller is a component in Kubernetes that manages Ingress resources. It acts as an entry point within the cluster, routing external traffic to the appropriate Services. The ALB Ingress controller watches the API server for changes to Ingress resources and dynamically generates AlbConfig resources. It then creates or updates the corresponding ALB instances, listeners, routing rules, and backend server groups.

  • AlbConfig CRD: A Custom Resource Definition (CRD) is a Kubernetes mechanism that extends the Kubernetes API and provides a way to define custom resource types. Each AlbConfig resource corresponds to one ALB instance.

  • IngressClass: An IngressClass is a Kubernetes resource that specifies which Ingress controller handles an Ingress. This allows you to use multiple Ingress controllers within the same cluster and assign a specific controller to each Ingress resource.

  • Ingress: An Ingress is a Kubernetes resource that defines rules for managing external access to Services in a cluster, typically for HTTP and HTTPS traffic. It relies on an Ingress controller to implement traffic forwarding. For ALB Ingress, you can configure routing rules using annotations. Once configured, ALB Ingress forwards HTTP and HTTPS requests to the corresponding Services based on the rules in the annotations.

  • Service: In Kubernetes, a Service is an abstraction that defines a logical set of Pods and provides them with a stable virtual IP address and port.

    A Service provides a stable entry point for an application. This allows other applications or services to communicate with backend Pods using the Service's virtual IP address and port, without knowing the specific IP addresses of individual Pods. A single Service can represent multiple identical backend Pods.

The figure below illustrates the logical relationship between an ALB instance and ALB Ingress.

ALB Ingress

Limitations

  • If you use the Flannel network plugin, backend Services for an ALB Ingress must be of type NodePort or LoadBalancer.

  • The names of AlbConfig, namespace, Ingress, and Service resources cannot start with aliyun.

  • Older versions of the Nginx Ingress Controller cannot recognize the spec:ingressClassName field in an Ingress resource. If both Nginx Ingress and ALB Ingress controllers are running in the same cluster, an older Nginx Ingress Controller might incorrectly reconcile your ALB Ingresses. To prevent this, upgrade your Nginx Ingress Controller or use an annotation to specify the IngressClass for your ALB Ingresses. For more information, see Upgrade the NGINX Ingress Controller or Advanced ALB Ingress usage.

Example scenario

This tutorial shows how to configure an ALB Ingress to forward traffic to different URL paths under the same domain, using an example of four Nginx pods.

Frontend request

Forwarded to

demo.domain.ingress.top/coffee

coffee service

demo.domain.ingress.top/tea

tea service

Prerequisites

Step 1: Install the ALB Ingress controller

To use ALB Ingress, install the ALB Ingress controller.

Install during cluster creation

When creating an ACK managed or dedicated cluster, go to the Ingress section and select ALB Ingress.

Set ALB Instance to New, Existing, or None:

Instance source

Description

What gets created

(Recommended) New

Create an ALB instance:
- Network Type: Internet or Intranet
- VPC: defaults to the cluster VPC
- vSwitch: two vSwitches in different zones; auto-selected if blank. To create vSwitches, click Create vSwitch.
See ALB billing rules.



An AlbConfig named alb and a corresponding IngressClass resource. Default: HTTP listener on port 80. To add HTTPS, see Create an HTTPS listener.

(Recommended) Existing

Select an existing ALB instance. Basic ALB instances are not supported. See Reuse an existing ALB instance.

An AlbConfig named alb and a corresponding IngressClass resource, bound to the selected ALB instance.

(Optional) None

Install the controller without creating an ALB instance. Use this when specifying ALB instances in Ingress YAML.

No ALB instance or related resources are created. You must manually create an AlbConfig and IngressClass.

Install on an existing cluster

  1. Log on to the ACK console. In the left navigation pane, click Clusters.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons.

  3. On the Add-ons page, click the Networking tab. In the Networking section, click Install on the ALB Ingress Controller card.

  4. In the Install ALB Ingress Controller dialog box, select New, Existing, or None for ALB Instance, configure the remaining parameters, and click OK.

    Instance source

    Description

    Result

    (Recommended)New

    • Network Type: Create an Internet or Private Network ALB instance as needed. For more information about billing, see ALB billing.

    • VPC: The default value is the VPC of the cluster.

    • vSwitch: Displays the virtual switches in the zones that the ALB instance supports within this VPC. Specify two vSwitches in different zones. If you do not specify vSwitches, the system automatically selects two active vSwitches. You can also click Create vSwitch to create a new vSwitch.

    The Controller automatically creates an AlbConfig resource named alb and a corresponding IngressClass resource. The AlbConfig includes a default listener that uses the HTTP protocol on port 80. For more information about listener extensions, see Configure ALB instances with AlbConfig.

    (Recommended)Existing

    Select an existing ALB instance from the drop-down list. Basic Edition ALB instances are not supported. For more information, see Configure ALB instances with AlbConfig.

    (Optional)None

    Does not create an ALB instance. Installs only the ALB Ingress Controller component.

    Important

    The Controller does not create the corresponding resources. Manually create an AlbConfig and an IngressClass.

Note

To use ALB Ingress to access services in an ACK dedicated cluster, you must grant the required permissions to the ALB Ingress controller before you deploy the services. For more information, see Grant permissions to the ALB Ingress controller for an ACK dedicated cluster.

Step 2: Deploy backend services

Console

  1. Log on to the ACK console.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Deployments.

  3. Click Create Resources in YAML.

    1. Sample Template: Select Custom.

    2. Template: Enter the following YAML configuration. This configuration creates two Deployments named coffee and tea, and two Services named coffee-svc and tea-svc.

      Sample YAML

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: coffee
      spec:
        replicas: 2
        selector:
          matchLabels:
            app: coffee
        template:
          metadata:
            labels:
              app: coffee
          spec:
            containers:
            - name: coffee
              image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
              ports:
              - containerPort: 80
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: coffee-svc
      spec:
        ports:
        - port: 80
          targetPort: 80
          protocol: TCP
        selector:
          app: coffee
        type: NodePort
      ---
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: tea
      spec:
        replicas: 2
        selector:
          matchLabels:
            app: tea
        template:
          metadata:
            labels:
              app: tea
          spec:
            containers:
            - name: tea
              image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
              ports:
              - containerPort: 80
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: tea-svc
      spec:
        ports:
        - port: 80
          targetPort: 80
          protocol: TCP
        selector:
          app: tea
        type: NodePort
  4. Click Create. The message Created. is displayed.

  5. Verify that the Deployments and Services were created:

    1. In the left-side navigation pane, choose Workloads > Deployments. The coffee and tea Deployments are displayed.

    2. In the left-side navigation pane, choose Network > Services. The coffee-svc and tea-svc Services are displayed.

CLI

  1. Create a YAML file named cafe-service.yaml and copy the following content into the file. This file deploys two Deployments named coffee and tea, and two Services named coffee-svc and tea-svc.

    Sample YAML

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: coffee
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: coffee
      template:
        metadata:
          labels:
            app: coffee
        spec:
          containers:
          - name: coffee
            image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
            ports:
            - containerPort: 80
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: coffee-svc
    spec:
      ports:
      - port: 80
        targetPort: 80
        protocol: TCP
      selector:
        app: coffee
      type: NodePort
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: tea
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: tea
      template:
        metadata:
          labels:
            app: tea
        spec:
          containers:
          - name: tea
            image: registry.cn-hangzhou.aliyuncs.com/acs-sample/nginxdemos:latest
            ports:
            - containerPort: 80
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: tea-svc
    spec:
      ports:
      - port: 80
        targetPort: 80
        protocol: TCP
      selector:
        app: tea
      type: NodePort
  2. Run the following command to deploy the two Deployments and two Services:

    kubectl apply -f cafe-service.yaml

    Expected output:

    deployment "coffee" created
    service "coffee-svc" created
    deployment "tea" created
    service "tea-svc" created
  3. Run the following commands to check the status of the Deployments and Services.

    1. Check the status of the Deployments:

      kubectl get deployment

      Expected output:

      NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
      coffee                           1/2     2            1           2m26s
      tea                              1/1     1            1           2m26s
    2. Check the status of the Services:

      kubectl get svc

      Expected output:

      NAME                          TYPE           CLUSTER-IP       EXTERNAL-IP           PORT(S)                 AGE
      coffee-svc                    NodePort       172.16.XX.XX     <none>                80:32056/TCP            9m38s
      tea-svc                       NodePort       172.16.XX.XX     <none>                80:31696/TCP            9m38s

Step 3: Create an AlbConfig

Note

If you set ALB Instance Source to New or Existing in Step 1: Install the ALB Ingress controller, the controller automatically creates an AlbConfig resource and an IngressClass resource, both named alb. In this case, you can skip this step.

Console

  1. Log on to the ACK console.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Custom Resources.

  3. On the Custom Resources page, click the CRDs tab, and then click Create Resources in YAML.

    1. Sample Template: Select Custom.

    2. Template: Paste the following YAML manifest into the editor.

      Sample YAML

      apiVersion: alibabacloud.com/v1
      kind: AlbConfig
      metadata:
        name: alb
      spec:
        config:
          name: alb-test
          addressType: Internet
          zoneMappings:
          - vSwitchId: vsw-uf6ccg2a9g71hx8go****
          - vSwitchId: vsw-uf6nun9tql5t8nh15****
        listeners:
          - port: 80
            protocol: HTTP

      The following table describes the parameters.

      Parameter

      Required

      Description

      metadata.name

      Yes

      The name of the AlbConfig resource.

      Note

      The name must be unique within the cluster to prevent conflicts.

      spec.config.name

      No

      The name of the ALB instance.

      spec.config.addressType

      No

      The network type of the ALB instance. Valid values:

      • Internet (default): Internet-facing. The ALB instance is accessible from the internet.

        Note

        Application Load Balancers provide Internet-facing services through an associated Elastic IP Address (EIP). If you use an Internet-facing ALB instance, you are charged for the EIP instance and for bandwidth or data transfer. For more information, see pay-as-you-go.

      • Intranet: internal-facing. The ALB instance is accessible only from within the VPC.

      spec.config.zoneMappings

      Yes

      The IDs of the vSwitches. For information about how to create a vSwitch, see Create and manage vSwitches.

      Note
      • The specified vSwitches must be in zones that support ALB and must be in the same VPC as your cluster. For more information about supported regions and zones, see Regions and zones that support ALB.

      • Application Load Balancer supports multi-zone deployment. To ensure high availability, select vSwitches in at least two different zones.

      spec.listeners

      No

      The listener configuration for the ALB instance, including the port and protocol. This example configures an HTTP listener on port 80.

      A listener defines how traffic is routed by the load balancer. We recommend that you retain this configuration. Otherwise, you must create a listener separately before you can use the ALB Ingress.

  4. After you complete the configuration, click Create. A Created. message appears.

  5. Verify that the ALB instance is created successfully:

    1. Log on to the Application Load Balancer (ALB) console.

    2. In the top navigation bar, select the region where the instance is deployed.

    3. On the Instances page, find the ALB instance named alb-test in the instance list. If the instance appears in the list, it was created successfully.

kubectl

  1. Create a file named alb-test.yaml and paste the following content into it.

    Sample YAML

    apiVersion: alibabacloud.com/v1
    kind: AlbConfig
    metadata:
      name: alb
    spec:
      config:
        name: alb-test
        addressType: Internet
        zoneMappings:
        - vSwitchId: vsw-uf6ccg2a9g71hx8go****
        - vSwitchId: vsw-uf6nun9tql5t8nh15****
      listeners:
        - port: 80
          protocol: HTTP

    The following table describes the parameters.

    Parameter

    Required

    Description

    metadata.name

    Yes

    The name of the AlbConfig resource.

    Note

    The name must be unique within the cluster to prevent conflicts.

    spec.config.name

    No

    The name of the ALB instance.

    spec.config.addressType

    No

    The network type of the ALB instance. Valid values:

    • Internet (default): Internet-facing. The ALB instance is accessible from the internet.

      Note

      Application Load Balancers provide Internet-facing services through an associated Elastic IP Address (EIP). If you use an Internet-facing ALB instance, you are charged for the EIP instance and for bandwidth or data transfer. For more information, see pay-as-you-go.

    • Intranet: internal-facing. The ALB instance is accessible only from within the VPC.

    spec.config.zoneMappings

    Yes

    The IDs of the vSwitches. For information about how to create a vSwitch, see Create and manage vSwitches.

    Note
    • The specified vSwitches must be in zones that support ALB and must be in the same VPC as your cluster. For more information about supported regions and zones, see Regions and zones that support ALB.

    • Application Load Balancer supports multi-zone deployment. To ensure high availability, select vSwitches in at least two different zones.

    spec.listeners

    No

    The listener configuration for the ALB instance, including the port and protocol. This example configures an HTTP listener on port 80.

    A listener defines how traffic is routed by the load balancer. We recommend that you retain this configuration. Otherwise, you must create a listener separately before you can use the ALB Ingress.

  2. Run the following command to create the AlbConfig resource:

    kubectl apply -f alb-test.yaml

    Expected output:

    albconfig.alibabacloud.com/alb created

Step 4: Create IngressClass

We recommend creating an IngressClass for each AlbConfig.

Note

If you set ALB Instance Source to New or Existing in Step 1: Install the ALB Ingress controller, the controller automatically creates an AlbConfig resource and an IngressClass resource, both named alb. In this case, you can skip this step.

Console

  1. Log on to the ACK console.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Workloads > Custom Resources.

  3. On the Custom Resources page, click the CRDs tab, and then click Create Resources in YAML.

    1. Sample Template: Select Custom.

    2. Template: In the editor, paste the following YAML.

      Sample YAML

      apiVersion: networking.k8s.io/v1
      kind: IngressClass
      metadata:
        name: alb
      spec:
        controller: ingress.k8s.alibabacloud/alb
        parameters:
          apiGroup: alibabacloud.com
          kind: AlbConfig
          name: alb

      The following table describes the parameters.

      Parameter

      Required

      Description

      metadata.name

      Yes

      The name of the IngressClass.

      Note

      The IngressClass name must be unique within the cluster to prevent naming conflicts.

      spec.parameters.name

      Yes

      The name of the associated AlbConfig.

  4. When you are finished, click Create. A message appears indicating that the resource is Created..

  5. Verify that the IngressClass is created:

    1. In the navigation pane on the left, choose Workloads > Custom Resources.

    2. Click the Resource Objects tab.

    3. In the API Group search box, search for IngressClass. The corresponding IngressClass appears.

CLI

  1. To create an IngressClass, create a file named alb.yaml and add the following content.

    Sample YAML

    apiVersion: networking.k8s.io/v1
    kind: IngressClass
    metadata:
      name: alb
    spec:
      controller: ingress.k8s.alibabacloud/alb
      parameters:
        apiGroup: alibabacloud.com
        kind: AlbConfig
        name: alb

    The following table describes the parameters.

    Parameter

    Required

    Description

    metadata.name

    Yes

    The name of the IngressClass.

    Note

    The IngressClass name must be unique within the cluster to prevent naming conflicts.

    spec.parameters.name

    Yes

    The name of the associated AlbConfig.

  2. Run the following command to create the IngressClass.

      kubectl apply -f alb.yaml

    Expected output:

    ingressclass.networking.k8s.io/alb created

Step 5: Create an Ingress

Console

  1. Log on to the ACK console.

  2. On the Clusters page, click the name of your cluster. In the left navigation pane, click Network > Ingresses.

  3. Click Create Resources in YAML.

    1. Sample Template: Select Custom.

    2. Template: Enter the following YAML configuration.

      Sample YAML

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: cafe-ingress 
      spec:
        ingressClassName: alb
        rules:
         - host: demo.domain.ingress.top
           http:
            paths:
            # Configure the context path
            - path: /tea
              pathType: ImplementationSpecific
              backend:
                service:
                  name: tea-svc
                  port:
                    number: 80
            # Configure the context path
            - path: /coffee
              pathType: ImplementationSpecific
              backend:
                service:
                  name: coffee-svc
                  port: 
                    number: 80

      The following table describes the parameters.

      Parameter

      Required

      Description

      metadata.name

      Yes

      The name of the Ingress.

      Note

      The Ingress name must be unique within the cluster.

      spec.ingressClassName

      Yes

      The name of the associated IngressClass.

      spec.rules.host

      No

      The domain name that the Ingress rule applies to. This value is matched against the Host header of an HTTP request. Set this to your custom domain name.

      When you access your custom domain name, for example, http://demo.domain.ingress.top, in a browser, the browser automatically adds a Host: demo.domain.ingress.top header to the HTTP request. This allows the server to identify the destination hostname. In Kubernetes, the host field in an Ingress rule is matched against the Host header from the request. If there is a match, the Ingress rule routes the request to the corresponding backend Service.

      Note
      • If you use a custom domain name, it must have an ICP filing to be accessible from the Chinese mainland. For more information, see ICP filing process.

      • If this parameter is not configured, the Ingress rule matches all requests that arrive at the Ingress controller.

      spec.rules.http.paths.path

      Yes

      The URL path for request forwarding.

      spec.rules.http.paths.pathType

      Yes

      The URL matching rule. For more information, see Path-based request forwarding.

      spec.rules.http.paths.backend.service.name

      Yes

      The name of the backend Service.

      spec.rules.http.paths.backend.service.port.number

      Yes

      The port number of the backend Service.

  4. After entering the configuration, click Create. A Created. message appears.

  5. Verify that the Ingress is created:

    1. In the navigation pane on the left, choose Network > Ingresses. The cafe-ingress Ingress appears in the list.

    2. The endpoint for cafe-ingress is displayed in the Endpoint column.

kubectl

  1. Create a file named cafe-ingress.yaml with the following content:

    Sample YAML

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress 
    spec:
      ingressClassName: alb
      rules:
       - host: demo.domain.ingress.top
         http:
          paths:
          # Configure the context path
          - path: /tea
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          # Configure the context path
          - path: /coffee
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port: 
                  number: 80

    The following table describes the parameters.

    Parameter

    Required

    Description

    metadata.name

    Yes

    The name of the Ingress.

    Note

    The Ingress name must be unique within the cluster.

    spec.ingressClassName

    Yes

    The name of the associated IngressClass.

    spec.rules.host

    No

    The domain name that the Ingress rule applies to. This value is matched against the Host header of an HTTP request. Set this to your custom domain name.

    When you access your custom domain name, for example, http://demo.domain.ingress.top, in a browser, the browser automatically adds a Host: demo.domain.ingress.top header to the HTTP request. This allows the server to identify the destination hostname. In Kubernetes, the host field in an Ingress rule is matched against the Host header from the request. If there is a match, the Ingress rule routes the request to the corresponding backend Service.

    Note
    • If you use a custom domain name, it must have an ICP filing to be accessible from the Chinese mainland. For more information, see ICP filing process.

    • If this parameter is not configured, the Ingress rule matches all requests that arrive at the Ingress controller.

    spec.rules.http.paths.path

    Yes

    The URL path for request forwarding.

    spec.rules.http.paths.pathType

    Yes

    The URL matching rule. For more information, see Path-based request forwarding.

    spec.rules.http.paths.backend.service.name

    Yes

    The name of the backend Service.

    spec.rules.http.paths.backend.service.port.number

    Yes

    The port number of the backend Service.

  2. Run the following command to configure the exposed domain name and path for the coffee and tea services.

    kubectl apply -f cafe-ingress.yaml

    Expected output:

    ingress.networking.k8s.io/cafe-ingress created
  3. (Optional) Run the following command to view the created Ingress and find the DNS name of the associated ALB instance in the ADDRESS column.

    kubectl get ingress

    Expected output:

    NAME           CLASS    HOSTS                         ADDRESS                                               PORTS   AGE
    cafe-ingress   alb      demo.domain.ingress.top       alb-m551oo2zn63yov****.cn-hangzhou.alb.aliyuncs.com   80      50s

Step 6: Configure DNS resolution

If you set the spec.rules.host field to your custom domain name when you create the Ingress, you must create a CNAME record to point your custom domain name to the ALB DNS name. This allows you to access the service through your custom domain name.

  1. Log on to the ACK console.

  2. Click the cluster name to go to the cluster details page.

  3. In the navigation pane on the left, choose Network > Ingresses.

  4. In the Endpoint column for cafe-ingress, copy the corresponding DNS name.

  5. Follow these steps to add a CNAME record.

    Note

    If your domain name is registered by a provider other than Alibaba Cloud, you must add the domain name to the Alibaba Cloud DNS console before you can configure DNS resolution. For more information, see Manage domain names. If your domain name is registered with Alibaba Cloud, proceed with the following steps.

    1. Log on to the Alibaba Cloud DNS console.

    2. On the Public Zone page, find the target domain name, and click Settings in the Operations column.

    3. On the Settings page, click Add Record.

    4. In the Add Record panel, configure the CNAME record by setting the following parameters, and then click OK.

      Parameter

      Description

      Record Type

      Select CNAME from the drop-down list.

      Hostname

      The prefix of your domain name. This tutorial uses @.

      Note

      To use a root domain, set the hostname to @.

      Query Source

      Select Default.

      Record Value

      Enter the DNS name of the ALB instance that you copied.

      TTL

      Time to live (TTL) is the duration that a DNS record is cached on a DNS server. Use the default value.

Step 7: Test traffic forwarding

In your browser, enter the test domain followed by the URL path to verify traffic forwarding.

This example uses demo.domain.ingress.top as the test domain:

  1. Enter demo.domain.ingress.top/coffee in your browser. The page for the coffee-svc backend service appears.

    Server address:  172.xxx.xxx.xx1:80
    Server name:     coffee-5c7xxxdxxxdf-xxxpm
    Date:            2xxx xxx/2024.09.28.13 +0000
    URI:             /coffee
    Request ID: e8c7d4xxx xxx xxx xxx xxx62a7
    © NGINX, Inc. 2018
  2. Enter demo.domain.ingress.top/tea in your browser. The page for the tea-svc backend service appears.

    Server address: 1xxx.xxx.xxx.100:80
    Server name: tea-6xxx
    Date: 26xxx 9:08 +0000
    URI: /tea
    Request ID: a044xxx2d0
    © NGINX, Inc. 2018

References