Manage ALB Instances via AlbConfig CRD with TLS and SLS - ACK

Prerequisites

Before you begin, ensure that you have:

The ALB Ingress controller installed in your cluster. For more information, see Manage the ALB Ingress controller.
Two vSwitches in different zones, both in the same virtual private cloud (VPC) as your ACK cluster. For more information, see Create and manage a vSwitch.

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

Usage notes

To modify resource configurations, use kubectl edit. If you use kubectl apply, run kubectl diff first to preview changes before applying.
If your cluster uses the Flannel network plugin, backend services for the ALB Ingress must be of the NodePort or LoadBalancer type.

Key parameters at a glance

The following table summarizes the most commonly used AlbConfig parameters, their default values, and whether they take effect only at creation time.

Parameter	Type	Default	Creation-only	Description
`spec.config.name`	string	—	No	Name of the ALB instance
`spec.config.addressType`	string	`Internet`	Yes	`Internet` (public) or `Intranet` (VPC-internal)
`spec.config.addressIpVersion`	string	—	Yes	Set to `DualStack` to enable IPv4/IPv6 dual stack
`spec.config.zoneMappings`	array	—	Yes	vSwitch IDs (at least two, in different zones)
`spec.config.edition`	string	`Standard`	No	ALB instance edition
`spec.config.id`	string	—	No	ID of an existing ALB instance to reuse
`spec.config.forceOverride`	boolean	`false`	No	Whether to overwrite attributes of a reused ALB instance
`spec.config.listenerForceOverride`	boolean	`false`	No	Whether to overwrite listener attributes of a reused instance
`spec.config.accessLogConfig.logProject`	string	—	No	SLS log project
`spec.config.accessLogConfig.logStore`	string	—	No	SLS Logstore (must start with `alb_`)
`spec.config.billingConfig.bandWidthPackageId`	string	—	No	Internet Shared Bandwidth instance ID
`spec.listeners[].port`	integer	—	No	Listener port
`spec.listeners[].protocol`	string	—	No	`HTTP`, `HTTPS`, or `QUIC`
`spec.listeners[].requestTimeout`	integer	`60`	No	Backend response timeout in seconds (1–180)
`spec.listeners[].gzipEnabled`	boolean	`false`	No	Enable Gzip/Brotli compression

ALB instance configurations

Create an AlbConfig

Each AlbConfig configures one ALB instance. To use multiple ALB instances, create one AlbConfig per instance.

Important

When you install the ALB Ingress controller and select Create or Select Existing for Gateway Source, the controller automatically creates an AlbConfig named alb and an IngressClass named alb.

Create alb.yaml with the following content:

Parameter	Description
`spec.config.name`	The name of the ALB instance.
`spec.config.addressType`	The IP address type. `Internet` (default): uses a public IP address. `Intranet`: uses a private IP address, accessible only within the VPC. Takes effect only at creation; cannot be changed by updating the AlbConfig.
`spec.config.zoneMappings`	The vSwitches used by the ALB Ingress. Specify at least two vSwitches in different zones. The zones must be supported by ALB. Both vSwitches must be in the same VPC as the cluster. Takes effect only at creation; cannot be changed by updating the AlbConfig. If your region has only one zone, you can specify a single vSwitch.
`spec.config.zoneMappings[].allocationId`	(Optional) The ID of an elastic IP address (EIP) to associate with the ALB instance. If not specified, a pay-as-you-go EIP using BGP (multi-ISP) bandwidth and the default security protection mode is created and associated automatically. Only pay-as-you-go (pay-by-data-transfer) EIPs that are not in an Internet Shared Bandwidth instance are supported. EIPs for different zones of the same ALB instance must be of the same type.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb
spec:
  config:
    name: alb
    addressType: Internet
    zoneMappings:
    - vSwitchId: vsw-uf6ccg2a9g71hx8go****  # Replace with your vSwitch ID.
      allocationId: eip-asdfas****            # Replace with your EIP ID. If omitted, an EIP is assigned automatically.
    - vSwitchId: vsw-uf6nun9tql5t8nh15****
      allocationId: eip-dpfmss****
  listeners:
    - port: 80
      protocol: HTTP

The default AlbConfig created during installation uses the following settings (except for vSwitchId):

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb
spec:
  config:
    accessLogConfig:
      logProject: ""
      logStore: ""
    addressAllocatedMode: Dynamic
    addressType: Internet
    billingConfig:
      internetBandwidth: 0
      internetChargeType: ""
      payType: PostPay
    deletionProtectionEnabled: true
    edition: Standard
    forceOverride: false
    zoneMappings:
    - vSwitchId: #...
    - vSwitchId: #...
status:
  loadBalancer:
    dnsname: alb-s2em8fr9debkg5****.cn-shenzhen.alb.aliyuncs.com
    id: alb-s2em8fr9debkg5****

Apply the configuration:

kubectl apply -f alb.yaml

Expected output:

AlbConfig.alibabacloud.com/alb created

Verify the AlbConfig:

PORT&PROTOCOL and CERTID are empty until you configure HTTP listeners and certificates.

kubectl get AlbConfig

Expected output:

NAME   ALBID        DNSNAME                                  PORT&PROTOCOL   CERTID   AGE
alb    alb-******   alb-******.<regionID>.alb.aliyuncs.com                            28m

Update an AlbConfig

List your AlbConfigs:
```
kubectl get AlbConfig
```

Edit the AlbConfig:

kubectl edit albconfig <ALBCONFIG_NAME>

For example, to rename the ALB instance to new_alb:

spec:
  config:
    name: new_alb

Delete an AlbConfig

Deleting an AlbConfig deletes the associated ALB instance.

Important

Delete all Ingresses associated with the AlbConfig before deleting it.

kubectl delete AlbConfig <AlbConfig_NAME>

Bind an EIP bandwidth plan

To bind an Internet Shared Bandwidth instance to the ALB instance, set billingConfig.bandWidthPackageId:

This only applies to internet-facing ALB instances. To purchase an Internet Shared Bandwidth instance, see Create an Internet Shared Bandwidth.

spec:
  config:
    name: alb
    addressType: Internet
    edition: Standard
    zoneMappings:
    - vSwitchId: vsw-2vcqeyvwsnd***
    - vSwitchId: vsw-2vcbhjlqu7y***
    billingConfig:
      bandWidthPackageId: cbwp-2vcjucp49otd8qolhm***

Create and use multiple ALB instances

To use multiple ALB instances, create a separate AlbConfig and IngressClass for each instance.

Create alb-2.yaml:

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: alb-2
spec:
  config:
    name: alb-2
    addressType: Internet
    zoneMappings:
    - vSwitchId: vsw-uf6ccg2a9g71hx8go****
    - vSwitchId: vsw-uf6nun9tql5t8nh15****

Apply it:
```
kubectl apply -f alb-2.yaml
```

Create ingress_class2.yaml:

Clusters v1.19 and later

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

Clusters earlier than v1.19

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

Apply it:
```
kubectl apply -f ingress_class2.yaml
```

Create ingress2.yaml. Set ingressClassName to the IngressClass for the target ALB instance:

Clusters v1.19 and later

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

Clusters earlier than v1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress2
spec:
  ingressClassName: alb-2
  rules:
  - http:
      paths:
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

Apply it:
```
kubectl apply -f ingress2.yaml
```

Associate an AlbConfig with an Ingress using IngressClass

Use an IngressClass to bind an AlbConfig to an ALB Ingress.

Step 1: Create an IngressClass

Create ingress_class.yaml:

Clusters v1.19 and later

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

Clusters earlier than v1.19

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

Apply it:

kubectl apply -f ingress_class.yaml

Expected output:

ingressclass.networking.k8s.io/alb created

Step 2: Create an Ingress that references the IngressClass

Create ingress.yaml and set ingressClassName to the IngressClass name:

Clusters v1.19 and later

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

Clusters earlier than v1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /tea
        backend:
          serviceName: tea-svc
          servicePort: 80
      - path: /coffee
        backend:
          serviceName: coffee-svc
          servicePort: 80

Apply it:

kubectl apply -f ingress.yaml

Expected output:

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

Reused ALB instance management

Reuse an existing ALB instance

To reuse an existing ALB instance, set spec.config.id to the instance ID. Standard ALB instances and Web Application Firewall (WAF)-enabled ALB instances from the ALB console are supported. Basic ALB instances cannot be reused.

apiVersion: alibabacloud.com/v1
kind: AlbConfig
metadata:
  name: reuse-alb
spec:
  config:
    id: ****
    forceOverride: false
    listenerForceOverride: false

The following table describes how id, forceOverride, and listenerForceOverride interact:

`id`	`forceOverride`	`listenerForceOverride`	Result
Not set	—	—	ALB instance is not reused. `forceOverride` and `listenerForceOverride` have no effect.
Set	`true`	—	ALB instance and listener attributes are overwritten.
Set	`false`	`false`	ALB instance attributes are not overwritten. Listener attributes are not overwritten.
Set	`false`	`true`	ALB instance attributes are not overwritten. The controller manages all listeners. Listeners whose names match `ingress-auto-listener-{port}` are treated as controller-managed and may be overwritten.

Important

Do not rename listeners on a reused ALB instance. Listeners created or updated through AlbConfigs are named ingress-auto-listener-{port} and managed by ACK. Listeners with other names are managed in the ALB console.

Delete the AlbConfig of a reused ALB instance

Deleting the AlbConfig of a reused ALB instance does not delete the ALB instance itself.

If your ALB Ingress controller version is 2.10.0-aliyun.1 or earlier, run kubectl edit to remove all entries from spec.listeners first. This deletes the listeners configured through the AlbConfig. If your ALB Ingress controller is later than 2.10.0-aliyun.1, skip this step.
Delete all Ingresses associated with the AlbConfig, then delete the AlbConfig:
```
kubectl delete AlbConfig <AlbConfig_NAME>
```

Advanced configurations

Enable SLS to collect access logs

Set logProject and logStore in spec.config.accessLogConfig:

spec:
  config:
    accessLogConfig:
      logProject: "k8s-log-xz92lvykqj1siwvif****"
      logStore: "alb_****"

The logStore value must start with alb_. If the specified Logstore does not exist, a new one is created automatically.

To find the log project associated with your cluster, go to the ACK console, navigate to your cluster's Cluster Information page, and check the Basic Information tab.

When reusing an existing ALB instance, set forceOverride: true to enable SLS. For more information, see Reuse an existing ALB instance.

After enabling, click the project name next to Log Service Project on the Basic Information tab to view logs in the SLS console.

Enable IPv6

Set addressIpVersion: DualStack to enable IPv4/IPv6 dual stack:

Important

addressIpVersion takes effect only at creation. It cannot be changed by updating the AlbConfig.

spec:
  config:
    addressIpVersion: DualStack

Listener configurations

Create listeners

Listeners define the protocols and ports the ALB instance uses to receive traffic. Set port and protocol in spec.listeners. Supported protocols: HTTP, HTTPS, and Quick UDP Internet Connections (QUIC).

Important

Modifying port or protocol deletes the existing listener and creates a new one. To configure multiple listeners with different protocols, add the required annotations to your Ingress. For more information, see Configure custom listening ports.

HTTP listener

spec:
  listeners:
    - port: 80
      protocol: HTTP

HTTP natively supports WebSocket. No additional configuration is required.

HTTPS listener

spec:
  listeners:
    - port: 443
      protocol: HTTPS

Important

HTTPS listeners require certificates. For more information, see Configure certificates to encrypt communication on HTTPS ports.

QUIC listener

spec:
  listeners:
    - port: 443
      protocol: QUIC

Important

QUIC listeners receive requests from clients using the HTTP/3 protocol. For more information, see Use QUIC listeners to support HTTP/3.

Specify a certificate

To add a certificate to an HTTPS listener, run kubectl edit albconfig <Albconfig_Name> and set the certificates field:

spec:
  listeners:
  - caEnabled: false
    certificates:
    - CertificateId: 756****-cn-hangzhou
      IsDefault: true
    port: 443
    protocol: HTTPS

ALB uses the first certificate as the default. When the default certificate expires or no longer meets requirements, ALB falls back to other configured certificates.

If no certificate is specified, listener creation is deferred until an Ingress is associated and a certificate is automatically discovered based on the domain name.

For more information, see Configure HTTPS certificates for encrypted communication.

Delete a listener

Run kubectl edit albconfig <Albconfig_Name> and remove the listener entry from spec.listeners.

Important

Disassociate all Ingresses from the listener before deleting it. Otherwise, you fail to delete the listener and the system prompts errors.

For example, to delete the listener on port 8002:

# Before
listeners:
- port: 8001
  protocol: HTTP
- port: 8002
  protocol: HTTP

# After
listeners:
- port: 8001
  protocol: HTTP

How listener updates work

The listeners field is an array. When you apply a new configuration, the controller compares the new array against the live configuration and the last-applied-configuration annotation:

In new config	In live config	In `last-applied-configuration`	Result
Yes	Yes	—	Listener is retained.
Yes	No	—	Listener is added.
No	—	Yes	Listener is deleted. Fields may reset to defaults.
No	Yes	No	Listener is deleted.

Example:

Given these three states:

# New configuration
listeners:
- port: 8001
  protocol: HTTP
- port: 8003
  protocol: HTTP
- port: 8005  # New
  protocol: HTTP

# Live configuration
listeners:
- port: 8001
  protocol: HTTP
- port: 8002
  protocol: HTTP
- port: 8003
  protocol: HTTP
- port: 8004
  protocol: HTTP

# last-applied-configuration
listeners:
- port: 8001
  protocol: HTTP
- port: 8002
  protocol: HTTP
- port: 8003
  protocol: HTTP

After applying the new configuration:

listeners:
- port: 8001  # Retained (in new config and live config)
  protocol: HTTP
- port: 8003  # Retained (in new config and live config)
  protocol: HTTP
- port: 8005  # Added (in new config, not in live config)
  protocol: HTTP
# Port 8002: deleted (not in new config, in last-applied-configuration)
# Port 8004: deleted (not in new config, in live config, not in last-applied-configuration)

Set the connection timeout period

Set requestTimeout to control how long ALB waits for a backend response before returning HTTP 504 to the client. Valid range: 1–180 seconds. Default: 60 seconds.

spec:
  listeners:
  - port: 80
    protocol: HTTP
    requestTimeout: 40

Advanced listener configurations

Configure data compression

Set gzipEnabled: true to enable compression. All file types support Brotli compression. The following file types also 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.

spec:
  listeners:
  - port: 80
    protocol: HTTP
    gzipEnabled: true

Preserve client IP addresses

When enabled, ALB adds the client IP address to the X-Forwarded-For header before forwarding the request to the backend.

Important

Available for HTTP and HTTPS listeners only.

spec:
  listeners:
  - port: 80
    protocol: HTTP
    xForwardedForConfig:
      XForwardedForEnabled: true # This parameter cannot be set to false.

Retrieve client connection metadata

Use xForwardedForConfig to append client and listener metadata to request headers forwarded to the backend. All fields below are available for HTTP and HTTPS listeners.

Field	When set to `true`
`XForwardedForClientSrcPortEnabled`	Adds the port the client used to connect to the ALB instance.
`XForwardedForProtoEnabled`	Adds the listener protocol used by the ALB instance.
`XForwardedForSLBIdEnabled`	Adds the ALB instance ID.
`XForwardedForSLBPortEnabled`	Adds the listening port of the ALB instance.

Example — append all four headers:

spec:
  listeners:
  - port: 80
    protocol: HTTP
    xForwardedForConfig:
      XForwardedForClientSrcPortEnabled: true
      XForwardedForProtoEnabled: true
      XForwardedForSLBIdEnabled: true
      XForwardedForSLBPortEnabled: true

Retrieve the client IP address from a trusted proxy chain

When requests pass through multiple proxy servers, set XForwardedForClientSourceIpsEnabled: true to extract the real client IP from the X-Forwarded-For header. Use XForwardedForClientSourceIpsTrusted to list trusted proxy IP addresses or CIDR blocks. ALB traverses the X-Forwarded-For header from right to left and treats the first IP not on the trusted list as the client IP.

For example, if X-Forwarded-For is <client IP, proxy-1, proxy-2>, add proxy-1 and proxy-2 to the trusted list.

Important

Available for HTTP and HTTPS listeners only.

spec:
  listeners:
  - port: 80
    protocol: HTTP
    xForwardedForConfig:
      XForwardedForClientSourceIpsEnabled: true
      XForwardedForClientSourceIpsTrusted: 192.168.x.x;192.168.x.x/16

Configure a custom TLS security policy

Set securityPolicyId on an HTTPS listener to apply a TLS security policy. Both default and custom TLS security policies are supported. For available policy IDs, see TLS security policies.

spec:
  listeners:
  - port: 443
    protocol: HTTPS
    securityPolicyId: tls_cipher_policy_1_1

Configure a trusted proxy IP address

For details, see Specify a trusted proxy IP address.

Configure network ACLs

Use aclConfig to allow or deny traffic from specific IP addresses or CIDR blocks at the listener level.

spec:
  listeners:
  - port: 80
    protocol: HTTP
    aclConfig:
      aclEntries:
      - 127.0.0.1/32
      aclType: White

Parameter	Description
`aclType`	`White`: allowlist — only listed IPs can access the listener. `Black`: blocklist — listed IPs are denied access.
`aclEntries`	IP addresses or CIDR blocks to include in the ACL rule. Example: `127.0.0.1/32`.

For more information, see Configure ACLs.