Container Service for Kubernetes:Create an ALB Ingress

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.

Install the ALB Ingress controller in an existing cluster

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

2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side navigation pane, choose Operations > Add-ons.

3. 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.

4. In the Install ALB Ingress Controller dialog box, set Gateway Source to New, Existing, or None. The following table describes the three options.

   Important

   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 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. 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.

5. Click OK.

ACK console

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

2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Workloads > Deployments.

3. In the upper-right corner of the Deployments page, click Create from YAML.

   1. Sample Template: Select Custom from the drop-down list.

   2. 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.

      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

4. After the configurations are complete, click Create. The Created message appears.

5. Perform the following steps to verify that the Deployments and Services are created:

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

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

kubectl

1. 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.

   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

2. 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

3. View the status of the Deployments and Services.

   1. 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

   2. 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

ACK console

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

2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Workloads > Custom Resources.

3. In the upper-right corner of the Custom Resources page, click Create from YAML.

   1. Sample Template: Select Custom from the drop-down list.

   2. Template: Copy the following code to the code editor.

      YAML configuration file

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

      The following table describes the parameters that you can specify.

      Parameter	Required	Description
      metadata.name	Yes	The name of the AlbConfig. Note The name of an AlbConfig must be unique in the cluster. When you create an AlbConfig, make sure that the AlbConfig name is unique to prevent name 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: Internet-facing. This is the default value. The ALB instance provides services to the Internet and is accessible over the Internet. Note To allow an ALB instance to provide Internet-facing services, the ALB instance needs to be associated with an elastic IP address (EIP). If you use an Internet-facing ALB instance, you are charged instance fees and bandwidth or data transfer fees for the associated EIPs. For more information, see Pay-as-you-go. Intranet: internal-facing. The ALB instance provides services within a virtual private cloud (VPC) and cannot be accessed over the Internet.
      spec.config.zoneMappings	Yes	The IDs of the vSwitches that are associated with the ALB instance. For more information about how to create a vSwitch, see Create and manage a vSwitch. Note The specified vSwitches must be deployed in the zones 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 in which ALB is available. 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 listener 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.

4. After the configurations are complete, click Create. The Created message appears.

5. Perform the following steps to verify that the ALB instance is created.

   1. Log on to the ALB console.

   2. In the top navigation bar, select the region in which the ALB instance is deployed.

   3. On the Instances page, verify that the ALB instance named alb-test is displayed in the instance list.

kubectl

1. Create a file named alb-test.yaml and copy the following content to the file. The file is used to create an AlbConfig.

   YAML configuration file

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

   The following table describes the parameters that you can specify.

   Parameter	Required	Description
   metadata.name	Yes	The name of the AlbConfig. Note The name of an AlbConfig must be unique in the cluster. When you create an AlbConfig, make sure that the AlbConfig name is unique to prevent name 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: Internet-facing. This is the default value. The ALB instance provides services to the Internet and is accessible over the Internet. Note To 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. The ALB instance provides services within a VPC and cannot be accessed over the Internet.
   spec.config.zoneMappings	Yes	The IDs of the vSwitches that are associated with the ALB instance. For more information about how to create a vSwitch, see Create and manage a vSwitch. Note The specified vSwitches must be deployed in the zones 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 in which ALB is available. 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 listener 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.

2. Run the following command to create an AlbConfig:

   kubectl apply -f alb-test.yaml

   Expected output:

   albconfig.alibabacloud.com/alb-demo created

ACK console

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

2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Workloads > Custom Resources.

3. In the upper-right corner of the Custom Resources page, click Create from YAML.

   1. Sample Template: Select Custom from the drop-down list.

   2. Template: Copy the following code to the code editor.

      YAML configuration file

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

      The following table describes the parameters that you can specify.

      Parameter	Required	Description
      metadata.name	Yes	The name of the IngressClass. Note The name of an IngressClass must be unique in the cluster. When you create an IngressClass, make sure that the IngressClass name is unique to prevent name conflicts.
      spec.parameters.name	Yes	The name of the associated AlbConfig.

4. After the configurations are complete, click Create. The Created message appears.

5. Perform the following steps to verify the IngressClass is created:

   1. In the left-side pane, choose Workloads > Custom Resources.

   2. On the Custom Resources page, click the Resource Objects tab.

   3. In the API Group search box, enter IngressClass. The IngressClass that you created is displayed.

kubectl

1. Create a file named alb.yaml and copy the following content to the file.

   YAML configuration file

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

   The following table describes the parameters that you can specify.

   Parameter	Required	Description
   metadata.name	Yes	The name of the IngressClass. Note The name of an IngressClass must be unique in the cluster. When you create an IngressClass, make sure that the IngressClass name is unique to prevent name conflicts.
   spec.parameters.name	Yes	The name of the associated AlbConfig.

2. Run the following command to create an IngressClass:

     kubectl apply -f alb.yaml

   Expected output:

   ingressclass.networking.k8s.io/alb created

ACK console

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

2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Network > Ingresses.

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

   Parameter	Description	Example
   Gateway Type	You can select ALB, MSE Cloud-native Gateway, or Nginx based on your requirements. For more information about the differences among the three gateway types, see Comparison among NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	ALB
   Metric	Specify the name of the Ingress.	cafe-ingress
   Ingress Class	Specify the class of the Ingress.	alb
   Listener/Port	The listener port and protocol of the ALB instance that you specify in the AlbConfig. The listener and protocol define how the ALB instance receives and processes traffic.	HTTP:80
   Rules	Click +Add Rule to add an Ingress rule. Domain Name: Enter a custom domain name. Mappings: Specify the following parameters: Path: Enter the URL path of the backend Service. In this example, the root path / is used. Rule: You can select Prefix (Prefix-based Match), Exact (Exact Match), or ImplementationSpecific (Default Value). 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: ImplementationSpecific. This is the default value. Service: tea-svc Port: 80 Mappings: Path: /coffee Rule: ImplementationSpecific. This is the default value. Service: coffee-svc Port: 80
   TLS Settings	Specifies whether to enable TLS authentication. You can enable TLS authentication for the Ingress. Domain Name: the 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. For more information, see Use an ALB Ingress to configure certificates for an HTTPS listener.	Turn off TLS Settings. In this example, you do not need to configure a TLS certificate.
   More	Canary Release: Enable canary releases. 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 nginx.ingress.kubernetes.io/canary-by-header, nginx.ingress.kubernetes.io/canary-by-header-value, or nginx.ingress.kubernetes.io/canary-by-header-pattern annotation. Based on Cookie: Distribute traffic based on cookies by adding the nginx.ingress.kubernetes.io/canary-by-cookie annotation. Based on Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the nginx.ingress.kubernetes.io/canary-weight annotation. Protocol: Select the protocol used by the backend Service by adding the nginx.ingress.kubernetes.io/backend-protocol annotation. HTTP, HTTPS, gRPC, and gRPCS are supported. Rewrite Path: Add the nginx.ingress.kubernetes.io/rewrite-target annotation to rewrite the paths in client requests before the requests are forwarded to the backend Service.	Turn off Canary Release. Use the default values of the Protocol and Rewrite Path parameters. In this example, you do not need to configure these parameters.
   Custom Forwarding Rules	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. The following condition types are available in the Add Condition drop-down list: Host: Specifies that only requests that contain the specified domain names are routed. The logical relationship between multiple domain names is OR. 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 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. Select the Service that you want to access from the Service Name drop-down list. Select the port used to connect to the Service from the Port drop-down list. Specify a custom weight for each backend server group. Note If you use the Flannel component for the cluster, the ClusterIP Service is not supported. If you select Forward To from the Action drop-down list, you do not need to configure the Mappings parameter for the rule. Return Fixed Response Specifies that fixed content is returned to clients by the ALB instance. 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 based on your business requirements. Valid values of the Response Content Type parameter: 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. You can specify multiple conditions and actions in a custom forwarding rule. You can configure domain names, paths, and HTTP request headers as forwarding conditions and forward the inbound traffic to backend server groups or return fixed content to clients. For more information, see Customize the routing rules of an ALB Ingress.	Turn off Custom Forwarding Rules. In this example, you do not need to configure custom forwarding rules.
   Annotations	You can enter custom annotation names and values. You can also select or search for annotations by name from the drop-down list. For more information about Ingress annotations, see Annotations. Click +Add Annotation to add an annotation. ACK does not limit the number of Ingress annotations that you can add.	In this example, you do not need to configure annotations.
   Labels	You can add labels to describe the characteristics of the Ingress. Click +Add Label to add a label. No limit is imposed on the number of Ingress labels that you can add.	In this example, you do not need to configure labels.

4. After the configurations are complete, click OK in the lower-left corner of the Create Ingress panel.

5. Perform the following steps to verify that the Ingress is created:

   1. In the left-side pane, choose Network > Ingresses. The Ingress named cafe-ingress is displayed on the Ingresses page.

   2. In the Endpoint column of cafe-ingress, you can view the endpoint.

kubectl

1. 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

   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 http://demo.domain.ingress.top, 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 the 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 overview. If this parameter is not specified, 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 the Forward requests based on URL paths section of the "Advanced ALB Ingress configurations" topic.
   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 so that requests can be routed to the backend Service and processed as expected.

2. 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

3. 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