Cloud Controller Manager: Overview and changelog - Container Compute Service

The Cloud Controller Manager (CCM) is used to manage load balancing services in Kubernetes clusters. This topic introduces the CCM and describes the usage notes and release notes for the CCM.

Introduction

The CCM can be used to interface Kubernetes with infrastructure services of Alibaba Cloud and manage load balancing services in ACS clusters, including Classic Load Balancer (CLB) and Network Load Balancer (NLB).

When the type of a Service is set to Type=LoadBalancer, CCM creates or configures a CLB or NLB for the Service, including resources such as CLB or NLB instances, listeners, and backend servers.
When the endpoints of a Service change or the cluster nodes change, the CCM automatically updates the backend server groups of the CLB or NLB instance created for the Service.

Usage notes

For more information about how to use CCM to manage load balancing services, refer to the following topics:
- Before you configure load balancing, take note of the considerations. For more information, see Considerations for configuring a LoadBalancer Service.
- For more information about how to configure load balancing, see Use an automatically created SLB instance to expose an application and Use an existing SLB instance to expose an application.
- You can also customize load balancing by adding annotations to Service configurations. The cloud controller manager supports custom configurations. For more information, see Add annotations to the YAML file of a Service to configure CLB instances.
For more information about how to troubleshoot the issue that the CCM fails to pass the update precheck, see How to handle the issue that the CCM fails to pass the update precheck.

Release notes

April 2026

Version

Image address

Date

Changes

Impact

v2.14.0

registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.14.0

April 13, 2026

New features:

NLB now supports the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ip-version: "DualStack" to attach both IPv4 and IPv6 backends to a server group with automatic IP version affinity.
NLB now supports the spec.loadBalancerSourceRanges field to specify which source ranges can access the Service.
The annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-default-weight now configures or updates the default weight of a server group.

This upgrade does not affect your workloads.

January 2026

Version

Image address

Date

Description

Impact

v2.13.0

registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.13.0

January 30, 2026

New features:

CLB now supports adding additional domain certificates to HTTPS listeners using the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-domain-extensions annotation.
NLB now supports adding additional certificates to TCPSSL listeners using the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-cert-ids annotation.
NLB now supports configuring cross-zone forwarding (enabled by default) using the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-cross-zone-enabled annotation.

Optimizations:

Improved ENI attachment logic so a failure on one pod does not block other attachments.
The controller now auto-selects a VSwitch when creating a private CLB without one specified.

This update has no impact on your workloads.

December 2025

Version

Image address

Release date

Description

Impact

v2.12.4

registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.12.4

December 11, 2025

New feature:

Added Pod readiness gate webhook support, enabled by default for new clusters. See Configure readiness gates to ensure smooth Pod updates.

Fixed issue:

Fixed an issue where deleting a Service of type NLB did not automatically clean up the associated server group.

This upgrade has no impact on workloads.

November 2025

Version

Image address

Release date

Description

Impact

v2.12.3

registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.12.3

November 19, 2025

Improvement:

The CLB error log now includes the pod name (targetRef) and node information when CCM fails to find the elastic network interface (ENI) for a backend pod IP.

Fixed issue:

Fixed a potential panic during Service synchronization when querying NLB information or when an asynchronous task call fails.

This upgrade does not impact your workloads.

September 2025

Version	Image address	Release date	Description	Impact
v2.12.1	registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.12.1	September 11, 2025	Important Starting with this version, the default billing method for newly created CLB instances changes from Pay-By-Spec to Pay-By-CLCU. Existing CLB instances are not affected. See [Product Changes] Default load balancer type and billing method change for new Services and Nginx Ingress Controller. New features: Changes the default billing method for newly created CLB instances from Pay-By-Spec to Pay-By-CLCU. Improvements: Improves CLB and NLB processing speed and performance. Adds a limited number of wait-and-retry attempts when NLB OpenAPI calls are rate-limited. Optimizes metrics related to the synchronization latency for Services, routes, and nodes. Changes the retry wait time for `readinessGate` from exponential backoff to a fixed value. Fixed issues: Fixes an issue where the backend's `targetPort` was not correctly used as the health check port in NLB configurations that use both a listener port range and a manually configured health check.	This upgrade has no impact on your workloads.

July 2025

Version	Image address	Release date	Description	Impact
v2.11.4	registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.11.4	July 17, 2025	Bug fixes Fixed an issue where creating an NLB listener port range by using `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-listener-port-range` failed.	This update has no impact on existing services.

June 2025

Version	Image address	Update time	Changes	Impact
v2.11.3	registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.11.3	June 27, 2025	Improvement: Skips the OpenAPI call to add servers when the server group is empty upon creation. Bug fix: Fixed an issue where servers failed to be added when `targetPort` was set to a named port and only a subset of pods were selected in the service configuration.	This upgrade has no impact on your workloads.

May 2025

Version	Image address	Date	Changes	Impact
v2.11.2	registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.11.2	May 29, 2025	Optimizations: Optimized the server group sync logic to reduce OpenAPI calls.	This upgrade has no impact on your workloads.
v2.11.1	registry-cn-hangzhou.ack.aliyuncs.com/acs/cloud-controller-manager:v2.11.1	May 15, 2025	New Features: The `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-ignore-weight-update` annotation ignores backend server weight updates. CLB now supports assigning multiple access control (ACL) IDs to apply multiple access control policies. The `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-listener-port-range` annotation now configures a listener port range for NLB. The `NLB_ENDPOINT` environment variable now configures a custom OpenAPI endpoint for NLB. Optimizations: Improved node-join and route-addition speed with fewer OpenAPI calls. Parallelized listener and server group operations during Service sync to reduce single-Service sync time. When creating an NLB instance via OpenAPI, unspecified EIP instance IDs or IPv4 private addresses now pass null instead of an empty string. The DescribeNetworkInterfaces API call now uses `NextToken` for pagination instead of `PageSize`. Bug Fixes: Fixed an NLB issue where a Service using ReadinessGate failed to retry if its Pod was not ready.	This upgrade has no impact on your workloads.

January 2025

Version number	Release date	Description	Impact
v2.10.2	2024-01-20	New features: Adds support for adding the `node.alibabacloud.com/spot-strategy` label to nodes to identify them as preemptible instances. Optimizations: The server group is synchronized only once when multiple listeners of a Service are associated with the server group. Fixed issues: Fixed an issue where the load balancer instance could not be created if a Service was changed from type `LoadBalancer` to another type and then back to type `LoadBalancer`. The issue that the system fails to locate the pod when it wants to update the readiness status of the pod is fixed. When updating the tags of a load balancer instance, system tags with the `acs:` prefix are ignored.	No impact on workloads.

December 2024

Version number	Release date	Description	Impact
v2.10.0	2024-12-02	Important Starting from this version, changes to the value of the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags` annotation affect created and reused load balancer instances. When you use this annotation, do not modify the load balancer tags in the console. Before you upgrade to this version, make sure that the tags on the load balancer instance match the annotation. New features: The readiness feature gate is supported. Adds support for modifying tags after instance creation by using the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-additional-resource-tags` annotation. Adds support for adding the `node.alibabacloud.com/node-pool-id` and `node.alibabacloud.com/instance-charge-type` labels to nodes. NLB now supports specifying the ALPN policy for `TCPSSL` listeners by using the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn` and `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-alpn-policy` annotations. Optimizations: The version of the base image is updated to Alpine 3.18. Optimized log output by adding a `reconcileID`. Fixed issues: The issue that Services associated with NLB instances may be managed by the CLB controller is fixed.	No impact on workloads.

June 2024

Version number	Release date	Description	Impact
v2.8.3	2024-06-30	New features: The Addon Token authorization mode is supported. NLB now supports creating IP-based server groups by using the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-server-group-type` annotation. For more information about NLB server groups, see NLB server groups. Optimizations: Direct access from clients to the Kubernetes API server is supported to prevent stale data generated due to data caching. The logic for creating NLB server groups is optimized to prevent the system from repeatedly creating server groups. IP address verification is performed when you add the IP addresses of elastic network interfaces (ENIs) that are allocated to pods to CLB instances. The verification is performed to ensure that the IP addresses fall within the CIDR block of the VPC where the cluster resides.	No impact on workloads.