ACK cluster node initialization process
Container Service for Kubernetes (ACK) runs a standardized initialization process on every new node and every node added by a scale-out. The process installs and configures software per the node pool settings and joins the node to the Kubernetes cluster, so workloads can run on it.
Scope
Node initialization applies to ECS and EGS node pools in ACK managed and dedicated clusters running version 1.20 or later.
How it works
Initialization runs in four sequential phases:
-
Create node — ACK receives a scale-out or auto-add request and provisions the ECS or EGS instance per the node pool configuration, such as instance type, image, and disks. The OS then completes basic setup, such as network configuration and system disk mounting. Cloud-init then runs the User Data script, which has three parts: the Pre-defined Custom Data script, ACK initialization scripts, and the User Data script.
-
Run pre-customization scripts — Cloud-init runs the Pre-defined Custom Data script, which is typically used to install specific dependencies, set up monitoring agents, or run preliminary environment checks and configurations.
-
Run ACK initialization scripts — ACK installs Kubernetes components, optional hardware drivers, and security packages. The node then registers with the cluster API server.
-
Run custom scripts — Cloud-init runs the User Data script for application-level setup, in parallel with the node transitioning to
Ready.
ACK initialization scripts
This phase has seven sub-steps with skip mechanisms for offline or specialized environments.
Prepare the basic environment
Configures the runtime environment for Kubernetes on the node:
-
Start chronyd — synchronizes the node clock with the NTP server.
-
Set node ID and hostname — calculates and assigns a node ID. If a Custom Node Name is configured, sets it as the hostname.
-
Initialize the data disk — if data disks exist, formats the last disk in lexicographic order (NVMe first) and mounts it as the container runtime directory (for example,
/var/lib/containerd).
Skip mechanisms:
| File to create | Effect |
|---|---|
/var/.skip-auto-fdisk |
Skips disk formatting. Create the file in the Pre-defined Custom Data script. Use when managing partitions manually or when the disk has existing data. |
/var/.keep-container-data |
Skips formatting but copies existing runtime data (such as image cache) to the new mount path. Use to avoid repeated image pulls during data disk migration. |
Install Kubernetes components
Installs and configures core Kubernetes components:
-
kubelet — see Custom Node Pool Kubelet Configuration.
-
Container runtime (such as containerd) — see Custom Node Pool Containerd Configuration.
Install optional components
ACK installs additional components based on node pool configuration:
-
Heterogeneous hardware drivers and device plugin — for GPU, NPU, or other heterogeneous compute instances, installs hardware drivers and a Kubernetes device plugin (for example, the NVIDIA Device Plugin) so the scheduler can recognize and allocate these resources.
-
Image acceleration software — if features such as on-demand container image loading are enabled, installs the acceleration software and updates the container runtime configuration to accelerate container startup.
-
SGX drivers and dependencies — if ACK-TEE confidential computing is enabled, installs SGX drivers and related packages for a trusted execution environment (TEE) supporting confidential containers.
Join the cluster
After the core components are installed, kubelet starts, registers with the cluster's API server, and the node enters the cluster with an initial status of NotReady.
Install additional software
To keep nodes stable and secure, ACK installs base tool packages by default and applies security updates.
Installed packages: pigz, container-selinux, zlib, and other common tools that support advanced storage and network features
Security updates (Alibaba Cloud Linux only):
-
Upgrades
systemdas needed for stability and functionality. -
Applies minimal CVE fixes by running:
yum update-minimal --exclude kernel* --security -y
Skip mechanisms:
| File to create | Effect |
|---|---|
/var/.skip-yum |
Skips this entire sub-step, including CVE fixes. Create the file in the Pre-defined Custom Data script. Use for offline environments or strict package version control. |
/var/.skip-security-fix |
Skips CVE fixes only. Create the file in the Pre-defined Custom Data script. Base tool packages are still installed. |
Apply OS configuration
After all software installs and updates complete, reapplies the node pool OS configuration to ensure all settings take effect in the final environment. See Manage Node Pool OS Parameters.
Apply security hardening
Runs the node pool's Security Hardening scripts (such as Alibaba Cloud OS hardening) to harden kernel parameters and restrict system permissions to meet enterprise security requirements.
Parallel execution: custom scripts and node readiness
After a node joins the cluster in NotReady status, two tasks run in parallel:
-
Node status transition — kubelet communicates with the control plane. When critical components are healthy and health checks pass, the node transitions to
Readyand becomes available for pod scheduling. -
User Data script execution — Cloud-init runs the User Data script for application-level initialization, such as populating data directories or starting non-containerized helper services.
These tasks are independent. The User Data script's outcome — success, failure, or duration — does not block the node from reaching Ready. Do not assume that application pods are already running on the node when the User Data script finishes, or vice versa.
Trace custom script execution
To verify User Data script results, log on to the node and run:
cat /var/log/cloud-init-output.log