Skip to main content

Verified Node Operating Systems

Scope​

This page lists node OS images and kernel versions that have been hands-on verified across the 3 installation modes covered in Installing Cilium (Native Routing (VPC-CNI), Overlay (VPC-CNI), Overlay (GR)). Use it as a reference when choosing the OS for your cilium node pools.

When creating a new node pool, prefer something from the table below. If your business requires an OS not listed here, validate on a single-node test cluster first before rolling out broadly.

Verified OS List​

All entries below have passed the full e2e suite (cilium 1.19.4 + Egress Gateway + Nodelocal DNSCache) under all 3 installation modes.

OSOsNameKernel
TencentOS Server 4tlinux4_x86_64_public6.6.117
Ubuntu 24.04ubuntu24.04x86_646.8.0
Ubuntu 22.04ubuntu22.04x86_645.15.0
Debian 12 (bookworm)debian12.8x86_646.1.0
Debian 11 (bullseye)debian11.11x86_645.10.0
OpenCloudOS 9.4opencloudos9.0x86_646.6.119
Rocky Linux 9.3rockylinux9.3x86_645.14.0
RedHat 9.5redhat9.5x86_645.14.0

Top picks: TencentOS Server 4 or Ubuntu 24.04 — newer kernels, best compatibility with recent cilium releases.

The OsName column matches the node_os field of the tencentcloud_kubernetes_node_pool terraform resource, and corresponds to the image identifier shown in the console's "Operating System" dropdown.

How These Were Verified​

The list above is produced as follows:

  1. Prepare one test cluster per network mode (VPC-CNI / GR), and create one node pool per OS in the list (1 node per pool).
  2. Use the one-click install script to install cilium 1.19.4 + Egress Gateway + Nodelocal DNSCache.
  3. From an environment with kubeconfig pointed at the cluster, run the e2e subcommand: 
    bash -c "$(curl -sfL https://raw.githubusercontent.com/imroc/tke-guide/main/static/scripts/cilium.sh)" -- test
  4. Verify all of the following pass:
    • cilium-health status reports all nodes reachable (covers host↔Pod and Pod↔Pod cross-node connectivity)
    • coredns Pods pass health checks
    • node-local-dns Pods pass health checks
    • Default cilium connectivity test suite (skipping public-internet cases) passes end-to-end

Validating an Unlisted OS Yourself​

If you need an OS not in the list (e.g. a custom image, or another CVM public image), validate it on a single node like this:

  1. Kernel pre-check: confirm the OS kernel is ≥ 5.10 (see cilium System Requirements).
  2. Create a test cluster: use the target OS, with just 1-2 nodes; install cilium.
  3. Run the e2e suite: cilium.sh test (see one-liner above). Watch for:
    • cilium-health status — all nodes reachable
    • DNS resolution (both in-cluster service names and external domains) works
    • cilium connectivity test passes
  4. Run business-path checks: if you rely on extra features (NetworkPolicy, Egress Gateway, Cluster Mesh, etc.), exercise their critical paths once.

After the above checks pass, the OS is safe to use in production node pools.

Common OS Pitfalls​

  • TencentOS 3.x / older Ubuntu 20.04: kernel may be < 5.10; cilium install errors or some features (e.g. BPF Host Routing) won't work.
  • DataPlaneV2's bundled OS: when creating a VPC-CNI cluster with the DataPlaneV2 option, the underlying OS is incompatible with the latest cilium — see Installing Cilium — FAQ: Can DataPlaneV2 be selected when creating a VPC-CNI cluster?.
  • Custom-trimmed OS images: if you stripped BPF-related kernel modules (e.g. bpf, bpf_jit), cilium fails to start.