ACK runs pre-checks before cluster upgrades, cluster migrations, component upgrades, and node pool upgrades. Each check must pass before the corresponding operation can proceed. When a check fails, ACK reports the specific item and the recommended fix.
Check types at a glance
| Check type | When it runs | Applies to |
|---|---|---|
| Cluster upgrade check | Before a cluster upgrade | All ACK clusters |
| Cluster migration check | Before a cluster migration | Dedicated-to-managed and Basic-to-managed migrations |
| Component check | Before a component upgrade | Individual ACK components |
| Node pool check | Before a node pool upgrade | Node pools in ACK clusters |
Cluster upgrade check
Kubernetes upgrades are complex and carry risk. ACK runs a mandatory pre-upgrade check to confirm the cluster is ready. The check items vary based on cluster type, Kubernetes version, and container runtime. The console always shows the most current list.
The check covers three categories:
-
Cluster resources: Cloud resources associated with the cluster, such as SLB, ECS, and VPC instances.
-
Cluster components: ACK cluster and component configurations, including component versions and deprecated API usage.
-
Cluster configuration: Node-level configurations. This category requires ACK to create a pod on each node to collect information.
| Category | Check item | What is checked |
|---|---|---|
| Cluster resources | API Server SLB | Whether the SLB instance exists |
| Whether the SLB instance status is Normal | ||
| Whether the SLB listener configurations (port and protocol) are correct | ||
| Whether the SLB backend server group configuration is correct | ||
| Whether the SLB access control configuration is correct (passes if no access control is configured) | ||
| VPC | Whether the VPC-connected instance exists | |
| Whether the VPC-connected instance is Normal | ||
| vSwitch | Whether the vSwitch exists | |
| Whether the vSwitch is Normal | ||
| Whether the vSwitch has two or more available IP addresses | ||
| ECS | Whether the ECS instance exists | |
| Whether the ECS instance is Normal | ||
| Whether the ECS security group is Normal | ||
| Whether the ECS instance subscription is active | ||
| Whether the ECS instance type meets requirements | ||
| Whether the Cloud Assistant client is Normal | ||
| Cluster components | Kube Proxy Master | Whether the component exists |
| Kube Proxy Worker | Whether the component exists | |
| API Service | Whether any unavailable API services exist | |
| Cluster instance | Whether the number of master nodes is 3 or 5 | |
| Cluster components | Whether the Terway component version meets requirements | |
| Whether the CoreDNS component version meets requirements | ||
| Whether the cloud-controller-manager component version meets requirements | ||
| Whether the Nginx Ingress Controller component version meets requirements | ||
| Whether the ACK Virtual Node component version meets requirements | ||
| Whether the Metrics Server component version meets requirements | ||
| Node | Whether the node IP address exists | |
| Whether the node is schedulable | ||
| Whether the node is in the Ready state | ||
| Whether the node operating system supports the upgrade | ||
| Whether the number of available pods on the node is greater than 2 | ||
| Deprecated API | Whether the cluster uses deprecated APIs | |
| Cluster configuration | iptables configuration | Whether the iptables configuration is correct |
| Operating system | Whether the operating system supports the upgrade | |
| yum | Whether yum is working correctly | |
| Disk | Whether the node file system is Normal | |
| Whether more than 5% of disk space on the node is free | ||
| Swap | Whether Swap is enabled on the node | |
| NTP | Whether Network Time Protocol (NTP) on the node is working correctly | |
| Systemd | Whether the node's systemd version is later than systemd-219-67 | |
| kubelet | Whether the kubelet configuration meets expectations | |
| Container runtime | Whether the Docker or containerd runtime is Normal | |
| Kernel configuration | Whether the node kernel configuration is correct | |
| Manifest configuration | Whether the manifest file meets expectations |
Cluster migration check
A pre-migration check runs automatically before a cluster migration begins. The migration proceeds only after the cluster passes the check.
This check applies to:
-
Migrating from an ACK dedicated cluster to an ACK managed cluster Pro Edition
-
Migrating from an ACK managed cluster Basic Edition to an ACK managed cluster
The check covers four categories:
-
Cluster resources: Cloud resources associated with the cluster, such as SLB, ECS, and VPC instances.
-
Cluster components: Component configurations, including unavailable API services.
-
Cluster configuration: Node-level configurations. This category requires ACK to create a pod on each node to collect information.
-
Component usage: Components that become ACK-managed after a dedicated cluster migration are checked for issues before the migration proceeds.
| Category | Check item | What is checked |
|---|---|---|
| Cluster resources | API Server SLB | Whether the SLB instance exists |
| Whether the SLB instance status is Normal | ||
| Whether the SLB listener configurations (port and protocol) are correct | ||
| Whether the SLB backend server group configuration is correct | ||
| Whether the SLB access control configuration is correct (passes if no access control is configured) | ||
| VPC | Whether the VPC-connected instance exists | |
| Whether the VPC-connected instance is Normal | ||
| vSwitch | Whether the vSwitch exists | |
| Whether the vSwitch is Normal | ||
| Whether the vSwitch has two or more available IP addresses | ||
| ECS | Whether the ECS instance exists | |
| Whether the ECS instance is Normal | ||
| Whether the ECS security group is Normal | ||
| Whether the Cloud Assistant client is Normal | ||
| Cluster components | Kube Proxy Master | Whether the component exists |
| Kube Proxy Worker | Whether the component exists | |
| API Service | Whether any unavailable API services exist | |
| Cluster instance | Whether the number of master nodes is 3 or 5 | |
| Node | Whether the node IP address exists | |
| Whether the node is schedulable | ||
| Whether the node is in the Ready state | ||
| Whether the node operating system supports the upgrade | ||
| Whether the number of available pods on the node is greater than 2 | ||
| Cluster configuration | Operating system | Whether the operating system supports the upgrade |
| yum | Whether yum is working correctly | |
| Component usage | cloud-controller-manager | Whether the cloud-controller-manager component has any issues |
Component check
ACK runs a pre-upgrade check before upgrading any component. The upgrade proceeds only after the component passes the check.
| Component | Check item | What is checked |
|---|---|---|
| cloud-controller-manager | Addon_CCM | Whether upgrading the component causes SLB changes |
| Component_Block_Version | Whether the CCM version can be upgraded | |
| csi-plugin | DaemonSet_Annotation | Whether the DaemonSet annotations meet expectations |
| Csi_Driver_Attributes | Whether the Container Storage Interface (CSI) driver properties meet requirements | |
| Node_Status_Ready | Whether cluster nodes are in the Ready state | |
| csi-provisioner | Stateful_Set_Exist | Whether the resource is a StatefulSet |
| Deployment_Annotation | Whether the deployment annotations meet expectations | |
| Storage_Class_Attributes | Whether the StorageClass properties meet requirements | |
| Csi_Provisioner_Node_Count | Whether the number of Ready nodes is 2 or more | |
| terway-eniip | Systemd | Whether the node's systemd version is later than systemd-219-67 |
| nginx-ingress-controller | Deployment_Healthy | Whether the Nginx Ingress deployment is healthy |
| Deployment_Not_Under_HPA | Whether a Horizontal Pod Autoscaler (HPA) is configured for the deployment | |
| Deployment_Not_Modified | Whether the deployment was modified | |
| Nginx_Ingress_Pod_Error_Log | Whether Nginx has error logs | |
| LoadBalancer_Service_Healthy | Whether the Nginx Service is healthy | |
| Nginx_Ingress_Configuration | Whether the Ingress has incompatible configurations | |
| aliyun-acr-credential-helper | RamRole_Exist | Whether the component is granted the AliyunCSManagedAcrRole permissions |
| ack-cost-exporter | RamRole_Exist | Whether the component is granted the AliyunCSManagedCostRole permissions |
Node pool check
ACK runs a pre-upgrade check when a node pool upgrade is triggered. The upgrade proceeds only after the node pool passes the check.
The check covers three categories:
-
Cluster resources: Cloud resources associated with the cluster, such as SLB and VPC instances.
-
Cluster components: ACK cluster, node, and application configurations.
-
Cluster configuration: Node-level configurations. This category requires ACK to create a pod on each node to collect information.
| Category | Check item | What is checked |
|---|---|---|
| Cluster resources | API Server SLB | Whether the SLB instance exists |
| Whether the SLB instance status is Normal | ||
| Whether the SLB listener configurations (port and protocol) are correct | ||
| Whether the SLB backend server group configuration is correct | ||
| Whether the SLB access control configuration is correct (passes if no access control is configured) | ||
| VPC | Whether the VPC-connected instance exists | |
| Whether the VPC-connected instance is Normal | ||
| vSwitch | Whether the vSwitch exists | |
| Whether the vSwitch is Normal | ||
| Whether the vSwitch has two or more available IP addresses | ||
| Cluster components | API Service | Whether any unavailable API services exist |
| Cluster instance | Whether the number of master nodes is 3 or 5 | |
| Node | Whether the node is in the Ready state | |
| Whether the number of available pods on the node is greater than 2 | ||
| HostPath | Whether any pods on the node use HostPath | |
| Cluster configuration | iptables configuration | Whether the iptables configuration is correct |
| Operating system | Whether the operating system supports the upgrade | |
| yum | Whether yum is working correctly | |
| Disk | Whether the node file system is Normal | |
| Remaining disk space | Whether more than 5% of disk space on the node is free | |
| Swap | Whether Swap is enabled on the node | |
| NTP | Whether NTP on the node is working correctly | |
| Systemd | Whether the node's systemd version is later than systemd-219-67 | |
| kubelet | Whether the kubelet configuration meets expectations | |
| Container runtime | Whether the Docker or containerd runtime is Normal | |
| Kernel configuration | Whether the node kernel configuration is correct | |
| Manifest configuration | Whether the manifest file meets expectations |
Solutions for failed checks
| Failed check item | Solution |
|---|---|
| systemd version is too low | Upgrade the systemd version. |
| Component version is too low | Upgrade the component version. For more information, see Manage components. |
| yum check timed out | Run the following command to check whether yum times out. The default timeout is 10 seconds. time if type yum >/dev/null; then yum list yum; fi |
| API Service is unavailable | 1. Run kubectl -n kube-system get apiservices | grep -i false to identify the unavailable API Service. 2. Confirm whether you need the service. If not, run kubectl -n kube-system delete apiservices ${your-abnormal-apiservice-name} to delete it. Important
Deleting a required API Service causes cluster exceptions. If you are unsure about the purpose of the service, contact technical support before proceeding. |
| Node has pods that use HostPath | When upgrading a node by replacing its system disk, pods that use HostPath to mount a container directory to the host may lose data. Check the mounted directory for the affected pod. If there is no impact, the upgrade can continue. This check result is for reference only and does not block the upgrade. |
| Cluster uses deprecated APIs | Identify the source of the deprecated API and take appropriate action. See Deprecated APIs. |
Deprecated APIs
For clusters running Kubernetes 1.20 or later, the pre-upgrade check scans audit logs from the previous day for deprecated API usage. For example, when upgrading a cluster from Kubernetes 1.20 to 1.22, the check scans the 1.20 cluster's audit logs to identify any deprecated APIs in use.
The deprecated API check is a notification only — it does not block the upgrade. However, continuing to use deprecated APIs after upgrading to Kubernetes 1.22 introduces security risks. Assess the impact on your services before proceeding.
Deprecated APIs are categorized by request source (user agent). Use the Type column in the following table to identify where a deprecated API originates and what action to take.
| Type | What it means | Action | Example |
|---|---|---|---|
| core | Kubernetes core components | No action required. ACK automatically upgrades these components during the cluster upgrade. They do not appear on the check page. | kube-apiserver, kube-scheduler, kube-controller-manager |
| ack | ACK components | Upgrade the affected components in the ACK console under Operations > Add-ons. The deprecated APIs are no longer displayed the day after the components are upgraded. Note
In some cases, the CoreDNS component may use deprecated APIs in Kubernetes clusters that run version 1.24 or later. If the check result includes coredns, see Why is CoreDNS using a deprecated API?. After the cluster is upgraded, the deprecated API resources are replaced with new ones. Do not use deprecated APIs to create resources after the cluster upgrade to avoid security risks. |
metrics-server, nginx-ingress-controller, CoreDNS |
| opensource | Open source community components | Decide whether to upgrade based on your requirements. The check result is for reference only and does not affect the upgrade. | rancher, elasticsearch-operator |
| unknown | Components that do not match any of the above categories | Decide whether to upgrade and perform the upgrade yourself. The check result is for reference only and does not affect the upgrade. | kubectl, agent, Go-http-client, okhttp |
To view deprecated API details:
-
On the Upgrade Cluster page, click Precheck, then click View Details.
-
On the Report page, click View Details.
-
Review the details, which include the deprecated API, user agent, type, deprecated Kubernetes version, time of last access, and source IP of the last access.