Use ALB Ingress in Container Service ACK
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.

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:ingressClassNamefield 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 |
|
|
|
|
Prerequisites
You have an ACK managed cluster or an ACK dedicated cluster with Kubernetes version 1.18 or later. For more information, see Create an ACK managed cluster and Create an ACK dedicated cluster (discontinued).
(Optional) Connect to the cluster using kubectl.
You have registered a domain name and completed its ICP filing. For more information, see Register an Alibaba Cloud domain name and ICP filing process.
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: | An AlbConfig named |
(Recommended) Existing | Select an existing ALB instance. Basic ALB instances are not supported. See Reuse an existing ALB instance. | An AlbConfig named |
(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
Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of your cluster. In the left navigation pane, click Add-ons.
On the Add-ons page, click the Networking tab. In the Networking section, click Install on the ALB Ingress Controller card.
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
alband 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.
ImportantThe Controller does not create the corresponding resources. Manually create an AlbConfig and an IngressClass.
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
Log on to the ACK console.
-
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
Click Create Resources in YAML.
Sample Template: Select Custom.
Template: Enter the following YAML configuration. This configuration creates two Deployments named
coffeeandtea, and two Services namedcoffee-svcandtea-svc.
Click Create. The message Created. is displayed.
Verify that the Deployments and Services were created:
In the left-side navigation pane, choose Workloads > Deployments. The coffee and tea Deployments are displayed.
In the left-side navigation pane, choose Network > Services. The coffee-svc and tea-svc Services are displayed.
CLI
Create a YAML file named cafe-service.yaml and copy the following content into the file. This file deploys two Deployments named
coffeeandtea, and two Services namedcoffee-svcandtea-svc.Run the following command to deploy the two Deployments and two Services:
kubectl apply -f cafe-service.yamlExpected output:
deployment "coffee" created service "coffee-svc" created deployment "tea" created service "tea-svc" createdRun the following commands to check the status of the Deployments and Services.
Check the status of the Deployments:
kubectl get deploymentExpected output:
NAME READY UP-TO-DATE AVAILABLE AGE coffee 1/2 2 1 2m26s tea 1/1 1 1 2m26sCheck the status of the Services:
kubectl get svcExpected 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
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
Log on to the ACK console.
-
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
On the Custom Resources page, click the CRDs tab, and then click Create Resources in YAML.
Sample Template: Select Custom.
Template: Paste the following YAML manifest into the editor.
The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the AlbConfig resource.
NoteThe 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.
NoteApplication 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.
NoteThe 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.
After you complete the configuration, click Create. A Created. message appears.
Verify that the ALB instance is created successfully:
Log on to the Application Load Balancer (ALB) console.
In the top navigation bar, select the region where the instance is deployed.
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
Create a file named alb-test.yaml and paste the following content into it.
The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the AlbConfig resource.
NoteThe 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.
NoteApplication 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.
NoteThe 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.
Run the following command to create the AlbConfig resource:
kubectl apply -f alb-test.yamlExpected output:
albconfig.alibabacloud.com/alb created
Step 4: Create IngressClass
We recommend creating an IngressClass for each AlbConfig.
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
Log on to the ACK console.
-
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
On the Custom Resources page, click the CRDs tab, and then click Create Resources in YAML.
Sample Template: Select Custom.
Template: In the editor, paste the following YAML.
The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the IngressClass.
NoteThe IngressClass name must be unique within the cluster to prevent naming conflicts.
spec.parameters.name
Yes
The name of the associated AlbConfig.
When you are finished, click Create. A message appears indicating that the resource is Created..
Verify that the IngressClass is created:
In the navigation pane on the left, choose Workloads > Custom Resources.
Click the Resource Objects tab.
In the API Group search box, search for IngressClass. The corresponding IngressClass appears.
CLI
To create an IngressClass, create a file named
alb.yamland add the following content.The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the IngressClass.
NoteThe IngressClass name must be unique within the cluster to prevent naming conflicts.
spec.parameters.name
Yes
The name of the associated AlbConfig.
Run the following command to create the IngressClass.
kubectl apply -f alb.yamlExpected output:
ingressclass.networking.k8s.io/alb created
Step 5: Create an Ingress
Console
Log on to the ACK console.
-
On the Clusters page, click the name of your cluster. In the left navigation pane, click .
Click Create Resources in YAML.
Sample Template: Select Custom.
Template: Enter the following YAML configuration.
The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the Ingress.
NoteThe 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 aHost: demo.domain.ingress.topheader to the HTTP request. This allows the server to identify the destination hostname. In Kubernetes, thehostfield in an Ingress rule is matched against theHostheader from the request. If there is a match, the Ingress rule routes the request to the corresponding backend Service.NoteIf 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.
After entering the configuration, click Create. A Created. message appears.
Verify that the Ingress is created:
In the navigation pane on the left, choose Network > Ingresses. The cafe-ingress Ingress appears in the list.
The endpoint for cafe-ingress is displayed in the Endpoint column.
kubectl
Create a file named cafe-ingress.yaml with the following content:
The following table describes the parameters.
Parameter
Required
Description
metadata.name
Yes
The name of the Ingress.
NoteThe 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 aHost: demo.domain.ingress.topheader to the HTTP request. This allows the server to identify the destination hostname. In Kubernetes, thehostfield in an Ingress rule is matched against theHostheader from the request. If there is a match, the Ingress rule routes the request to the corresponding backend Service.NoteIf 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.
Run the following command to configure the exposed domain name and
pathfor thecoffeeandteaservices.kubectl apply -f cafe-ingress.yamlExpected output:
ingress.networking.k8s.io/cafe-ingress created(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 ingressExpected 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.
Log on to the ACK console.
Click the cluster name to go to the cluster details page.
In the navigation pane on the left, choose Network > Ingresses.
In the Endpoint column for cafe-ingress, copy the corresponding DNS name.
Follow these steps to add a CNAME record.
NoteIf 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.
Log on to the Alibaba Cloud DNS console.
On the Public Zone page, find the target domain name, and click Settings in the Operations column.
On the Settings page, click Add Record.
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 @.
NoteTo 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:
Enter
demo.domain.ingress.top/coffeein your browser. The page for thecoffee-svcbackend 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. 2018Enter
demo.domain.ingress.top/teain your browser. The page for thetea-svcbackend 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
See Advanced ALB Ingress usage to learn how to forward requests from different domain names or URL paths to different backend server groups, configure health checks, redirect HTTP traffic to HTTPS, set up canary releases, and use custom listener ports.
See Customize ALB Ingress forwarding rules to learn how to set conditions and actions.
See Use an ALB Ingress to configure certificates for an HTTPS listener to learn how to forward HTTPS requests.
To troubleshoot ALB Ingress issues, see ALB Ingress troubleshooting and ALB Ingress FAQ.