• Install Istio with the Istio CNI plugin
    • Prerequisites
    • Installation
      • Helm chart parameters
      • Excluding specific Kubernetes namespaces
      • Hosted Kubernetes settings
      • GKE setup
    • Sidecar injection compatibility
    • Operational details
      • Identifying pods requiring traffic redirection
      • Traffic redirection parameters
      • Logging
      • Compatibility with application init containers
      • Compatibility with other CNI plugins
    • See also

    Install Istio with the Istio CNI plugin

    Follow this guide 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 inthe mesh. The istio-init container sets up the pod network trafficredirection to/from the Istio sidecar proxy. This requires the user orservice-account deploying pods to the mesh to have sufficient Kubernetes RBACpermissions to deploy NET_ADMIN containers.Requiring Istio users to have elevated Kubernetes RBAC permissions isproblematic for some organizations’ security compliance. The Istio CNI pluginis a replacement for the istio-init container that performs the samenetworking functionality but without requiring Istio users to enable elevatedKubernetes RBAC permissions.

    The Istio CNI plugin performs the Istio mesh pod traffic redirection in the Kubernetes pod lifecycle’s networksetup phase, thereby removing the NET_ADMIN capability requirementfor users deploying pods into the Istio mesh. The Istio CNI pluginreplaces the functionality provided by the istio-init container.

    Prerequisites

    • Install Kubernetes with the container runtime supporting CNI and kubelet configuredwith 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 require that thenetwork-policy featureis enabled to have Kubernetes configured with network-plugin=cni.
      • OpenShift has CNI enabled by default.
    • Install Kubernetes with the ServiceAccount admission controller enabled.

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

    Installation

    • Determine the Kubernetes environment’s CNI plugin —cni-bin-dir and —cni-conf-dir settings.Refer to Hosted Kubernetes settings for any non-default settings required.

    • Install Istio CNI and Istio using istioctl.Refer to the Istio install instructions and pass —set cni.enabled=true option.Pass —set values.cni.cniBinDir=… and/or —set values.cni.cniConfDir=… options when installing istio-cni if non-default,as determined in the previous step.

    Helm chart parameters

    The following table shows all the options that the istio-cni configuration supports:

    OptionValuesDefaultDescription
    hubThe container registry to pull the install-cni image.
    tagThe container tag to use to pull the install-cni image.
    pullPolicyAlwaysThe image pull policy for the install-cni image.
    logLevelpanic, fatal, error, warn, info, debugwarnLogging level for CNI binary.
    excludeNamespaces[]string[ istio-system ]List of namespaces to exclude from Istio pod check.
    cniBinDir/opt/cni/binMust be the same as the environment’s —cni-bin-dir setting (kubelet parameter).
    cniConfDir/etc/cni/net.dMust be the same as the environment’s —cni-conf-dir setting (kubelet parameter).
    cniConfFileNameLeave unset to auto-find the first file in the cni-conf-dir (as kubelet does). Primarily used for testing install-cni plugin configuration. If set, install-cni will inject the plugin configuration into this file in the cni-conf-dir.
    psp_cluster_roleThis value refers to a ClusterRole and can be used to create a RoleBinding in the namespace of istio-cni. This is useful if you use Pod Security Policies and want to allow istio-cni to run as priviliged Pods.
    podAnnotations{}Additional custom annotations to be set on pod level.

    These options are accessed through values.cni.<option-name> in istioctl manifest commands, either as a —set flag,or the corresponding path in a custom overlay file.

    Excluding specific Kubernetes namespaces

    This example uses Istioctl to perform the following tasks:

    • Install the Istio CNI plugin.
    • Configure its log level.
    • Ignore the pods in the following namespaces:
      • istio-system
      • foo_ns
      • bar_ns

    Refer to the Customizable Install with Istioctl for complete instructions.

    Use the following command to render and apply Istio CNI components and override the default configuration of thelogLevel and excludeNamespaces parameters for istio-cni:

    Create a IstioControlPlane CR yaml locally with your override to install istio, e.g. cni.yaml

    1. apiVersion: install.istio.io/v1alpha2
    2. kind: IstioControlPlane
    3. spec:
    4. cni:
    5. enabled: true
    6. values:
    7. cni:
    8. excludeNamespaces:
    9. - istio-system
    10. - kube-system
    11. - foo_ns
    12. - bar_ns
    13. unvalidatedValues:
    14. cni:
    15. logLevel: info
    1. $ istioctl manifest apply -f cni.yaml

    Hosted Kubernetes settings

    The Istio CNI solution is not ubiquitous. Some platforms, especially hosted Kubernetes environments, do not enable theCNI plugin in the kubelet configuration.The istio-cni plugin is expected to work with any hosted Kubernetes leveraging CNI plugins.The following table shows the required settings for many common Kubernetes environments.

    Hosted Cluster TypeRequired Istio CNI Setting OverridesRequired Platform Setting Overrides
    GKE 1.9+ (see GKE setup below for details)—set values.cni.cniBinDir=/home/kubernetes/binenable network-policy
    IKS (IBM cloud)(none)(none)
    EKS (AWS)(none)(none)
    AKS (Azure)(none)(none)
    Red Hat OpenShift 3.10+(none)(none)
    Red Hat OpenShift 4.2+—set cni.components.cni.namespace=kube-system —set values.cni.cniBinDir=/var/lib/cni/bin —set values.cni.cniConfDir=/var/run/multus/cni/net.d(none)

    GKE setup

    • Refer to the procedure to prepare a GKE cluster for Istio andenable network-policy in your cluster.

    For existing clusters, this redeploys all nodes.

    • Install Istio CNI via Istioctl including the —set cniBinDir=/home/kubernetes/bin option.For example, the following istioctl manifest command sets the cniBinDir value for a GKE cluster:
    1. $ istioctl manifest apply --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 methodthat uses the istio-sidecar-injector configmap created from the installation with the—set cni.enabled=true option. Refer to Istio sidecar injectionfor details about Istio sidecar injection methods.

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

    • Automatic sidecar injection
    • Manual sidecar injection with the istio-sidecar-injector configmap

      • istioctl kube-inject using the configmap directly:
    1. $ istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml --injectConfigMapName istio-sidecar-injector
    2. $ kubectl apply -f deployment-injected.yaml
    • istioctl kube-inject using a file created from the configmap:
    1. $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml
    2. $ istioctl kube-inject -f deployment.yaml -o deployment-injected.yaml --injectConfigFile inject-config.yaml
    3. $ kubectl apply -f deployment-injected.yaml

    Operational details

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

    • Identify Istio user application pods with Istio sidecars requiring traffic redirection
    • 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 theaccompanying Istio proxy sidecar by checking that the pod meets all of the following conditions:

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

    Traffic redirection parameters

    To redirect traffic in the application pod’s network namespace to/from the Istio proxy sidecar, the IstioCNI plugin configures the namespace’s iptables. The following table describes the parameters to theredirect functionality. To override the default values for the parameters, set the correspondingapplication pod annotation key.

    Annotation KeyValuesDefaultDescription
    sidecar.istio.io/injecttrue, falsetrueIndicates whether the Istio proxy sidecar should be injected. If present and false, the Istio CNI plugin doesn’t configure the namespace’s iptables for the pod.
    sidecar.istio.io/statusAnnotation created by Istio’s sidecar injection. If missing, the Istio CNI plugin doesn’t configure the pod namespace’s iptables.
    sidecar.istio.io/interceptionModeREDIRECT, TPROXYREDIRECTThe iptables redirect mode to use.
    traffic.sidecar.istio.io/includeOutboundIPRanges<IPCidr1>,<IPCidr2>,…""Comma separated list of IP ranges in CIDR form to redirect to the sidecar proxy. The default value of "" redirects all traffic.
    traffic.sidecar.istio.io/excludeOutboundIPRanges<IPCidr1>,<IPCidr2>,…Comma separated list of IP ranges in CIDR form to be excluded from redirection. Only applies when includeOutboundIPRanges is "".
    traffic.sidecar.istio.io/includeInboundPorts<port1>,<port2>,…Pod’s list of containerPortsComma separated list of inbound ports for which traffic is to be redirected to the Istio proxy sidecar. The value of "" redirects all ports.
    traffic.sidecar.istio.io/excludeInboundPorts<port1>,<port2>,…Comma separated list of inbound ports to be excluded from redirection to the Istio sidecar proxy. Only valid when includeInboundPorts is "*".
    traffic.sidecar.istio.io/excludeOutboundPorts<port1>,<port2>,…Comma separated list of outbound ports to be excluded from redirection to Envoy.
    traffic.sidecar.istio.io/kubevirtInterfaces<ethX>,<ethY>,…Comma separated list of virtual interfaces whose inbound traffic (from VM) will be treated as outbound.

    Logging

    The Istio CNI plugin runs in the container runtime process space.Due to this, the kubelet process writes the plugin’s log entries into its log.

    Compatibility with application init containers

    The Istio CNI plugin may cause networking connectivity problems for any application initContainers. When using Istio CNI, kubeletstarts 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 or both of the following settings:
    • Set the traffic.sidecar.istio.io/excludeOutboundIPRanges annotation to disable redirecting traffic to anyCIDRs the init containers communicate with.
    • Set the traffic.sidecar.istio.io/excludeOutboundPorts annotation to disable redirecting traffic to thespecific 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 NET_ADMINistio-init container.

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

    The Istio CNI plugin should not interfere with the operations of the base CNI plugin that configures the pod’snetworking setup, although not all CNI plugins have been validated.

    See also

    Customizable Install with Helm

    Install and configure Istio for in-depth evaluation or production use.

    Helm Changes

    Details the Helm chart installation options differences between Istio 1.1 and Istio 1.2.

    Helm Changes

    Details the Helm chart installation options differences between Istio 1.0 and Istio 1.1.

    Helm Changes

    Details the Helm chart installation options differences between Istio 1.2 and Istio 1.3.

    Installation Options (Helm)

    Describes the options available when installing Istio using Helm charts.

    Installing the Sidecar

    Install the Istio sidecar in application pods automatically using the sidecar injector webhook or manually using istioctl CLI.