Configure ALB instances with AlbConfig - Container Service for Kubernetes

Prerequisites

The ALB Ingress Controller is installed in your cluster.
Two vSwitches in different zones are created in the same VPC as your ACK cluster.

To use ALB Ingress with an ACK dedicated cluster, grant the cluster the required permissions first.

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

Commonly used AlbConfig parameters:

Parameter	Type	Default	Creation-only	Description
`spec.config.name`	string	—	No	Name of the ALB instance
`spec.config.addressAllocatedMode`	string	`Dynamic`	No	Sets the IP mode of the ALB instance. Valid values: `Dynamic` (dynamic IP mode, default) and `Fixed` (fixed IP mode).
`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–600)
`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`	`Internet` (default): public IP. `Intranet`: VPC-internal only. Creation-only; cannot be changed later.
`spec.config.zoneMappings`	At least two vSwitches in different ALB-supported zones, in the same VPC as the cluster. Creation-only; cannot be changed later. Single-zone regions allow one vSwitch.
`spec.config.zoneMappings[].allocationId`	(Optional) EIP ID to associate with the ALB instance. If omitted, a pay-as-you-go BGP (multi-ISP) EIP is created automatically. Only pay-as-you-go (pay-by-data-transfer) EIPs not in an Internet Shared Bandwidth instance are supported. EIPs for different zones 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

Default AlbConfig settings (except 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 HTTPS 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 Internet Shared Bandwidth instance

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.

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

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

Set spec.config.id to reuse an existing ALB instance. Standard and WAF-enabled instances from the ALB console are supported; Basic instances cannot be reused. An ALB instance can be reused by only one cluster.

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

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`	When listenerForceOverride is false, the ALB Ingress Controller only manages listeners automatically created by AlbConfig (named ingress-auto-listener-{port}). Manually created listeners are not managed by AlbConfig.
Set	`false`	`true`	ALB instance attributes are not overwritten. The controller manages all listeners. Listener existence and configuration are determined by AlbConfig.

Important

Do not rename listeners on a reused ALB instance. Listeners named ingress-auto-listener-{port} are 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.

For ALB Ingress Controller 2.10.0-aliyun.1 or earlier: run kubectl edit to remove all entries from spec.listeners, which deletes listeners configured through the AlbConfig. For versions 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.

Find the log project in the ACK console under your cluster's Cluster Information > Basic Information.

To enable SLS on a reused ALB instance, set forceOverride: true.

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

Enable IPv6

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

Important

addressIpVersion takes effect only at creation and cannot be changed later.

spec:
  config:
    addressIpVersion: DualStack

Listener configurations

Create listeners

Set port and protocol in spec.listeners to define how ALB receives traffic. 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.

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.

QUIC listener

spec:
  listeners:
    - port: 443
      protocol: QUIC

Important

QUIC listeners receive HTTP/3 requests from clients.

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

If no default certificate is specified, ALB Ingress uses the first certificate as the default.

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.

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, deletion fails with 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 array is reconciled by comparing the new config against the live state 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–600 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

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

Set XForwardedForClientSourceIpsEnabled: true to extract the real client IP from X-Forwarded-For when requests pass through multiple proxies. Use XForwardedForClientSourceIpsTrusted to list trusted proxy IPs or CIDR blocks. ALB traverses X-Forwarded-For right to left and treats the first non-trusted IP 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 default or custom TLS security policy.

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

Configure a trusted proxy IP address

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

See Configure ACLs.