ALB Ingress quick start - route traffic by URL path - Container Compute Service

How ALB Ingress works

Key concepts:

ALB Ingress Controller: This component manages Ingress resources. It dynamically retrieves changes to Ingress and AlbConfig resources from the cluster API Server and updates ALB instances accordingly. Unlike the NGINX Ingress Controller, the ALB Ingress Controller serves as the control plane for ALB instances. It manages ALB instances but does not process user traffic directly. Instead, ALB instances forward user traffic. The ALB Ingress Controller dynamically retrieves changes to Ingress resources from the cluster API Server and updates ALB instances based on the forwarding rules defined in Ingress.
An AlbConfig is a cluster-level Custom Resource Definition (CRD) created by the ALB Ingress Controller. Each AlbConfig contains parameters that define the configuration for a single ALB instance. An ALB instance serves as the entry point for traffic and forwards requests to backend services. It is fully managed by Application Load Balancer (ALB). Unlike the Nginx Ingress Controller, ALB Ingress requires no operations and maintenance (O&M) and provides greater elasticity.
IngressClass: An IngressClass defines the association between an Ingress and an AlbConfig.
Ingress: In Kubernetes, Ingress is a resource object that defines external traffic routing and access rules. The ALB Ingress Controller monitors changes in Ingress resources and updates ALB instances to achieve traffic forwarding.
Service: A stable entry point for a group of Pods with the same function. Other applications access backend Pods through the Service's virtual IP and port, decoupled from individual Pod changes.

The following figure shows the relationship between an ALB instance and ALB Ingress.

Limitations

AlbConfig, namespace, ingress, and service resource names must not start with aliyun.

Example scenario

This tutorial deploys four Nginx Pods and configures ALB Ingress to route traffic by URL path under the same domain.

Frontend request	Backend service
`demo.domain.ingress.top/coffee`	`coffee` service
`demo.domain.ingress.top/tea`	`tea` service

Prerequisites

You have installed the ALB Ingress Controller.
You have created two VSwitches in different availability zones within your cluster's VPC. Create and manage VSwitches.

Step 1: Deploy the backend service

Using console

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Workloads > Deployments.
On the Deployments page, click Create from YAML in the upper-right corner.

On the Create page, configure the parameters.

Sample Template: Select Custom.

Template: Enter the YAML configuration to deploy two Deployments ( coffee and tea) and two Services (coffee-svc and tea-svc).

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

Click Create. A Created. message appears.
Verify the Deployments and Services are created.
1. In the left-side navigation pane, choose Workloads > Stateless. The Deployments named coffee and tea appear.
2. In the left-side navigation pane, choose Network > Services. The Services named coffee-svc and tea-svc appear.

Using kubectl

Create a file named cafe-service.yaml with the following content. This deploys two Deployments (coffee and tea) and two Services (coffee-svc and tea-svc).

YAML configuration file reference

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

Run the following command to deploy the resources.

kubectl apply -f cafe-service.yaml

Expected output:

deployment "coffee" created
service "coffee-svc" created
deployment "tea" created
service "tea-svc" created

Verify the Deployments and Services.

Check the Deployments.

kubectl get deployment

Expected output:

NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
coffee                           2/2     2            2           2m26s
tea                              2/2     2            2           2m26s

Check the Services.

kubectl get svc

Expected output:

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

Step 2: Create an ALBConfig

Console

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Workloads > Custom Resources.

On the CRDs tab, click Create from YAML.

Sample Template: Select Custom.

Template: Paste the YAML manifest.

Sample YAML configuration

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    name: alb-test
    addressType: Internet
    zoneMappings:                          # To ensure high availability, select vSwitches in at least two different availability zones.
    - vSwitchId: vsw-uf6ccg2a9g71hx8go**** # Replace with the actual vSwitch ID (in availability zone 1).
    - vSwitchId: vsw-uf6nun9tql5t8nh15**** # Replace with the actual vSwitch ID (in availability zone 2, which must be different from the preceding one).
  listeners:
    - port: 80
      protocol: HTTP

The following table describes the parameters.

Parameter	Required	Description
`metadata.name`	Yes	The name of the ALBConfig. Note The ALBConfig name must be unique within the cluster to avoid naming 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): The instance provides public load balancing services over the internet. Note Internet-facing ALB instances use an Elastic IP Address (EIP). You are charged for the EIP instance, bandwidth, and data transfer. Pay-as-you-go. Intranet: The instance provides private load balancing services within a VPC.
`spec.config.zoneMappings`	Yes	The IDs of the vSwitches for the ALB instance. For instructions on how to create a vSwitch, see Create and manage vSwitches. Note The vSwitches must be in an ALB-supported availability zone and the same VPC as the cluster. Regions and availability zones supported by ALB. If your region offers multiple availability zones, we recommend selecting vSwitches from at least two different zones for high availability.
`spec.listeners`	No	The listener port and protocol. This example uses HTTP on port 80. ALB Ingress requires a listener. Keep this default to avoid manual configuration.

Click Create. A Created. message is displayed.
Verify the ALB instance:
1. Log on to the Application Load Balancer (ALB) console.
2. In the top navigation bar, select the region of the instance.
3. On the Instance page, verify that the ALB instance named alb-test appears in the instance list.

Kubectl

Copy the following content to a file named alb-test.yaml to create an ALBConfig.

Sample YAML configuration

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    name: alb-test
    addressType: Internet
    zoneMappings:                          # To ensure high availability, select vSwitches in at least two different availability zones.
    - vSwitchId: vsw-uf6ccg2a9g71hx8go**** # Replace with the actual vSwitch ID (in availability zone 1).
    - vSwitchId: vsw-uf6nun9tql5t8nh15**** # Replace with the actual vSwitch ID (in availability zone 2, which must be different from the preceding one).
  listeners:
    - port: 80
      protocol: HTTP

The following table describes the parameters.

Parameter	Required	Description
`metadata.name`	Yes	The name of the ALBConfig. Note The ALBConfig name must be unique within the cluster to avoid naming 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): The instance provides public load balancing services over the internet. Note Internet-facing ALB instances use an Elastic IP Address (EIP). You are charged for the EIP instance, bandwidth, and data transfer. Pay-as-you-go. Intranet: The instance provides private load balancing services within a VPC.
`spec.config.zoneMappings`	Yes	The IDs of the vSwitches for the ALB instance. For instructions on how to create a vSwitch, see Create and manage vSwitches. Note The vSwitches must be in an ALB-supported availability zone and the same VPC as the cluster. Regions and availability zones supported by ALB. If your region offers multiple availability zones, we recommend selecting vSwitches from at least two different zones for high availability.
`spec.listeners`	No	The listener port and protocol. This example uses HTTP on port 80. ALB Ingress requires a listener. Keep this default to avoid manual configuration.

Run the following command to create the ALBConfig.
```
kubectl apply -f alb-test.yaml
```
Expected output:
```
albconfig.alibabacloud.com/alb-demo created
```
This output confirms that the ALBConfig was created.

Step 3: Create IngressClass

We recommend creating one IngressClass for each AlbConfig.

Console

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Workloads > Custom Resources.

On the CRDs tab, click Create from YAML.

Sample Template: Select Custom.

Template: Enter the YAML manifest.

Sample YAML configuration

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

The following table describes the parameters.

Parameter	Required	Description
metadata.name	Yes	The name of the IngressClass. Note The name must be unique within the cluster.
spec.parameters.name	Yes	The name of the associated AlbConfig.

Click Create. A confirmation message appears.
Verify that the IngressClass is created:
1. In the left-side navigation pane, choose Workloads > Custom Resources.
2. Click the Resource Objects tab.
3. In the API Group search box, enter IngressClass. The created IngressClass appears.

Kubectl

Create a file named alb.yaml with the following content.

Sample YAML configuration

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

The following table describes the parameters.

Parameter	Required	Description
`metadata.name`	Yes	The name of the IngressClass. Note The name must be unique within the cluster.
`spec.parameters.name`	Yes	The name of the associated AlbConfig.

Run the following command to create the IngressClass.
```
kubectl apply -f alb.yaml
```
Expected output:
```
ingressclass.networking.k8s.io/alb created
```

Step 4: Create an Ingress

Console

Log on to the ACS console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the Ingress.

Parameter	Description	Example value
Gateway Type	Select the gateway type. Options include ALB and MSE.	ALB Ingress
Name	A custom name for the Ingress.	cafe-ingress
IngressClass	A custom class for the Ingress.	alb
Rules	Click +Add Rule to add multiple routing rules. Domain Name: A custom domain name. Mappings: Configure the following parameters. Path: The URL path for accessing the service. In this example, this parameter is left empty to use the root path /. Rule: Supports Prefix (Prefix-based Match), Exact (Exact Match), and ImplementationSpecific (Default Value). Service: The target backend, which is a Kubernetes Service. Port: The port that the service exposes. An Ingress supports multiple paths under the same domain name. Click +Add to add a new path.	Domain Name: demo.domain.ingress.top Path mapping: Path: /tea Rule: ImplementationSpecific Service: tea-svc Port: 80 Mappings: Path: /coffee Rule: ImplementationSpecific Service: coffee-svc Port: 80
TLS Settings	Enable this option to secure the Ingress with a TLS certificate (HTTPS). Domain Name: Enter a custom domain name. Secret: Select the Secret that contains the TLS certificate. To create a Secret, perform the following steps: To the right of Secret, click Create. In the Create Secret dialog box, set the Name, Cert, and Key, and then click OK. From the Secret drop-down list, select the Secret that you created. Click Add to configure multiple TLS settings. For more information, see Configure an HTTPS certificate for encrypted communication.	Keep TLS Settings disabled. This configuration is not required for this example.
More	Canary Release: Enable canary release. You can set canary rules based on request headers, cookies, and weights. Note You can set only one type of rule (by request header, cookie, or weight). If you configure multiple types, they are matched in the order of request header, cookie, and weight. Based on Request Header: Splits traffic based on the request header. This adds the `alb.ingress.kubernetes.io/canary-by-header` and `alb.ingress.kubernetes.io/canary-by-header-value` annotations. Based on Cookie: Splits traffic based on a cookie. This adds the `alb.ingress.kubernetes.io/canary-by-cookie` annotation. Based on Weight: Specifies the percentage of requests (an integer from 0 to 100) to route to a specific Service. This adds the `alb.ingress.kubernetes.io/canary-weight` annotation. Protocol: Enables the HTTPS and gRPC protocols for backend services, adding the `alb.ingress.kubernetes.io/backend-protocol` annotation. Rewrite Path: The path in a client request is rewritten before the request is sent to the backend service. Configuring this setting adds the alb.ingress.kubernetes.io/rewrite-target annotation.	Keep canary release disabled, and keep the default protocol and rewrite path settings. These configurations are not required for this example.
Custom Forwarding Rules	Enable custom forwarding rules to manage inbound traffic with fine-grained control. Note You can add a maximum of 10 condition entries to a forwarding rule. From the Add Condition drop-down list, select an option: Domain Name: Matches the request domain. If you specify multiple domains, a request is matched if it uses any of the specified domains. When you configure this condition, the `alb.ingress.kubernetes.io/conditions.host-example` annotation is added. Path: Matches the request path. If you specify multiple paths, a request is matched if it uses any of the specified ones. When you configure this condition, the `alb.ingress.kubernetes.io/conditions.path-example` annotation is added. HTTP Header: Matches the request header as a key-value pair. For example, Key is `headername` and Value is `headervalue1`. If multiple header values are configured, the relationship between them is OR. When you configure this condition, the `alb.ingress.kubernetes.io/conditions.http-header-example` annotation is added. From the Action drop-down list, select an option: Forward To Forwards requests to one or more backend services based on weight. In the Service field, select the target service. In the Port field, select the target port number. Then, specify a weight. Note If you select this action, you do not need to configure path mapping in the rule. Return Fixed Response Configures ALB to return a fixed response to the client. You can set the response status code, body content, and content type. As required, configure Response Status Code, Response Content Type (Optional), and Response Content (Optional). Response Body Type: text/plain: plain text. text/css: CSS content. text/html: HTML content. application/javascript: JavaScript content. application/json: JSON content. Custom forwarding rules support conditions based on domain, path, or HTTP header, and actions such as forwarding to a service or returning a fixed response. Customize forwarding rules for an ALB Ingress.	Keep custom forwarding rules disabled. This configuration is not required for this example.
Annotations	You can specify a custom annotation name and value, or select or search for an annotation to configure. For more information about Ingress annotations, see Annotations.	Not required for this example.
Labels	Specifies labels to add to the Ingress. Labels are key-value pairs that are attached to objects to specify identifying attributes.	Not required for this example.

In the lower-left corner of the Create Ingress page, click OK.
Verify the Ingress:
1. In the left-side navigation pane, choose Network > Routes. The cafe-ingress ingress appears.
2. The Endpoint column for cafe-ingress displays the endpoint address.

kubectl

Create a file named cafe-ingress.yaml and add the following content:

YAML configuration file reference

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 name must be unique within the cluster to avoid conflicts.
`spec.ingressClassName`	Yes	The name of the associated IngressClass.
`spec.rules.host`	No	The domain name in the HTTP `Host` header. Set this to your own domain name. Kubernetes matches incoming Host headers against Ingress rules and routes matched requests to the specified backend service. Note Custom domain names require a valid ICP filing for Chinese mainland access. ICP filing process. If you do not set this parameter, the Ingress rule matches all requests that reach the Ingress controller.
`spec.rules.http.paths.path`	Yes	The forwarding path URL.
`spec.rules.http.paths.pathType`	Yes	The URL matching rule. Route requests based on URL paths.
`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. Ensure this port matches the Service definition.

Run the following command to create the Ingress with path-based routing for the coffee and tea services.
```
kubectl apply -f cafe-ingress.yaml
```
Expected output:
```
ingress.networking.k8s.io/cafe-ingress created
```

(Optional) Get the ALB DNS name assigned to the Ingress.

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

(Optional) Step 5: Configure domain name resolution

If you specified a custom domain in spec.rules.host, add a CNAME record pointing it to the ALB DNS name to enable access through your domain.

Log in to the Container Service for Kubernetes (ACK) console.
Click the cluster name to open the cluster management page.
In the navigation pane on the left, choose Network > Routes.
In the Endpoint column of cafe-ingress, copy its DNS name.

To add a CNAME record:

Log in to the Alibaba Cloud DNS console.
On the Domain Name Resolution page, click Add Zone.
In the Add Zone dialog box, enter your domain name and click OK.

Important
You must verify the domain name with a TXT record.
For the target domain, click Settings in the Actions column.
On the Settings page, click Add Record.

In the Add Record panel, configure the following settings for the CNAME record and click OK.

Parameter	Description
Record Type	From the drop-down list, select CNAME.
Hostname	The prefix of your domain name, such as `www`.
DNS Query Source	Select the default value.
Record Value	Enter the DNS name that you copied from the Endpoint column.
TTL	The duration a DNS record is cached on a DNS server. Use the default value.

Step 6: Test traffic forwarding

Enter the test domain and URL path in your browser to verify traffic routing.

Note

If you configured a custom domain, use that domain.
If you did not configure a custom domain, use the cafe-ingress endpoint DNS name.

In this example, the domain is demo.domain.ingress.top:

Enter demo.domain.ingress.top/coffee. The coffee-svc backend page is displayed.
Enter demo.domain.ingress.top/tea. The tea-svc backend page is displayed.

References

Advanced usage of the ALB Ingress service covers health checks, HTTPS redirect, canary releases, and custom listener ports.
Customize forwarding rules for ALB Ingress.
Configure an HTTPS certificate for encrypted communication.
Troubleshoot ALB Ingress issues and ALB Ingress FAQ.