Tutorial: Configuring the CNI of Your Cluster

OKS clusters are deployed with a default Container Network Interface (CNI) to provide network communication between Kubernetes pods.

By default, OKS installs Cilium as the cluster CNI. Cilium is deployed with a full kube-proxy replacement, which means that kube-proxy is not deployed on worker nodes.

Most cluster components are managed by OKS and are not customizable. However, you can customize the CNI configuration of your cluster. As a result, you can:

Choose the Cilium version to install during cluster creation.
Update the CNI configuration of an existing cluster, provided that the requested transition is supported.
Disable the default CNI installation to install and configure your own CNI.

Disabling the default CNI installation makes the cluster non-functional until you manually install and configure your own CNI.
This option is intended for advanced users only. It is not recommended for novice users, as you must repair and configure the cluster network yourself before workloads can communicate properly.

Understanding CNI Configuration

A Container Network Interface (CNI) is a network plugin used by Kubernetes to provide network connectivity between pods and other cluster components.

Kubernetes requires a CNI plugin so that:

Pods can communicate with each other.
Pods can communicate with services.
Network policies can be applied.
Cluster networking can function across worker nodes.

Cilium is installed by default as the cluster CNI. Cilium is a Kubernetes networking plugin that provides network connectivity, service routing, and network policy enforcement for cluster workloads. In OKS, Cilium also replaces kube-proxy, meaning that service routing is handled directly by Cilium instead of by a separate kube-proxy component.

Supported Cilium Versions

You can choose a specific Cilium version supported by OKS when creating a cluster, or when updating the CNI configuration of an existing cluster.

When updating an existing cluster, the available target versions depend on the current CNI configuration. For more information, see Updating the CNI of an Existing Cluster > CNI Compatibility Matrix.

Supported values are:

cilium-1.16
cilium-1.17
cilium-1.18
cilium-1.19

OKS deploys the selected Cilium version and keeps managing it.

Configuring a CNI on Your Cluster

Creating a Cluster With a Specific Cilium Version Using OKS CLI

Before you begin:

Install OKS CLI. For more information, see Installing and Configuring OKS CLI.
Configure your OKS CLI profile. For more information, see Managing Your Profiles.
Create a project. For more information, see Creating a Project.

To create a cluster with a specific Cilium version, use the cluster create command with the set cni option:

Request sample

$ oks-cli cluster create \
    --profile NAME_OF_PROFILE \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --set cni=CILIUM_VERSION

For more information, see Creating a Cluster and Supported Cilium Versions.

Installing a CNI Manually on a Cluster

To install and configure your own CNI, first disable the OKS-managed CNI by setting the cni configuration to none.

You can do this either:

When creating a cluster,
By updating the CNI configuration of an existing cluster, provided that the transition to none is supported. For more information, see Updating the CNI of an Existing Cluster > CNI Compatibility Matrix.

When the cni configuration is set to none, OKS does not manage or install a CNI on the cluster. The cluster network remains non-functional until you manually install and configure a CNI.

Disabling the Default CNI On Your Cluster

To disable the default CNI when creating a cluster, set the cni option to none:

Disabling the default CNI installation is an advanced configuration option:

OKS will not install Cilium during cluster creation. The cluster network will thus not be functional until you manually install and configure your own CNI.
Pods will not be able to communicate properly, and some cluster components may remain unavailable or unhealthy.
You will be responsible for configuring, updating, upgrading, and troubleshooting your CNI. OKS does not manage custom CNI installations.

Request sample

$ oks-cli cluster create \
    --profile NAME_OF_PROFILE \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --set cni=none

For more information, see Creating a Cluster.

To disable the OKS-managed CNI on an existing cluster, update its CNI configuration to none. For more information, see Configuring a CNI on Your Cluster > Updating the CNI of an Existing Cluster.

Installing Cilium Manually On Your Cluster

Before you begin:

Install the Cilium CLI.

Make sure your KUBECONFIG points to the cluster created with cni=none:

Request sample

$ export KUBECONFIG=$(oks-cli cluster kubeconfig \
  --project-name NAME_OF_PROJECT \
  --cluster-name NAME_OF_CLUSTER \
  --print-path)

Once the cni configuration of your cluster is set to none, you can manually install a CNI version on it. In this case, you will be responsible for deploying, configuring, updating, and supporting Cilium.

3DS OUTSCALE will not update, upgrade, or reconfigure this CNI installation for you.
This section provides an example using Cilium. If you wish to install another CNI, follow the official documentation of the selected network plugin and make sure it provides the networking features required by your cluster.

Install the desired Cilium version:
Request sample
```
$ cilium install --version CILIUM_VERSION
```
Cilium automatically detects that kube-proxy is not installed and fully replaces its functionalities.

For more information, see Supported Cilium Versions.
Apply a node pool manifest to create worker nodes for the cluster:
Request sample
```
$ kubectl apply -f NODEPOOL_MANIFEST.yaml
```
For more information on how to write a node pool manifest, see Node Pool Manifest Reference.

Cilium pods remain in Pending state until worker nodes are available in the cluster.
Verify that the worker nodes are in Ready state:
Request sample
```
$ kubectl get nodes
```
Verify that Cilium is running properly:
Request sample
```
$ cilium status
```
Cilium is correctly installed when the Cilium, Operator, and Envoy DaemonSet components are OK.
Verify the network connectivity:
Request sample
```
$ cilium connectivity test
```

Updating the CNI of an Existing Cluster

You can update the CNI configuration of an existing cluster. The supported target configuration depends on the CNI configuration currently used by the cluster.

CNI Compatibility Matrix

Before updating the CNI configuration, check that the transition from your current CNI version to the target version is supported.

Current CNI Supported target CNI

Current CNI	Supported target CNI
`none`	None
`cilium`	`none`, `cilium-1.17`, `cilium-1.18`
`cilium-1.17`	`none`, `cilium`, `cilium-1.18`
`cilium-1.18`	`none`, `cilium-1.19`
`cilium-1.19`	`none`

none

None

cilium

none, cilium-1.17, cilium-1.18

cilium-1.17

none, cilium, cilium-1.18

cilium-1.18

none, cilium-1.19

cilium-1.19

none

Updating the CNI of an Existing Cluster Using OKS CLI

Update the CNI configuration of the cluster by specifying the target CNI version:
Request sample
```
$ oks-cli cluster update \
    --cluster-name NAME_OF_CLUSTER \
    --set cni=CILIUM_VERSION
```
This command contains the following options that you need to specify:
- cluster-name: The name of the cluster.
- set: The configuration option to update. Set cni=CILIUM_VERSION, where CILIUM_VERSION is the target CNI configuration, for example cilium-1.18. For more information, see the CNI Compatibility Matrix.

Upgrade the cluster to apply the new CNI configuration:

Request sample

$ oks-cli cluster upgrade  \
    --cluster-name NAME_OF_CLUSTER

The upgrade can take several minutes to complete.

You can monitor the cluster during the upgrade using the following command:

$ oks-cli cluster list \
    --project-name NAME_OF_PROJECT \
    --w

This command contains the following options that you need to specify:

NAME_OF_PROJECT: The name of the project containing the cluster.
-w: Watches the cluster list and refreshes the output when the cluster status changes.

Once the upgrade is complete, list the Cilium pods running in the kube-system namespace:
Request sample
```
$ kubectl get pods -n kube-system -l k8s-app=cilium
```
Check the Cilium version running on one of the pods:
Request sample
```
$ kubectl describe pod -n kube-system <CILIUM_POD> | grep Image
```
This command contains the following options:
- CILIUM_POD: The name of one of the Cilium pods returned in the previous step. Replace CILIUM_POD with the actual pod name.
- grep Image: Filters the command output to display only the lines containing Image for readability purposes.
  
  The image version corresponds to the Cilium version currently running on the cluster.

Verifying Your CNI Configuration Using kubectl

After setting it on your cluster one way or the other, you can check the CNI configuration by retrieving your kubeconfig file:

Request sample

$ export KUBECONFIG=`oks-cli cluster kubeconfig \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER \
    --print-path`

Check the resources deployed in the kube-system namespace:
Request sample
```
$ kubectl get deployment -n kube-system
```

If the default CNI is installed, Cilium resources will be present in the cluster.

You can also check its status with the following command:

Request sample

$ cilium status

Related Pages