All Products
Search

This Product

    Container Service for Kubernetes:Upgrade an edge node

    Document Center

    Container Service for Kubernetes:Upgrade an edge node

    Last Updated:Mar 26, 2026

    Edge node upgrades are not automated. After you upgrade the control plane, you must run the upgrade command on each edge node individually. This topic describes how to manually upgrade edge nodes in both Docker and non-Docker container runtimes.

    Prerequisites

    Before you begin, ensure that you have:

    • Upgraded the ACK edge cluster control plane. For instructions, see Upgrade an ACK Edge cluster

    • Identified the interconnect mode for your edge nodes: basic (public network) or private (Express Connect circuits)

    Limitations

    Constraint Details
    Supported version ranges Versions 1.18 to 1.24: use the steps in this topic. Versions 1.26 to 1.30: submit a ticket to contact the Container Service team. Other versions: not supported.
    Sequential minor-version upgrades Each upgrade advances by only one minor version. To go from 1.18 to 1.22, upgrade in two steps: 1.18 → 1.20, then 1.20 → 1.22.
    Version skew between control plane and edge nodes The control plane and edge nodes can differ by at most two minor versions. For example, if the control plane runs 1.22, edge nodes must run at least 1.20. Keep versions in sync where possible.
    Batch size Upgrade no more than 20 nodes per batch to limit the impact of any issue.
    Cloud nodes For cloud nodes, see Upgrade an on-cloud node pool.

    Upgrade edge nodes

    Run the upgrade steps that match your container runtime.

    If the runtime is Docker (upgrading to 1.24)

    Kubernetes 1.24 dropped Docker runtime support. Before upgrading nodes to 1.24, migrate them from Docker to containerd.

    Option 1 (recommended): Rolling migration to a new node pool

    1. Create a new node pool with the runtime set to containerd. See Edge node pool management.

    2. Gradually migrate workloads to the new node pool by either:

    3. Take the old node pool offline once all workloads are migrated.

    Option 2: In-place update

    This option restarts all containers on the node.

    1. Change the container runtime from Docker to containerd.

    2. Drain the node before starting. See Node draining and scheduling status.

    3. Run the upgrade command on each node, one at a time:

      Parameter Description Example
      TARGET_CLUSTER_VERSION The Kubernetes version of the updated control plane 1.24.6-aliyunedge.1 — see Release notes for supported Kubernetes versions
      REGION The region ID of the cluster cn-hangzhou — see Supported regions
      INTERCONNECT_MODE The network type: basic for public network, private for Express Connect circuits basic 
      export REGION="" INTERCONNECT_MODE="" TARGET_CLUSTER_VERSION=""; export ARCH=$(uname -m | awk '{print ($1 == "x86_64") ? "amd64" : (($1 == "aarch64") ? "arm64" : "amd64")}') INTERNAL=$( [ "$INTERCONNECT_MODE" = "private" ] && echo "-internal" || echo "" ); wget http://aliacs-k8s-${REGION}.oss-${REGION}${INTERNAL}.aliyuncs.com/public/pkg/run/attach/${TARGET_CLUSTER_VERSION}/${ARCH}/edgeadm -O edgeadm; chmod u+x edgeadm;./edgeadm upgrade --interconnect-mode=${INTERCONNECT_MODE} --region=${REGION}

      Replace the following parameters before running the command:

    4. Confirm the upgrade succeeded. The output includes the following message:

      This node has been upgraded successfully

      Upgrade success output

    If the runtime is not Docker

    Run the upgrade command on each node, one at a time:

    export REGION="" INTERCONNECT_MODE="" TARGET_CLUSTER_VERSION=""; export ARCH=$(uname -m | awk '{print ($1 == "x86_64") ? "amd64" : (($1 == "aarch64") ? "arm64" : "amd64")}') INTERNAL=$( [ "$INTERCONNECT_MODE" = "private" ] && echo "-internal" || echo "" ); wget http://aliacs-k8s-${REGION}.oss-${REGION}${INTERNAL}.aliyuncs.com/public/pkg/run/attach/${TARGET_CLUSTER_VERSION}/${ARCH}/edgeadm -O edgeadm; chmod u+x edgeadm;./edgeadm upgrade --interconnect-mode=${INTERCONNECT_MODE} --region=${REGION}

    Replace the following parameters before running the command:

    Parameter Description Example
    TARGET_CLUSTER_VERSION The Kubernetes version of the updated control plane 1.24.6-aliyunedge.1 — see Release notes for supported Kubernetes versions
    REGION The region ID of the cluster cn-hangzhou — see Supported regions
    INTERCONNECT_MODE The network type: basic for public network, private for Express Connect circuits basic

    Confirm the upgrade succeeded. The output includes the following message:

    This node has been upgraded successfully
    Upgrade success output

    FAQ

    What do I do if an edge node upgrade fails?

    If the output does not include This node has been upgraded successfully, refer to What do I do if an edge node fails to be upgraded when I upgrade an ACK Edge cluster? for troubleshooting steps.

    Next steps