Installing the Sidecar

    The following sections describe twoways of injecting the Istio sidecar into a pod: manually using the command or automatically using the Istio sidecar injector.

    Manual injection directly modifies configuration, like deployments, and injects the proxy configuration into it.

    Automatic injection injects at pod creation time using an admission controller.

    Injection occurs by applying a template defined in the istio-sidecar-injector ConfigMap.

    To manually inject a deployment, use :

    Zip

    By default, this will use the in-cluster configuration. Alternatively, injection can be done using local copies of the configuration.

    1. $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml
    2. $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.values}' > inject-values.yaml
    3. $ kubectl -n istio-system get configmap istio -o=jsonpath='{.data.mesh}' > mesh-config.yaml

    Run kube-inject over the input file and deploy.

    1. $ istioctl kube-inject \
    2.     --injectConfigFile inject-config.yaml \
    3.     --meshConfigFile mesh-config.yaml \
    4.     --valuesFile inject-values.yaml \
    5.     --filename @samples/sleep/sleep.yaml@ \
    6.     | kubectl apply -f -

    Verify that the sidecar has been injected into the sleep pod with 2/2 under the READY column.

    1. $ kubectl get pod  -l app=sleep
    2. NAME                     READY   STATUS    RESTARTS   AGE
    3. sleep-64c6f57bc8-f5n4x   2/2     Running   0          24s

    Automatic sidecar injection

    Sidecars can be automatically added to applicable Kubernetes pods using a provided by Istio.

    While admission controllers are enabled by default, some Kubernetes distributions may disable them. If this is the case, follow the instructions to turn on admission controllers.

    When the injection webhook is enabled, any new pods that are created will automatically have a sidecar added to them.

    Note that unlike manual injection, automatic injection occurs at the pod-level. You won’t see any change to the deployment itself. Instead you’ll want to check individual pods (via kubectl describe) to see the injected proxy.

    Disabling or updating the webhook

    The sidecar injecting webhook is enabled by default. If you wish to disable the webhook, you canuse Helm to set option sidecarInjectorWebhook.enabled to false.

    There are also a that can be configured.

    Deploying an app

    Deploy sleep app. Verify both deployment and pod have a single container.

    1. $ kubectl apply -f @samples/sleep/sleep.yaml@
    2. $ kubectl get deployment -o wide
    3. NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE       CONTAINERS   IMAGES       SELECTOR
    4. sleep     1         1         1            1           12m       sleep        tutum/curl   app=sleep
    1. $ kubectl get pod
    2. NAME                     READY     STATUS        RESTARTS   AGE
    3. sleep-776b7bcdcd-7hpnk   1/1       Running       0          4

    Injection occurs at pod creation time. Kill the running pod and verify a new pod is created with the injected sidecar. The original pod has 1/1 READY containers and the pod with injected sidecar has 2/2 READY containers.

    1. $ kubectl delete pod -l app=sleep
    2. $ kubectl get pod -l app=sleep
    3. NAME                     READY     STATUS        RESTARTS   AGE
    4. sleep-776b7bcdcd-7hpnk   1/1       Terminating   0          1m
    5. sleep-776b7bcdcd-bhn9m   2/2       Running       0          7s

    View detailed state of the injected pod. You should see the injected istio-proxy container and corresponding volumes. Be sure to substitute the correct name for the Running pod below.

    1. $ kubectl describe pod -l app=sleep

    Disable injection for the default namespace and verify new pods are created without the sidecar.

    1. $ kubectl label namespace default istio-injection-
    2. $ kubectl get pod
    3. NAME                     READY     STATUS        RESTARTS   AGE
    4. sleep-776b7bcdcd-bhn9m   2/2       Terminating   0          2m
    5. sleep-776b7bcdcd-gmvnr   1/1       Running       0          2s

    Understanding what happened

    When Kubernetes invokes the webhook, the configuration is applied. The default configuration injects the sidecar intopods in any namespace with the istio-injection=enabled label. Theistio-sidecar-injector configuration map specifies the configuration for theinjected sidecar. To change how namespaces are selected for injection, you canedit the MutatingWebhookConfiguration with the following command:

    You should restart the sidecar injector pod(s) after modifyingthe MutatingWebhookConfiguration.

    For example, you can modify the MutatingWebhookConfiguration to always injectthe sidecar into every namespace, unless a label is set. Editing thisconfiguration is an advanced operation. Refer to the Kubernetes documentationfor the MutatingWebhookConfiguration APIfor more information.

    policy

    disabled - The sidecar injector will not inject the sidecar intopods by default. Add the sidecar.istio.io/inject annotation withvalue true to the pod template spec to override the default and enable injection.

    enabled - The sidecar injector will inject the sidecar into pods bydefault. Add the sidecar.istio.io/inject annotation withvalue false to the pod template spec to override the default and disable injection.

    The following example uses the sidecar.istio.io/inject annotation to disable sidecar injection.

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: ignored
    5. spec:
    6.   template:
    7.     metadata:
    8.       annotations:
    9.         sidecar.istio.io/inject: "false"
    10.     spec:
    11.       containers:
    12.       - name: ignored
    13.         image: tutum/curl
    14.         command: ["/bin/sleep","infinity"]
    template

    The sidecar injection template uses which,when parsed and executed, is decoded to the followingstruct containing the list of containers and volumes to inject into the pod.

    The template is applied to the following data structure at runtime.

    1. type SidecarTemplateData struct {
    2.     DeploymentMeta *metav1.ObjectMeta
    3.     ObjectMeta     *metav1.ObjectMeta
    4.     Spec           *corev1.PodSpec
    5.     ProxyConfig    *meshconfig.ProxyConfig  // Defined by https://istio.io/docs/reference/config/service-mesh.html#proxyconfig
    6.     MeshConfig     *meshconfig.MeshConfig   // Defined by https://istio.io/docs/reference/config/service-mesh.html#meshconfig
    7. }

    ObjectMeta and Spec are from the pod. ProxyConfig and MeshConfigare from the istio ConfigMap in the istio-system namespace. Templates can conditionallydefine injected containers and volumes with this data.

    For example, the following template

    1. containers:
    2. - name: istio-proxy
    3.   image: istio.io/proxy:0.5.0
    4.   args:
    5.   - proxy
    6.   - sidecar
    7.   - --configPath
    8.   - {{ .ProxyConfig.ConfigPath }}
    9.   - --binaryPath
    10.   - {{ .ProxyConfig.BinaryPath }}
    12.   - {{ index .ObjectMeta.Labels "app" }}
    13.   {{ else -}}
    14.   - "istio-proxy"
    15.   {{ end -}}

    expands to

    1. containers:
    2. - name: istio-proxy
    3.   image: istio.io/proxy:0.5.0
    4.   args:
    5.   - proxy
    6.   - sidecar
    7.   - --configPath
    8.   - /etc/istio/proxy
    9.   - --binaryPath
    10.   - /usr/local/bin/envoy
    11.   - --serviceCluster
    12.   - sleep

    when applied over a pod defined by the pod template spec in samples/sleep/sleep.yaml

    More control: adding exceptions

    There are cases where users do not have control of the pod creation, for instance, when they are created by someone else. Therefore they are unable to add the annotation sidecar.istio.io/inject in the pod, to explicitly instruct Istio whether to install the sidecar or not.

    Think of auxiliary pods that might be created as an intermediate step while deploying an application. OpenShift Builds, for example, creates such pods for building the source code of an application. Once the binary artifact is built, the application pod is ready to run and the auxiliary pods are discarded. Those intermediate pods should not get an Istio sidecar, even if the policy is set to enabled and the namespace is properly labeled to get automatic injection.

    For such cases you can instruct Istio to not inject the sidecar on those pods, based on labels that are present in those pods. You can do this by editing the istio-sidecar-injector ConfigMap and adding the entry neverInjectSelector. It is an array of Kubernetes label selectors. They are OR'd, stopping at the first match. See an example:

    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: istio-sidecar-injector
    5. data:
    6.   config: |-
    7.     policy: enabled
    8.     neverInjectSelector:
    9.       - matchExpressions:
    10.         - {key: openshift.io/build.name, operator: Exists}
    11.       - matchExpressions:
    12.         - {key: openshift.io/deployer-pod-for.name, operator: Exists}
    13.     template: |-
    14.       initContainers:
    15. ...

    For completeness, you can also use a field called alwaysInjectSelector, with similar syntax, which will always inject the sidecar on pods that match that label selector, regardless of the global policy.

    The label selector approach gives a lot of flexibility on how to express those exceptions. Take a look at to see what you can do with them!

    It’s worth noting that annotations in the pods have higher precedence than the label selectors. If a pod is annotated with sidecar.istio.io/inject: "true/false" then it will be honored. So, the order of evaluation is:

    Pod Annotations → NeverInjectSelector → AlwaysInjectSelector → Default Policy

    Uninstalling the automatic sidecar injector

    1. $ kubectl delete mutatingwebhookconfiguration istio-sidecar-injector
    2. $ kubectl -n istio-system delete service istio-sidecar-injector
    3. $ kubectl -n istio-system delete deployment istio-sidecar-injector
    4. $ kubectl -n istio-system delete serviceaccount istio-sidecar-injector-service-account
    6. $ kubectl delete clusterrolebinding istio-sidecar-injector-admin-role-binding-istio-system

    The above command will not remove the injected sidecars from Pods. Arolling update or simply deleting the pods and forcing the deploymentto create them is required.

    Optionally, it may also be desirable to clean-up other resources thatwere modified in this task.

    See also

    Pods and Services

    Prepare your Kubernetes pods and services to run in an Istio-enabled cluster.

    De-mystify how Istio manages to plugin its data-plane components into an existing deployment.

    Install Istio with the Istio CNI plugin

    Install and use Istio with the Istio CNI plugin, allowing operators to deploy services with lower privilege.

    Provision and manage DNS certificates in Istio.

    Secure Webhook Management

    A more secure way to manage Istio webhooks.

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