Resolve pre-flight check failures that block ACK cluster upgrades, migrations, or component upgrades.
Check types
ACK runs three types of pre-flight checks:
| Check type | When it runs | Applies to |
|---|---|---|
| Cluster upgrade check | Before a cluster upgrade | All cluster types |
| Cluster migration check | Before a cluster migration | ACK Serverless Basic Edition to ACK Serverless Pro |
| Component check | Before a component upgrade | Individual components |
Cluster upgrade check
ACK checks for deprecated APIs, component version constraints, and runtime changes before a cluster upgrade. The upgrade proceeds only after all checks pass.
The check covers two categories:
-
Cluster resources: Cloud resources such as Server Load Balancer (SLB) instances and Virtual Private Cloud (VPC) networks.
-
Cluster components: Component configurations, application settings, and deprecated API usage.
Check items vary by cluster type, version, and runtime. The ACK console check page is the definitive source.
Cluster resources
| Check item | What it validates |
|---|---|
| APIServer SLB | SLB instance exists |
| SLB instance status is Normal | |
| SLB listener configuration (port and protocol) is valid | |
| SLB backend server group configuration is valid | |
| SLB access control configuration is correct (passes if not configured) | |
| VPC | VPC instance exists |
| VPC instance status is Normal | |
| vSwitch | vSwitch exists |
| vSwitch status is Normal | |
| vSwitch has at least two available IP addresses |
Cluster components
| Check item | What it validates |
|---|---|
| Kube Proxy Master | Component exists |
| Kube Proxy Worker | Component exists |
| APIService | No unavailable APIServices exist |
| Component versions | Terway, CoreDNS, cloud-controller-manager (CCM), Nginx Ingress Controller, and Metric Server versions meet upgrade requirements |
| Deprecated APIs | Cluster is not using deprecated APIs |
Cluster configuration
| Check item | What it validates |
|---|---|
| iptables | iptables configuration is valid |
| Operating system | OS supports the upgrade |
| yum | yum package manager is working correctly |
| kubelet | kubelet configuration meets expectations |
| Container runtime | Docker or containerd runtime status is Normal |
| Manifest | Manifest file meets expectations |
Cluster migration check
ACK checks the cluster before migrating from Serverless Basic Edition to Serverless Pro. The migration proceeds only after all checks pass.
The check covers two categories:
-
Cluster resources: SLB instances and VPC networks used by the cluster.
-
Cluster components: Component configurations, including whether any unavailable APIServices exist.
Check items vary by cluster type, version, and runtime. The ACK console check page is the definitive source.
Cluster resources
| Check item | What it validates |
|---|---|
| APIServer SLB | SLB instance exists |
| SLB instance status is Normal | |
| SLB listener configuration (port and protocol) is valid | |
| SLB backend server group configuration is valid | |
| SLB access control configuration is correct (passes if not configured) | |
| VPC | VPC-connected instance exists |
| VPC-connected instance status is Normal | |
| vSwitch | vSwitch exists |
| vSwitch status is Normal | |
| vSwitch has at least two available IP addresses |
Cluster components
| Check item | What it validates |
|---|---|
| Kube Proxy Master | Component exists |
| Kube Proxy Worker | Component exists |
| APIService | No unavailable APIServices exist |
Component check
ACK checks each component before upgrading it. The upgrade proceeds only after all checks pass.
Check items vary by component type, version, and runtime. The ACK console check page is the definitive source.
| Component | Check item | What it validates |
|---|---|---|
| cloud-controller-manager | Addon_CCM | Upgrading the component does not cause SLB changes |
| Component_Block_Version | CCM version can be upgraded | |
| csi-plugin | DaemonSet_Annotation | DaemonSet annotations meet expectations |
| Csi_Driver_Attributes | Container Storage Interface (CSI) Driver properties meet requirements | |
| csi-provisioner | Stateful_Set_Exist | Resource is a StatefulSet |
| Deployment_Annotation | Deployment annotations meet expectations | |
| Storage_Class_Attributes | StorageClass properties meet requirements | |
| nginx-ingress-controller | Deployment_Healthy | Nginx Ingress Deployment is healthy |
| Deployment_Not_Under_HPA | No Horizontal Pod Autoscaler (HPA) is configured for the Deployment | |
| Deployment_Not_Modified | Deployment has not been modified | |
| Nginx_Ingress_Pod_Error_Log | Nginx has no error logs | |
| LoadBalancer_Service_Healthy | Nginx service is healthy | |
| Nginx_Ingress_Configuration | Ingress has no incompatible configurations | |
| aliyun-acr-credential-helper | RamRole_Exist | Component is granted the AliyunCSManagedAcrRole RAM role |
| ack-cost-exporter | RamRole_Exist | Component is granted the AliyunCSManagedCostRole RAM role |
Fix failed checks
Common check failures and resolutions:
| Failed check | Resolution |
|---|---|
| Component version is too low | Upgrade the component. See Manage components. |
| APIService is unavailable | See the steps below. |
| Cluster contains deprecated APIs | See Deprecated APIs. |
To resolve an unavailable APIService:
-
Find the unavailable APIService.
kubectl -n kube-system get apiservices | grep -i false -
Confirm whether the APIService is still needed.
ImportantDeleting an APIService by mistake can cause cluster exceptions. Verify its purpose before proceeding.
-
If the APIService is no longer needed, delete it.
kubectl -n kube-system delete apiservices ${your-abnormal-apiservice-name}
Deprecated APIs
For clusters running Kubernetes 1.20 or later, the pre-upgrade check scans the previous day's audit logs to detect deprecated API usage.
How deprecated API detection works
When upgrading from Kubernetes 1.20 to 1.22, the system scans the 1.20 cluster's audit logs for deprecated APIs:
-
If deprecated APIs are found, the result is a notification only — it does not block the upgrade.
-
If you continue using deprecated APIs after upgrading to 1.22, security risks may arise.
Deprecated API notifications do not block the upgrade. After the upgrade, deprecated API resources are replaced with new ones. Do not create resources with deprecated APIs afterward.
Deprecated API categories
Deprecated APIs are classified by request source (User Agent).
| Category | Description | Examples | Action required |
|---|---|---|---|
| core | Core Kubernetes components. ACK automatically upgrades these during a cluster upgrade. | apiserver, scheduler, kube-controller-manager | None — not shown on the check page |
| ack | ACK-managed components. ACK displays these and guides you to upgrade them. | metrics-server, nginx-ingress-controller, coredns | Upgrade via Operations > Add-ons in the ACK console |
| opensource | Open source community components. ACK displays a partial list. Unrecognized components appear under unknown. | rancher, elasticsearch-operator | Upgrade as needed |
| unknown | Components with unrecognized sources. | kubectl, agent, Go-http-client, okhttp | Upgrade as needed |
Upgrade ACK components to clear deprecated API warnings
Go to Operations > Add-ons in the ACK console to upgrade components. Deprecated API warnings for those components clear the day after the upgrade.ACK console
If the check results include coredns, CoreDNS may use deprecated APIs in Kubernetes 1.24 or later. See Why is CoreDNS using a deprecated API?.