Install Istio with the Istio CNI plugin

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

By default Istio injects an initContainer, 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 NET_ADMIN containers. 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 performs the Istio mesh pod traffic redirection in the Kubernetes pod lifecycle’s network setup phase, thereby removing the NET_ADMIN capability requirement for users deploying pods into the Istio mesh. The Istio CNI plugin replaces the functionality provided by the istio-init container.

Prerequisites

1. Install Kubernetes with the container runtime supporting CNI and kubelet configured with the main CNI plugin enabled via --network-plugin=cni.

   • Kubernetes installations for AWS EKS, Azure AKS, and IBM Cloud IKS clusters have this capability.
   • Google Cloud GKE clusters require that the network-policy feature is enabled to have Kubernetes configured with network-plugin=cni.

2. Install Kubernetes with the ServiceAccount admission controller enabled.

   • The Kubernetes documentation highly recommends this for all Kubernetes installations where ServiceAccounts are utilized.

3. Download the Istio release.

Installation

1. Determine the Kubernetes environment’s CNI plugin --cni-bin-dir and --cni-conf-dir settings.

   1. Refer to the Hosted Kubernetes Usage section for any non-default settings required.

2. Create a namespace for the Istio control-plane components:

   $ kubectl create namespace istio-system
   

3. Expand the release’s compressed Istio CNI chart.

   $ tar -xzf install/kubernetes/helm/charts/istio-cni-*.tgz -C install/kubernetes/helm/
   

4. Install Istio CNI.

   • Option 1. Render and apply the Istio CNI Helm template.

     $ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=istio-system | kubectl apply -f -
     

   • Option 2. Install via Helm and Tiller via helm install.

     $ helm install install/kubernetes/helm/istio-cni --name=istio-cni --namespace=istio-system
     

5. Add the --set istio_cni.enabled=true setting to the Istio Installation with Helm procedure to include the installation of the Istio CNI plugin. For example:

   $ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
     --set istio_cni.enabled=true | kubectl apply -f -
   

Example: excluding specific Kubernetes namespaces

The following example configures the Istio CNI plugin to ignore pods in the namespaces istio-system, foo_ns, and bar_ns.

1. Create an istio-system namespace for the Istio control-plane components.

   $ kubectl create namespace istio-system
   

2. Create and apply Istio CNI manifest. Override the default configuration of the istio-cni Helm chart’s logLevel and excludeNamespaces parameters:

   $ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=istio-system \
   --set logLevel=info \
   --set excludeNamespaces={"istio-system,kube-system,foo_ns,bar_ns"} | kubectl apply -f -
   

3. Create and apply Istio manifest with the Istio CNI plugin enabled:

   $ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
   --set istio_cni.enabled=true | kubectl apply -f -
   

Helm chart parameters

Hosted Kubernetes Usage

Not all hosted Kubernetes clusters are created with the kubelet configured to use the CNI plugin so compatibility with this istio-cni solution is not ubiquitous. The istio-cni plugin is expected to work with any hosted Kubernetes leveraging CNI plugins. The below table indicates the known CNI status of many common Kubernetes environments.

GKE setup

1. Refer to the procedure to prepare a GKE cluster for Istio and enable network-policy in your cluster.

   • Note for existing clusters this redeploys the nodes.

2. Install Istio CNI via Helm including this option --set cniBinDir=/home/kubernetes/bin. For example, the following helm install command sets the cniBinDir value for GKE setups:

   $ helm install install/kubernetes/helm/istio-cni --name=istio-cni --namespace=istio-system --set cniBinDir=/home/kubernetes/bin
   

Sidecar injection compatibility

The use of the Istio CNI plugin requires Kubernetes pods to be deployed with a sidecar injection method that uses the istio-sidecar-injector configmap created from the Helm installation with the istio_cni.enabled=true. Refer to Istio sidecar injection for details about Istio sidecar injection methods.

The following sidecar injection methods are supported for use with the Istio CNI plugin:

1. Automatic sidecar injection

2. Manual sidecar injection with the istio-sidecar-injector configmap

   1. istioctl kube-inject using the configmap directly:

      $ istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml --injectConfigMapName istio-sidecar-injector
      $ kubectl apply -f deployment-injected.yaml
      

   2. istioctl kube-inject using a file created from the configmap:

      $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml
      $ istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml --injectConfigFile inject-config.yaml
      $ kubectl apply -f deployment-injected.yaml
      

Operational details

The Istio CNI plugin handles Kubernetes pod create and delete events and does the following:

1. Identify Istio user application pods with Istio sidecars requiring traffic redirection
2. Perform pod network namespace configuration to redirect traffic to/from the Istio sidecar

Identifying pods requiring traffic redirection

The Istio CNI plugin identifies pods requiring traffic redirection to/from the accompanying Istio proxy sidecar by checking that the pod meets all of the following conditions:

1. The pod is NOT in a Kubernetes namespace in the configured exclude_namespaces list.
2. The pod has a container named istio-proxy.
3. The pod has more than 1 container.
4. The pod has no annotation with key sidecar.istio.io/inject OR the value of the annotation is true.

Traffic redirection details

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. The following table describes the parameters to the redirect functionality. The default values for the parameters are able to be overridden by setting the corresponding application pod annotation key.

Logging

The Istio CNI plugin is run by the container runtime process space, and, therefore, the log entries are added within the kubelet process.

Compatibility with other CNI plugins

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

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 setup the application pod’s traffic redirection to the injected Istio proxy sidecar (using iptables in the pod’s network namespace).