How to use an alternative CNI¶

Canonical Kubernetes ships with a default Container Network Interface (CNI) that is fully compatible with our distribution. It is possible, however, to use a different CNI plugin for your specific networking requirements. This guide explains how to safely disable the default CNI and deploy your own networking solution, and how to revert to the default configuration if needed.

Prerequisites¶

This guide assumes the following:

Root or sudo access to the machine.

Disable default network¶

Disable on an existing cluster¶

For an existing cluster, disable the default network plugin and its dependencies:

Note

ingress and gateway must be disabled before or at the same time as network.

sudo k8s disable ingress gateway network

Remove any configuration files left behind by the default Cilium implementation in /etc/cni/net.d/:

sudo rm -f /etc/cni/net.d/05-cilium.conflist

Disable on new clusters¶

For a new cluster, create a bootstrap configuration that disables networking:

cat <<EOF > bootstrap-config.yaml
cluster-config:
  network:
    enabled: false
EOF

Then, bootstrap the cluster with this configuration:

sudo k8s bootstrap --file bootstrap-config.yaml

Install your CNI¶

Refer to the instructions provided by your CNI solution for installation. If your CNI uses kubectl, Canonical Kubernetes supplies a built-in k8s kubectl implementation that can help with the installation process.

Verify deployment¶

Ensure the alternative CNI pods are running and in a Ready state:

watch sudo k8s kubectl get pods -A

Once the CNI pods are healthy, verify that cluster nodes reach the Ready state:

sudo k8s kubectl get nodes

Revert to default¶

You can always revert to the default networking configuration. Remove all resources associated with the alternative CNI (pods, namespace, Helm charts etc.).

Then enable the default networking features:

sudo k8s enable ingress gateway network

Kubernetes may add a network-unavailable taint when no CNI is active. This taint prevents pods from scheduling.

sudo k8s kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints

Remove the network-unavailable taint if present.

sudo k8s kubectl taint nodes --all node.kubernetes.io/network-unavailable-

Watch the Cilium pods deploy and reach a Running status:

watch sudo k8s kubectl get pods -n kube-system

Once all Cilium pods are Running and all nodes show Ready, the cluster has been successfully reverted to the default networking configuration.

sudo k8s kubectl get nodes