Application Load Balancer (ALB) Ingresses are compatible with NGINX Ingresses and provide improved traffic routing capabilities based on ALB instances. ALB Ingresses support complex routing, automatic certificate discovery, and the HTTP, HTTPS, and QUIC protocols. ALB Ingresses meet the requirements of cloud-native applications for ultra-high elasticity and balancing of heavy traffic loads at Layer 7. You can configure an ALB Ingress in a Container Service for Kubernetes (ACK) cluster to manage traffic. This topic describes how to deploy Services and access the Services by using an ALB Ingress.
Background information
Terms related to ALB Ingresses:
ALB Ingress controller: a Kubernetes component that manages Ingresses. The ALB Ingress controller serves as an entry point in a cluster and routes external traffic to specific Services. The ALB Ingress controller retrieves the changes to Ingresses from the API server and dynamically generates AlbConfigs when the changes are detected. Then, the ALB Ingress controller performs the following operations in sequence: create ALB instances, configure listeners, create Ingress rules, and configure backend server groups.
AlbConfig CRD: Custom resource definitions (CRDs) extend the Kubernetes API and allow you to create custom resources. An AlbConfig corresponds to one ALB instance.
IngressClass: An IngressClass is an attribute of a Kubernetes Ingress that defines the class or identifier of an Ingress controller. IngressClasses allow you to use multiple Ingress controllers in a cluster and specify a controller for each Ingress.
Ingress: An Ingress is a resource object in Kubernetes that defines the forwarding rules and access rules of external traffic. The Ingress controller forwards traffic based on Ingresses. You can configure forwarding rules in ALB Ingresses by using annotations. After the configuration is complete, HTTP/HTTPS requests can be forwarded to the corresponding Services based on the forwarding rules.
Service: In Kubernetes, a Service is an abstract resource object that defines a set of pods that have the same logical function and allows you to access the pods by using a fixed virtual IP address and port.
A Service provides access to an application and allows other applications or services to communicate with backend pods by accessing the virtual IP address and port of the Service. This eliminates the need to obtain the IP address and port of a specific pod. A Service is an abstraction of a backend application that runs on a set of replicated pods.
The following figure shows the relationship between an ALB instance and an ALB Ingress.
Limits
If you use the Flannel network plug-in, the backend Services of the ALB Ingress must be of the NodePort or LoadBalancer type.
The names of AlbConfigs, namespaces, Ingresses, and Services cannot start with aliyun.
Earlier NGINX Ingress controller versions cannot recognize the
spec: ingressClassName
field of an Ingress. If NGINX Ingresses and ALB Ingresses are configured in your ACK cluster, the ALB Ingresses may be reconciled by an earlier version of the NGINX Ingress controller. To avoid this problem, update your NGINX Ingress controller at the earliest opportunity or use annotations to specify the IngressClasses of ALB Ingresses. For more information, see Update the NGINX Ingress controller or Advanced ALB Ingress configurations.
Scenarios
In the following example, two NGINX Services are deployed on four pods. This topic uses the example to describe how to configure an ALB Ingress to forward requests destined for the same domain name but different URL paths.
Frontend request | Forwarded to |
|
|
|
|
Prerequisites
An ACK managed cluster or ACK dedicated cluster is created and the cluster runs Kubernetes 1.18 or later. For more information, see Create an ACK managed cluster and Create an ACK dedicated cluster.
Optional. kubectl is used to connect to the cluster.
A domain name is registered, and an Internet content provider (ICP) number is obtained for the domain name. For more information, see Register a generic domain name and ICP filing process.
Step 1: Install the ALB Ingress controller
To use the ALB Ingress, install the ALB Ingress controller first.
Install the ALB Ingress controller when you create a cluster
When you create an ACK managed cluster or ACK dedicated cluster, select ALB Ingress in the Ingress section.
You can set Gateway Source to New, Existing, or None. The following table describes the three options.
If you select New or Existing, an AlbConfig and IngressClass are automatically created after the ALB Ingress controller is installed. A listener
that uses HTTP and listens on port 80 is configured in the AlbConfig.
Comparison item | New | Existing | None |
Use scenarios | This is the first time you use ALB Ingresses in the cluster. No AlbConfig exists in the cluster. | You want to use existing ALB instances. | You want to configure an AlbConfig after the ALB Ingress controller is installed. |
How it works | After an AlbConfig is created, an ALB instance is automatically created based on the AlbConfig. | An AlbConfig is automatically created. The | Only the ALB Ingress controller is installed. No AlbConfig is created. |
What to do next | Set Network Type to the type of network used by the ALB instance and set vSwitch to the vSwitch of the ALB instance. Important To ensure high availability, we recommend that you select at least two vSwitches that reside in different zones. | Set ALB Cloud-native Gateway to the ALB instance that you want to use. To use an AlbConfig to specify an ALB instance, see Reuse an existing ALB instance. Important Basic ALB instances are not supported. | Select an existing AlbConfig or create an AlbConfig later. |
Install the ALB Ingress controller in an existing cluster
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose .
On the Add-ons page, click the Networking tab. In the Networking section, find the ALB Ingress Controller card and click Install in the lower-right corner.
In the Install ALB Ingress Controller dialog box, set Gateway Source to New, Existing, or None. The following table describes the three options.
ImportantIf you select New or Existing, an AlbConfig and IngressClass are automatically created after the ALB Ingress controller is installed. A
listener
that uses HTTP and listens on port 80 is configured in the AlbConfig.Comparison item
New
Existing
None
Use scenarios
This is the first time you use ALB Ingresses in the cluster. No AlbConfig exists in the cluster.
You want to use existing ALB instances.
You want to configure an AlbConfig after the ALB Ingress controller is installed.
How it works
After an AlbConfig is created, an ALB instance is automatically created based on the AlbConfig.
An AlbConfig is automatically created. The
id
field is set to the ID of the specified ALB instance.Only the ALB Ingress controller is installed. No AlbConfig is created.
What to do next
Set Network Type to the type of network used by the ALB instance and set vSwitch to the vSwitch of the ALB instance.
ImportantTo ensure high availability, we recommend that you select at least two vSwitches that reside in different zones.
Set ALB Cloud-native Gateway to the ALB instance that you want to use. To use an AlbConfig to specify an ALB instance, see Reuse an existing ALB instance.
ImportantBasic ALB instances are not supported.
Select an existing AlbConfig or create an AlbConfig later.
Click OK.
If you want to use an ALB Ingress to access Services deployed in an ACK dedicated cluster, you need to first authorize the cluster to access the ALB Ingress controller. For more information, see Authorize an ACK dedicated cluster to access the ALB Ingress controller.
Step 2: Deploy a backend Service
ACK console
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose .
Click Create from YAML in the upper-right corner.
Sample Template: Select Custom.
Template: Paste the following code to the code editor. This YAML file is used to deploy two Deployments named
coffee
andtea
, and two Services namedcoffee-svc
andtea-svc
.
After you complete the configurations, click Create. The Created message appears.
Perform the following operations to verify that the Deployments and Services are created:
In the left-side navigation pane, choose Workloads > Deployments. The Deployments named coffee and tea are displayed.
In the left-side navigation pane, choose Network > Services. The Services named coffee-svc and tea-svc are displayed.
kubectl
Create a file named cafe-service.yaml. Copy and paste the following content to the file. The file is used to deploy two Deployments named
coffee
andtea
and two Services namedcoffee-svc
andtea-svc
.Run the following command to deploy the Deployments and Services:
kubectl apply -f cafe-service.yaml
Expected output:
deployment "coffee" created service "coffee-svc" created deployment "tea" created service "tea-svc" created
Run the following command to view the status of the Deployments and Services:
Run the following command to view 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
Run the following command to query 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
If you set Gateway Source to New or Existing in Step 1: Install the ALB Ingress controller, the controller automatically creates an AlbConfig named alb and an IngressClass named alb. In this case, skip this step.
ACK console
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose .
Click Create from YAML in the upper-right corner.
Sample Template: Select Custom.
Template: Paste the following code to the code editor.
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the AlbConfig.
NoteThe name of the AlbConfig must be unique in the cluster. When you create an AlbConfig, make sure that the AlbConfig name is unique 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 provides services to the Internet and is accessible over the Internet.
NoteTo allow an ALB instance to provide Internet-facing services, the ALB instance need to be associated with an EIP . If you use an Internet-facing ALB instance, you are charged instance fees and bandwidth or data transfer fees for the EIPs. For more information, see Pay-as-you-go.
Intranet: internal-facing. An internal-facing ALB instance provides services within a VPC and cannot be accessed over the Internet.
spec.config.zoneMappings
Yes
The IDs of the vSwitches. For more information about how to create a vSwitch, see Create and manage a vSwitch.
NoteThe specified vSwitch must be deployed in a zone supported by the ALB instance and deployed in the same VPC as the cluster. For more information about the regions and zones supported by ALB, see Regions and zones supported by ALB.
ALB supports multi-zone deployment. If the current region supports two or more zones, select vSwitches in at least two zones to ensure high availability.
spec.listeners
No
The listening port and protocol of the ALB instance. In this example, an HTTP listener that uses port 80 is configured.
A listener defines how ALB receives traffic. We recommend that you retain the listener configuration. Otherwise, you must create a listener before you can use ALB Ingresses.
After the configuration is complete, click Create. The Created message appears.
Check whether the ALB instance is created:
Log on to the ALB console.
In the top navigation bar, select the region in which the ALB instance is deployed.
On the Instances page, an ALB instance named alb-test is displayed in the instance list. This indicates that the ALB instance is created.
kubectl
Create a file named alb-test.yaml and copy the following content to the file. The file is used to create an AlbConfig.
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the AlbConfig.
NoteThe name of the AlbConfig must be unique in the cluster. When you create an AlbConfig, make sure that the AlbConfig name is unique 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 provides services to the Internet and is accessible over the Internet.
NoteTo allow an ALB instance to provide Internet-facing services, the ALB instance need to be associated with an EIP . If you use an Internet-facing ALB instance, you are charged instance fees and bandwidth or data transfer fees for the EIPs. For more information, see Pay-as-you-go.
Intranet: internal-facing. An internal-facing ALB instance provides services within a VPC and cannot be accessed over the Internet.
spec.config.zoneMappings
Yes
The IDs of the vSwitches. For more information about how to create a vSwitch, see Create and manage a vSwitch.
NoteThe specified vSwitch must be deployed in a zone supported by the ALB instance and deployed in the same VPC as the cluster. For more information about the regions and zones supported by ALB, see Regions and zones supported by ALB.
ALB supports multi-zone deployment. If the current region supports two or more zones, select vSwitches in at least two zones to ensure high availability.
spec.listeners
No
The listening port and protocol of the ALB instance. In this example, an HTTP listener that uses port 80 is configured.
A listener defines how ALB receives traffic. We recommend that you retain the listener configuration. Otherwise, you must create a listener before you can use ALB Ingresses.
Run the following command to create an AlbConfig object:
kubectl apply -f alb-test.yaml
Expected output:
albconfig.alibabacloud.com/alb-demo created
Step 4: Create an IngressClass
We recommend that you create an IngressClass for each AlbConfig.
If you set Gateway Source to New or Existing in Step 1: Install the ALB Ingress controller, the controller automatically creates an AlbConfig named alb and an IngressClass named alb. In this case, skip this step.
ACK console
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose .
Click Create from YAML in the upper-right corner.
Sample Template: Select Custom.
Template: Paste the following code to the code editor.
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the IngressClass.
NoteThe name of an IngressClass must be unique in the cluster. Therefore, when you create an IngressClass, make sure that the IngressClass name is unique to prevent conflicts.
spec.parameters.name
Yes
The name of the associated AlbConfig.
After the configuration is complete, click Create. The Created message appears.
Perform the following operations to check whether the IngressClass is created:
In the left-side navigation pane, choose Workloads> Custom Resources.
Click the Resource Objects tab.
In the API Group search box, enter IngressClass. The IngressClass is displayed.
kubectl
Create a file named alb.yaml and copy the following content to the file:
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the IngressClass.
NoteThe name of an IngressClass must be unique in the cluster. Therefore, when you create an IngressClass, make sure that the IngressClass name is unique to prevent conflicts.
spec.parameters.name
Yes
The name of the associated AlbConfig.
Run the following command to create an IngressClass resource:
kubectl apply -f alb.yaml
Expected output:
ingressclass.networking.k8s.io/alb created
Step 5: Create an Ingress
ACK console
Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose .
Click Create from YAML in the upper-right corner.
Sample Template: Select Custom.
Template: Paste the following code to the code editor.
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the Ingress.
NoteThe name of an Ingress must be unique in the cluster. Therefore, when you create an Ingress, make sure that the Ingress name is unique to prevent conflicts.
spec.ingressClassName
Yes
The name of the associated IngressClass.
spec.rules.host
No
The domain name of the HTTP host header. You must set this parameter to a custom domain name.
When you access the domain name, such as http://demo.domain.ingress.top, in a browser, the browser automatically adds the Host: demo.domain.ingress.top header when sending an HTTP request. This way, the server identifies the destination host based on the header. In Kubernetes, the host field in an Ingress rule is used to match the host header in a request. If the host header is matched, the request is sent to the corresponding backend Service.
NoteIf you specify a custom domain name, make sure that the domain name has an ICP number. Otherwise, the domain name may fail to be resolved. For more information, see ICP filing overview.
If this parameter is not configured, the Ingress rule matches all requests that are sent to the Ingress controller.
spec.rules.http.paths.path
Yes
The URL.
spec.rules.http.paths.pathType
Yes
The URL matching rule. For more information, see Forward requests based on URL paths.
spec.rules.http.paths.backend.service.name
Yes
The name of the Service that you created.
spec.rules.http.paths.backend.service.port.number
Yes
The port number of the Service that you created.
Make sure that the port is valid because the port is used to route requests to the backend Service. Make sure that the port is valid to ensure that requests can be routed to the backend Service and processed as expected.
After the configuration is complete, click Create. The Created message appears.
Check that the Ingress is created:
In the left-side navigation pane, choose Network > Ingresses. The Ingress named cafe-ingress is displayed.
In the Endpoint column of cafe-ingress, you can view the endpoint.
kubectl
Create a file named cafe-ingress.yaml and paste the following content to the file. The file is used to create an Ingress.
The following table describes the parameters that you can configure.
Parameter
Required
Description
metadata.name
Yes
The name of the Ingress.
NoteThe name of an Ingress must be unique in the cluster. Therefore, when you create an Ingress, make sure that the Ingress name is unique to prevent conflicts.
spec.ingressClassName
Yes
The name of the associated IngressClass.
spec.rules.host
No
The domain name of the HTTP host header. You must set this parameter to a custom domain name.
When you access the domain name, such as http://demo.domain.ingress.top, in a browser, the browser automatically adds the Host: demo.domain.ingress.top header when sending an HTTP request. This way, the server identifies the destination host based on the header. In Kubernetes, the host field in an Ingress rule is used to match the host header in a request. If the host header is matched, the request is sent to the corresponding backend Service.
NoteIf you specify a custom domain name, make sure that the domain name has an ICP number. Otherwise, the domain name may fail to be resolved. For more information, see ICP filing overview.
If this parameter is not configured, the Ingress rule matches all requests that are sent to the Ingress controller.
spec.rules.http.paths.path
Yes
The URL.
spec.rules.http.paths.pathType
Yes
The URL matching rule. For more information, see Forward requests based on URL paths.
spec.rules.http.paths.backend.service.name
Yes
The name of the Service that you created.
spec.rules.http.paths.backend.service.port.number
Yes
The port number of the Service that you created.
Make sure that the port is valid because the port is used to route requests to the backend Service. Make sure that the port is valid to ensure that requests can be routed to the backend Service and processed as expected.
Run the following command to configure an externally-accessible domain name and a
path
for thecoffee
andtea
Services separately:kubectl apply -f cafe-ingress.yaml
Expected output:
ingress.networking.k8s.io/cafe-ingress created
(Optional) Run the following command to query the domain name of the ALB instance:
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: Create a DNS record
If you set the spec.rules.host
parameter to a custom domain name when you create the Ingress, you must add a CNAME record to map the domain name to the domain name of the ALB instance. Then, you can access the Services through your custom domain name.
Log on to the ACK console.
Click the cluster name to go to the cluster details page.
In the left-side navigation pane, choose Network > Ingresses.
In the Endpoint column of cafe-ingress, copy the domain name.
To create a CNAME record, perform the following steps:
NoteIf your domain name is not registered by using Alibaba Cloud Domains, you must add your domain name to Alibaba Cloud DNS before you can configure a DNS record. For more information, see Manage domain names. If your domain name is registered on Alibaba Cloud, proceed with the following steps.
Log on to the Alibaba Cloud DNS console.
On the Authoritative DNS Resolution page, find your domain name and click DNS Settings in the Actions column.
On the DNS Settings tab of the domain name details page, click Add DNS Record.
In the Add DNS Record panel, configure the parameters and click OK. The following table describes the parameters.
Parameter
Description
Record Type
Select CNAME from the drop-down list.
Hostname
Enter the prefix of the domain name. In this example, @ is entered.
NoteIf you use a root domain name, enter
@
.DNS Request Source
Select Default.
Record Value
Enter the CNAME, which is the domain name of the ALB instance.
TTL
Select a time-to-live (TTL) value for the CNAME record to be cached on the DNS server. In this example, the default value is used.
Step 7: Test traffic forwarding
Enter "test domain name + URL path" in the address bar of a browser to test whether traffic can be forwarded to the specified Service.
In this example, demo.domain.ingress.top
is used in the tests.
Enter
demo.domain.ingress.top/coffee
in the address bar of a browser. The page for the coffee-svc Service appears.Enter
demo.domain.ingress.top/tea
in the address bar of a browser. The page for the tea-svc Service appears.
References
For more information about advanced ALB Ingress configurations, such as forwarding requests destined for different domain names or URLs to different backend server groups, health checks, redirecting requests from HTTP to HTTPS, canary releases, and custom listener ports, see Advanced ALB Ingress configurations.
For more information about how to configure custom ALB Ingress routing rules, routing conditions, and actions, see Customize the routing rules of an ALB Ingress.
For more information about how to use an HTTPS listener to forward HTTPS requests, see Use an ALB Ingress to configure certificates for an HTTPS listener.
For more information about how to troubleshoot ALB Ingress issues, see ALB Ingress troubleshooting and ALB Ingress FAQ.