Configure an AlbConfig and enable SLS - - Alibaba Cloud Documentation Center

An AlbConfig is a custom resource definition (CRD) that Alibaba Cloud Container Compute Service (ACS) provides for the Application Load Balancer (ALB) Ingress controller. The ALB Ingress controller uses AlbConfigs to configure ALB instances and listeners. This topic describes how to create, modify, and update an AlbConfig, and how to enable Simple Log Service (SLS).

Prerequisites

An ACS cluster is created. For more information, see Create an ACS cluster.
Two vSwitches that reside in different zones are created and deployed in the virtual private cloud (VPC) of the cluster. For more information, see Create and manage a vSwitch.
The ALB Ingress controller is installed in the cluster. For more information, see Manage the ALB Ingress controller.

Usage notes

To modify or update resources in a cluster, we recommend that you use the kubectl edit command. If you need to use the kubectl apply command to modify or update resources, you must run the kubectl diff command to preview the changes and make sure that the changes meet your requirements before you run the kubectl apply command. Then, run the kubectl apply command to apply the changes to the resources.
The NGINX Ingress controller of earlier versions cannot recognize the spec:ingressClassName field in the Ingress resource. If both NGINX Ingresses and ALB Ingresses are configured in your cluster, the ALB Ingresses may be reconciled by an earlier version of the NGINX Ingress controller. To avoid this issue, update the NGINX Ingress controller at the earliest opportunity or use annotations to specify the IngressClasses of ALB Ingresses.

Relationships among Services, Ingresses, and AlbConfigs

The ALB Ingress controller retrieves the changes to Ingresses from the API server and dynamically generates AlbConfig objects when Ingresses 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. The Services, the Ingresses, and the AlbConfigs object interact with each other in the following ways:

A Service is an abstraction of an application that is deployed in a group of replicated pods.
An Ingress contains reverse proxy rules. It controls the Services to which HTTP or HTTPS requests are routed. For example, an Ingress routes requests to different Services based on the hosts and URLs in the requests.
An AlbConfig is a custom resource definition (CRD) that the ALB Ingress controller uses to configure ALB instances and listeners. An AlbConfig object corresponds to one ALB instance.

Each AlbConfig corresponds to one ALB instance. An ALB instance can be specified in the forwarding rules of multiple Ingresses. Therefore, each AlbConfig can be associated with multiple Ingresses.

Create an AlbConfig

An AlbConfig is used to configure an ALB instance. If you want to configure multiple ALB instances, you must create multiple AlbConfigs. To create an AlbConfig, perform the following steps:

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

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    name: alb-test
    addressAllocatedMode: Dynamic # Valid values: Dynamic and Fixed. You can use this parameter to specify how an IP address is assigned to the ALB instance. 
    addressType: Internet
    zoneMappings:               
    - vSwitchId: vsw-uf6ccg2a9g71hx8go****
    - vSwitchId: vsw-uf6nun9tql5t8nh15****
  listeners:
    - port: 80
      protocol: HTTP

Parameter	Description
spec.config.name	The name of the ALB instance. This parameter is optional.
spec.config.addressType	The type of IP address that the ALB instance uses to provide services. This parameter is required. Valid values: Internet (default): The ALB instance uses a public IP address. The domain name of the Ingress is resolved to the public IP address. Therefore, the ALB instance can be accessed over the Internet. Intranet: The ALB instance uses a private IP address. The domain name of the Ingress is resolved to the private IP address. Therefore, the ALB instance can be accessed only within the VPC in which the ALB instance is deployed.
spec.config.zoneMappings	The IDs of the vSwitches that are used by the ALB Ingress. This parameter is required. If you want to specify vSwitches in a region that contains multiple zones, you must specify at least two vSwitch IDs in different zones. If you want to specify vSwitches in a region that contains only one zone, you can specify only one vSwitch ID. The 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 Ingresses, see Regions and zones in which ALB is available. Important After an ALB instance is created, you cannot modify the region and zone of the ALB instance. This indicates that the `addressType` and `zoneMappings` parameters in an AlbConfig take effect only when you create the AlbConfig. The parameters do not take effect when you update the AlbConfig.
`spec.config.addressAllocatedMode`	The type of the IP address used by the ALB instance. This parameter is optional. Valid values: Dynamic: dynamic IP address Fixed: static IP address

When you install the ALB Ingress controller for a cluster, the system creates a default AlbConfig. The parameters of the default AlbConfig use the following settings, except for the vSwitchID parameter.

Default AlbConfig configurations

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo                      # The name of the AlbConfig. 
spec:
  config:
    accessLogConfig:
      logProject: ""
      logStore: ""
    addressAllocatedMode: Dynamic # You can use this parameter to specify how an IP address is assigned to the ALB instance. Valid values: Dynamic and Fixed. A value of Dynamic specifies a dynamic IP address. A value of Fixed specifies a static IP address. 
    addressType: Internet
    billingConfig:
      internetBandwidth: 0
      internetChargeType: ""
      payType: PostPay
    deletionProtectionEnabled: true
    edition: Standard
    forceOverride: false
    zoneMappings:
    - vSwitchId: vsw-wz92lvykqj1siwvif****        # The ID of a vSwitch. If the ALB instance uses a dynamic IP address, specify two vSwitches. If the ALB instance uses a static IP address, specify one vSwitch. 
    - vSwitchId: vsw-wz9mnucx78c7i6iog****        # The ID of a vSwitch. 
status:
  loadBalancer:
    dnsname: alb-s2em8fr9debkg5****.cn-shenzhen.alb.aliyuncs.com
    id: alb-s2em8fr9debkg5****

Run the following command to create an AlbConfig:

kubectl apply -f alb-test.yaml

Expected output:

albconfig.alibabacloud.com/alb-demo created

Run the following command to query the name of the AlbConfig:

kubectl -n kube-system get AlbConfig

Expected output:

NAME       ALBID        DNSNAME                                  PORT&PROTOCOL   CERTID                 AGE
alb-demo   alb-******   alb-******.<regionID>.alb.aliyuncs.com   443/HTTPS       11055487-cn-<regionID>  2d

Update an AlbConfig

In Kubernetes, the kubectl apply command overwrites the configurations of objects but the kubectl edit command only adds configurations to objects. To update an ALB instance created by using an AlbConfig, we recommend that you use the kubectl edit command. To update an AlbConfig, perform the following steps:

Run the following command to query the name of the AlbConfig:

kubectl -n kube-system get AlbConfig

Expected output:

NAME       ALBID        DNSNAME                                  PORT&PROTOCOL   CERTID                 AGE
alb-demo   alb-******   alb-******.<regionID>.alb.aliyuncs.com   443/HTTPS       11055487-cn-<regionID>  2d

Run the following command to modify the AlbConfig:
Important
- We recommend that you run the kubectl edit command to update resources in your cluster. To use the kubectl apply command to update resources, run the kubectl diff command to preview the changes and make sure that the changes meet your requirements before you run the kubectl apply command. Then, you can run the kubectl apply command to apply the changes to the resources.
- The kubectl apply command overwrites the configurations of the AlbConfig. If the YAML file of the AlbConfig does not contain listener settings, the update does not affect the existing listeners. If the YAML file contains listener settings, the existing listeners are reconciled based on the updated listener settings. Therefore, you need to specify all listeners that are in use, such as commonly used listeners that listen on ports 80 and 443.
```
kubectl -n kube-system edit AlbConfig alb-demo
```
Update the AlbConfig configuration file based on your business requirements. For example, you can update the spec.config.name parameter to change the name of the AlbConfig to test.
```
...
 spec:
 config:
 name: test # The new name of the AlbConfig. 
...
```

Use an IngressClass to associate an AlbConfig with an Ingress

Important

We recommend that you run the kubectl edit command to update resources in your cluster. To use the kubectl apply command to update resources, run the kubectl diff command to preview the changes and make sure that the changes meet your requirements before you run the kubectl apply command. Then, you can run the kubectl apply command to apply the changes to the resources.

You can associate an AlbConfig with an ALB Ingress by using an IngressClass. To do this, you need to create an IngressClass first.

Create a file named alb.yaml and add the following content to the file. The file is used to create an IngressClass.

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

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

Create a file named ingress.yaml and add the following content to the file. Set the ingressClassName parameter to the alb IngressClass.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cafe-ingress 
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      # Specify a context path. 
      - path: /tea
        pathType: ImplementationSpecific
        backend:
          service:
            name: tea-svc
            port:
              number: 80
      # Specify a context path. 
      - path: /coffee
        pathType: ImplementationSpecific
        backend:
          service:
            name: coffee-svc
            port: 
              number: 80

Run the following command to create an Ingress:

kubectl apply -f ingress.yaml

Expected output:

ingress.networking.k8s.io/cafe-ingress created

After you complete the preceding steps, you can use the IngressClass to associate the AlbConfig with the Ingress.

Rename an ALB instance

Run the following command to rename an ALB instance.

Important

We recommend that you use the kubectl edit command to update resources in your cluster. To use the kubectl apply command to update resources, run the kubectl diff command to preview the changes and make sure that the changes meet your requirements before you run the kubectl apply command. Then, you can run the kubectl apply command to apply the changes to the resources.

kubectl -n kube-system edit AlbConfig alb-demo

Change the value of the config.name parameter in the configuration file and save the file. Then, the new name of the ALB instance automatically takes effect.

...
  spec:
    config:
      name: test   # The new name. 
...

Enable IPv6

When you use an AlbConfig to create an ALB instance, you can set the addressIpVersion parameter to DualStack to enable IPv4/IPv6 dual stack.

Important

The addressIpVerison parameter is available only when you create an ALB instance. You cannot modify the parameter after the ALB instance is created.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    addressIpVersion: DualStack
    ...

Specify a custom TLS security policy

Important

When you use an AlbConfig to configure an HTTPS listener, you can specify a TLS security policy. Custom TLS security policies and default TLS security policies are supported. For more information, see TLS security policies.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    #...
  listeners:
  - port: 443
    protocol: HTTPS
    securityPolicyId: tls_cipher_policy_1_1
  #...

Enable SLS to collect access logs

Important

If you want to collect the access logs of ALB Ingresses, specify the logProject and logStore parameters in the AlbConfig configurations.

Note

SLS projects must be manually created. For more information about how to create SLS projects, see Manage a project.
The name of the Logstore that you specify by using the logStore parameter must start with alb_. If the specified Logstore does not exist, the system automatically creates one.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
    accessLogConfig:
      logProject: "k8s-log-xz92lvykqj1siwvif****"
      logStore: "alb_****"
    #...

After you save the modification to the AlbConfig configurations, you can go to the SLS console and view the collected log in the specified Logstore.

Reuse an existing ALB instance

If you want to reuse an existing ALB instance, specify the ID of the ALB instance in the AlbConfig configurations when you create the AlbConfig. You can reuse a standard ALB instance or a Web Application Firewall (WAF)-enabled ALB instance that is created in the SLB console. You cannot reuse a basic ALB instance.

Important

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: reuse-alb
spec:
  config:
    id: **** # The ID of the standard ALB instance or WAF-enabled ALB instance that is created in the SLB console. 
    forceOverride: false
    listenerForceOverride: false

The following table describes the parameters.

Parameter	Description
id	If the `id` parameter does not exist or the `id` parameter is not specified, no ALB instance is reused. In this case, the `forceOverride` and `listenerForceOverride` parameters do not take effect. If the `id` parameter is set to a valid instance ID, the corresponding ALB instance is reused. If the `forceOverride` parameter is set to `true`, the ALB instance attributes and listener attributes are forcefully overwritten. If the `forceOverride` parameter is set to `false`, the ALB instance attributes are not forcefully overwritten. In this case, the `listenerForceOverride` parameter determines whether to forcefully overwrite the listener attributes. Important If an ALB instance is reused, we recommend that you do not modify the listener names. Otherwise, the listeners cannot be managed by ACS. The listeners created or updated by using AlbConfigs are managed by ACS, and their names are in the `ingress-auto-listener-{port}` format by default. The listeners whose names are not in the format are managed in the SLB console.
forceOverride	Specifies whether to forcefully overwrite ALB instance attributes when the ALB instance is reused. Valid values: `true`: forcefully overwrites ALB instance attributes. `false`: does not overwrite listener attributes. If you set this parameter to false, the ALB instance attributes are not modified when you modify the AlbConfig.
listenerForceOverride	Specifies whether to forcefully overwrite listener attributes when the ALB instance is reused. Valid values: `true`: forcefully overwrites listener attributes. `false`: does not overwrite listener attributes.

Create listeners

If an ALB instance is reused, you can modify the AlbConfig of the instance to add listeners or modify the existing listener configurations. Run the kubectl edit albconfig <Albconfig_Name> command and set the port and protocol parameters in the AlbConfig to create a listener. The port and protocol parameters are used to uniquely identify a listener. If you modify the port or protocol of a listener, the system deletes the listener and creates a new listener based on the modification.

Note

HTTP is compatible with WebSocket. No additional configuration is required.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-demo
spec:
  config:
  ...
  listeners:
    - port: 80
      protocol: HTTP # Valid values: HTTP, HTTPS, and QUIC. 
  ...

Create and use multiple ALB instances

If you want an Ingress to use multiple ALB instances, specify different IngressClasses in the spec.ingressClassName parameter in the Ingress configuration file.

Create a file named alb-demo2.yaml and add the following content to the file:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: demo
spec:
  config:
    name: alb-demo2        # The name of an ALB instance. 
    addressType: Internet  # The ALB instance uses a public IP address. 
    zoneMappings:
    - vSwitchId: vsw-uf6ccg2a9g71hx8go****
    - vSwitchId: vsw-uf6nun9tql5t8nh15****

Run the following command to create an AlbConfig:

kubectl apply -f alb-demo2.yaml

Expected output:

AlbConfig.alibabacloud.com/demo created

Create a file named alb.yaml and add the following content to the file. The file is used to create an IngressClass.

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

Run the following command to create an IngressClass:

kubectl apply -f alb.yaml

Expected output:

ingressclass.networking.k8s.io/alb-demo2 created

Create a file named ingress.yaml and add the following content to the file. Specify different ALB instances by using the ingressClassName parameter.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  namespace: default
spec:
  ingressClassName: alb-demo2
  rules:
    - host: ""
      http:
        paths:
          - backend:
             service:
              name: demo-service
              port:
                number: 80
            path: /hello
            pathType: ImplementationSpecific

Set the connection timeout period for listeners

Important

You can set the connection timeout period for listeners in the configuration of an AlbConfig. The connection timeout period can range from 1 second to 180 seconds. If no response is received from the backend server within the specified connection timeout period, ALB returns an HTTP 504 error code to the client. If you do not specify the connection timeout period, the default connection timeout period, which is 60 seconds, is used. The following YAML file provides an example:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: default
spec:
  config:
    ...
  listeners:
  - port: 80
    protocol: HTTP
    requestTimeout: 60
  ...

Configure data compression

Important

You can enable or disable data compression for listeners in an AlbConfig. Valid values of the gzipEnabled parameter:

true: compresses specific types of files.
false: does not compress files.

Note

All file types support Brotli compression. The following file types support Gzip compression: text/xml, text/plain, text/css, application/javascript, application/x-javascript, application/rss+xml, application/atom+xml, application/xml, and application/json.

The following sample code for a YAML file shows how to disable data compression:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: default
spec:
  config:
    ...
  listeners:
  - port: 80
    protocol: HTTP
    gzipEnabled: false
  ...

Preserve client IP addresses

You can specify the X-Forwarded-For header field in an AlbConfig to preserve client IP addresses. Valid values of the XForwardedForEnabled parameter:

true: enables client IP address preservation.
false: disables client IP address preservation.

Note