Install Istio with the Istio CNI plugin

8 minute read page test

Follow this guide to install, configure, and use an Istio mesh using the Istio Container Network Interface (CNI) plugin.

By default Istio injects an init container, istio-init, in pods deployed in the mesh. The istio-init container sets up the pod network traffic redirection to/from the Istio sidecar proxy. This requires the user or service-account deploying pods to the mesh to have sufficient Kubernetes RBAC permissions to deploy containers with the NET_ADMIN and NET_RAW capabilities. Requiring Istio users to have elevated Kubernetes RBAC permissions is problematic for some organizations’ security compliance. The Istio CNI plugin is a replacement for the istio-init container that performs the same networking functionality but without requiring Istio users to enable elevated Kubernetes RBAC permissions.

The Istio CNI plugin identifies user application pods with sidecars requiring traffic redirection and sets this up in the Kubernetes pod lifecycle’s network setup phase, thereby removing the requirement for the NET_ADMIN and NET_RAW capabilities for users deploying pods into the Istio mesh. The Istio CNI plugin replaces the functionality provided by the istio-init container.

Install CNI

Prerequisites

Install Kubernetes with the container runtime supporting CNI and kubelet configured with the main CNI plugin enabled via --network-plugin=cni.
- AWS EKS, Azure AKS, and IBM Cloud IKS clusters have this capability.
- Google Cloud GKE clusters have CNI enabled when any of the following features are enabled: network policy, intranode visibility, workload identity, pod security policy, or dataplane v2.
- OpenShift has CNI enabled by default.
Install Kubernetes with the ServiceAccount admission controller enabled.
- The Kubernetes documentation highly recommends this for all Kubernetes installations where ServiceAccounts are utilized.

Install Istio with CNI plugin

In most environments, a basic Istio cluster with CNI enabled can be installed using the following commands:

$ cat <<EOF > istio-cni.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    cni:
      enabled: true
EOF
$ istioctl install -f istio-cni.yaml -y

$ helm install istio-cni istio/cni -n kube-system --wait

This will deploy an istio-cni-node DaemonSet into the cluster, which installs the Istio CNI plugin binary to each node and sets up the necessary configuration for the plugin. The CNI DaemonSet runs with system-node-critical PriorityClass.

There are several commonly used install options:

components.cni.namespace=kube-system configures the namespace to install the CNI DaemonSet.
values.cni.cniBinDir and values.cni.cniConfDir configure the directory paths to install the plugin binary and create plugin configuration.
values.cni.cniConfFileName configures the name of the plugin configuration file.
values.cni.chained controls whether to configure the plugin as a chained CNI plugin.

Installing with Helm

Following the Install with Helm installation steps, there are some additional Helm values that are required to be set. You can set these either through an override values file or via the command line when installing the istiod chart. These are:

values.istio_cni.enabled should be set to the same value as values.cni.enabled.
values.istio_cni.chained should be set to the same value as values.cni.chained.

For example:

$ helm install istiod istio/istiod -n istio-system --set istio_cni.enabled=true --wait

Hosted Kubernetes settings

The istio-cni plugin is expected to work with any hosted Kubernetes version using CNI plugins. The default installation configuration works with most platforms. Some platforms required special installation settings.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    cni:
      enabled: true
      namespace: kube-system
  values:
    cni:
      cniBinDir: /home/kubernetes/bin

$ istioctl install --set profile=openshift

Operation details

Upgrade

When upgrading Istio with in-place upgrade, the CNI component can be upgraded together with the control plane using one IstioOperator resource.

When upgrading Istio with canary upgrade, because the CNI component runs as a cluster singleton, it is recommended to operate and upgrade the CNI component separately from the revisioned control plane. The following IstioOperator can be used to operate the CNI component independently.

This is not a problem for Helm as the istio-cni is installed separately.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  profile: empty # Do not include other components
  components:
    cni:
      enabled: true
  values:
    cni:
      excludeNamespaces:
        - istio-system
        - kube-system

When installing revisioned control planes with the CNI component enabled, values.istio_cni.enabled needs to be set, so that sidecar injector does not inject the istio-init init container.

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  revision: REVISION_NAME
  ...
  values:
    istio_cni:
      enabled: true
  ...

The CNI plugin at version 1.x is compatible with control plane at version 1.x-1, 1.x, and 1.x+1, which means CNI and control plane can be upgraded in any order, as long as their version difference is within one minor version.

Race condition & mitigation

The Istio CNI DaemonSet installs the CNI network plugin on every node. However, a time gap exists between when the DaemonSet pod gets scheduled onto a node, and the CNI plugin is installed and ready to be used. There is a chance that an application pod starts up during that time gap, and the kubelet has no knowledge of the Istio CNI plugin. The result is that the application pod comes up without Istio traffic redirection and bypasses Istio sidecar.

To mitigate the race between an application pod and the Istio CNI DaemonSet, an istio-validation init container is added as part of the sidecar injection, which detects if traffic redirection is set up correctly, and blocks the pod starting up if not. The CNI DaemonSet will detect and handle any pod stuck in such state; how the pod is handled is dependent on configuration described below. This mitigation is enabled by default and can be turned off by setting values.cni.repair.enabled to false.

This repair capability can be further configured with different RBAC permissions to help mitigate the theoretical attack vector detailed in ISTIO-SECURITY-2023-005. By setting the below fields to true/false as required, you can select the Kubernetes RBAC permissions granted to the Istio CNI.

Configuration	Roles	Behavior on Error	Notes
`values.cni.repair.deletePods`	DELETE pods	Pods are deleted, when rescheduled they will have the correct configuration.	Default in 1.20 and older
`values.cni.repair.labelPods`	UPDATE pods	Pods are only labeled. User will need to take manual action to resolve.
`values.cni.repair.repairPods`	None	Pods are dynamically reconfigured to have appropriate configuration. When the container restarts, the pod will continue normal execution.	Default in 1.21 and newer

Traffic redirection parameters

To redirect traffic in the application pod’s network namespace to/from the Istio proxy sidecar, the Istio CNI plugin configures the namespace’s iptables. You can adjust traffic redirection parameters using the same pod annotations as normal, such as ports and IP ranges to be included or excluded from redirection. See resource annotations for available parameters.

Compatibility with application init containers

The Istio CNI plugin may cause networking connectivity problems for any application init containers. When using Istio CNI, kubelet starts an injected pod with the following steps:

The Istio CNI plugin sets up traffic redirection to the Istio sidecar proxy within the pod.
All init containers execute and complete successfully.
The Istio sidecar proxy starts in the pod along with the pod’s other containers.

Init containers execute before the sidecar proxy starts, which can result in traffic loss during their execution. Avoid this traffic loss with one of the following settings:

Set the uid of the init container to 1337 using runAsUser. 1337 is the uid used by the sidecar proxy. Traffic sent by this uid is not captured by the Istio’s iptables rule. Application container traffic will still be captured as usual.
Set the traffic.sidecar.istio.io/excludeOutboundIPRanges annotation to disable redirecting traffic to any CIDRs the init containers communicate with.
Set the traffic.sidecar.istio.io/excludeOutboundPorts annotation to disable redirecting traffic to the specific outbound ports the init containers use.

Compatibility with other CNI plugins

The Istio CNI plugin maintains compatibility with the same set of CNI plugins as the current istio-init container which requires the NET_ADMIN and NET_RAW capabilities.

The Istio CNI plugin operates as a chained CNI plugin. This means its configuration is added to the existing CNI plugins configuration as a new configuration list element. See the CNI specification reference for further details. When a pod is created or deleted, the container runtime invokes each plugin in the list in order. The Istio CNI plugin only performs actions to set up the application pod’s traffic redirection to the injected Istio proxy sidecar (using iptables in the pod’s network namespace).