Before upgrading the Kubernetes version of an ACK cluster, check whether the Elastic Container Instance (ECI) platform version of existing ECI-based pods is compatible with the target Kubernetes version. If it is not, delete and recreate the affected pods before proceeding with the cluster upgrade.
What is the ECI platform version
The ECI platform version identifies the runtime environment in which ECI-based pods run. New platform versions introduce features, bug fixes, and patches.
Every pod created in an ACK Serverless cluster includes the k8s.aliyun.com/eci-platform-version annotation by default. The annotation value shows which ECI platform version the pod runs on:
apiVersion: v1
kind: Pod
metadata:
annotations:
k8s.aliyun.com/eci-platform-version: 1.0.0
name: demo-76d8d9f9d8-l7pwm
namespace: default
...Newly created ECI-based pods use platform version 1.1.0. Existing ECI-based pods use version 1.0.0 or have the annotation missing (unavailable).
Compatibility matrix
| ECI platform version | Compatible Kubernetes versions |
|---|---|
| 1.1.0 | 1.12, 1.14, 1.16, 1.18, 1.20, 1.22, 1.24, 1.26, 1.28, 1.30, and 1.31 (canary release) |
| 1.0.0 | 1.12, 1.14, 1.16, 1.18, 1.20, 1.22, and 1.24 |
Unavailable (k8s.aliyun.com/eci-platform-version annotation not configured) |
1.12, 1.14, 1.16, 1.18, 1.20, 1.22, and 1.24 |
If your target Kubernetes version is 1.26 or later, pods with version 1.0.0 or no annotation are incompatible and must be upgraded before you can upgrade the cluster.
Upgrade the ECI platform version
Prerequisites
Before you begin, make sure you have:
-
kubectl installed and configured with a valid kubeconfig file. For instructions, see Obtain the kubeconfig file of a cluster and use kubectl to connect to the cluster.
Identify pods that need upgrading
Run the following command to list all ECI-based pods with version 1.0.0 or no annotation. The output includes namespace, pod name, ECI platform version, and ECI instance ID, separated by commas.
kubectl get pods -A -o json | jq -r '.items[] | select(.metadata.annotations["k8s.aliyun.com/eci-platform-version"] == "1.0.0" or .metadata.annotations["k8s.aliyun.com/eci-platform-version"] == null or .metadata.annotations["k8s.aliyun.com/eci-platform-version"] == "") | select(.spec.nodeName | startswith("virtual-kubelet")) | "\(.metadata.namespace),\(.metadata.name),\(.metadata.annotations["k8s.aliyun.com/eci-platform-version"] // ""),\(.metadata.annotations["k8s.aliyun.com/eci-instance-id"])"'Example output:
default,portal-server-57dfc4fdc8-2gl64,,eci-2zecdr8z5jy******If the output is empty, all ECI-based pods are already on version 1.1.0 and no action is needed. If the output lists any pods, delete and recreate those pods before upgrading the cluster.
Delete and recreate affected pods
For each pod returned in the previous step, run the following command to delete it. Kubernetes automatically recreates the pod using the latest ECI platform version (1.1.0).
kubectl delete pod portal-server-57dfc4fdc8-2gl64 -n defaultExpected output:
pod "portal-server-57dfc4fdc8-2gl64" deletedVerify the upgrade
After recreating the pods, confirm that all ECI-based pods are running on version 1.1.0:
kubectl get pods -A -o json | jq -r '.items[] | select(.spec.nodeName | startswith("virtual-kubelet")) | "\(.metadata.namespace),\(.metadata.name),\(.metadata.annotations["k8s.aliyun.com/eci-platform-version"] // ""),\(.metadata.annotations["k8s.aliyun.com/eci-instance-id"] // "")"'Check the third field in each output line. All entries should show 1.1.0. Once confirmed, proceed with the ACK cluster upgrade.