istio.io/content/en/docs/setup/additional-setup/sidecar-injection/index.md

title	description	weight	keywords	aliases	owner	test
Installing the Sidecar	Install the Istio sidecar in application pods automatically using the sidecar injector webhook or manually using istioctl CLI.	45	kubernetes sidecar sidecar-injection	/docs/setup/kubernetes/automatic-sidecar-inject.html /docs/setup/kubernetes/sidecar-injection/ /docs/setup/kubernetes/additional-setup/sidecar-injection/	istio/wg-environments-maintainers	no

Injection

In order to take advantage of all of Istio's features, pods in the mesh must be running an Istio sidecar proxy.

The following sections describe two ways of injecting the Istio sidecar into a pod: manually using the istioctl command or by enabling automatic Istio sidecar injection in the pod's namespace.

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

When enabled in a pod's namespace, automatic injection injects the proxy configuration at pod creation time using an admission controller.

If you are not sure which one to use, automatic injection is recommended.

Manual sidecar injection

To manually inject a deployment, use istioctl kube-inject:

{{< text bash >}} $ istioctl kube-inject -f @samples/sleep/sleep.yaml@ | kubectl apply -f - serviceaccount/sleep created service/sleep created deployment.apps/sleep created {{< /text >}}

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

{{< text bash >}} $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml $ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.values}' > inject-values.yaml $ kubectl -n istio-system get configmap istio -o=jsonpath='{.data.mesh}' > mesh-config.yaml {{< /text >}}

Run kube-inject over the input file and deploy.

{{< text bash >}} $ istioctl kube-inject
--injectConfigFile inject-config.yaml
--meshConfigFile mesh-config.yaml
--valuesFile inject-values.yaml
--filename @samples/sleep/sleep.yaml@
| kubectl apply -f - serviceaccount/sleep created service/sleep created deployment.apps/sleep created {{< /text >}}

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

{{< text bash >}} $ kubectl get pod -l app=sleep NAME READY STATUS RESTARTS AGE sleep-64c6f57bc8-f5n4x 2/2 Running 0 24s {{< /text >}}

Automatic sidecar injection

Sidecars can be automatically added to applicable Kubernetes pods using a mutating webhook admission controller provided by Istio.

{{< tip >}} 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. {{< /tip >}}

When you set the istio-injection=enabled label on a namespace and the injection webhook is enabled, any new pods that are created in that namespace 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.

Deploying an app

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

{{< text bash >}} $ kubectl apply -f @samples/sleep/sleep.yaml@ $ kubectl get deployment -o wide NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR sleep 1/1 1 1 12s sleep curlimages/curl app=sleep {{< /text >}}

{{< text bash >}} $ kubectl get pod NAME READY STATUS RESTARTS AGE sleep-8f795f47d-hdcgs 1/1 Running 0 42s {{< /text >}}

Label the default namespace with istio-injection=enabled

{{< text bash >}} $ kubectl label namespace default istio-injection=enabled --overwrite $ kubectl get namespace -L istio-injection NAME STATUS AGE ISTIO-INJECTION default Active 5m9s enabled istio-system Active 4m58s disabled kube-node-lease Active 5m10s kube-public Active 5m10s kube-system Active 5m10s local-path-storage Active 5m7s {{< /text >}}

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.

{{< text bash >}} $ kubectl delete pod -l app=sleep $ kubectl get pod -l app=sleep pod "sleep-776b7bcdcd-7hpnk" deleted NAME READY STATUS RESTARTS AGE sleep-776b7bcdcd-7hpnk 1/1 Terminating 0 1m sleep-776b7bcdcd-bhn9m 2/2 Running 0 7s {{< /text >}}

View detailed state of the injected pod. You should see the injected istio-proxy container and corresponding volumes.

{{< text bash >}} $ kubectl describe pod -l app=sleep ... Events: Type Reason Age From Message

---

... Normal Created 11s kubelet Created container istio-init Normal Started 11s kubelet Started container istio-init ... Normal Created 10s kubelet Created container sleep Normal Started 10s kubelet Started container sleep ... Normal Created 9s kubelet Created container istio-proxy Normal Started 8s kubelet Started container istio-proxy {{< /text >}}

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

{{< text bash >}} $ kubectl label namespace default istio-injection- $ kubectl delete pod -l app=sleep $ kubectl get pod namespace/default labeled pod "sleep-776b7bcdcd-bhn9m" deleted NAME READY STATUS RESTARTS AGE sleep-776b7bcdcd-bhn9m 2/2 Terminating 0 2m sleep-776b7bcdcd-gmvnr 1/1 Running 0 2s {{< /text >}}

Controlling the injection policy

In the above examples, you enabled and disabled injection at the namespace level. Injection can also be controlled on a per-pod basis, by configuring the sidecar.istio.io/inject label on a pod:

Resource	Label	Enabled value	Disabled value
Namespace	istio-injection	enabled	disabled
Pod	sidecar.istio.io/inject	"true"	"false"

The injector is configured with the following logic:

1. If either label is disabled, the pod is not injected
2. If either label is enabled, the pod is injected
3. If neither label is set, the pod is injected if .values.sidecarInjectorWebhook.enableNamespacesByDefault is enabled. This is not enabled by default, so generally this means the pod is not injected.

Customizing injection

Generally, pod are injected based on the sidecar injection template, configured in the istio-sidecar-injector configmap. Per-pod configuration is available to override these options on individual pods. This is done by adding an istio-proxy container to your pod. The sidecar injection will treat any configuration defined here as an override to the default injection template.

Care should be taken when customizing these settings, as this allows complete customization of the resulting Pod, including making changes that cause the sidecar container to not function properly.

For example, the following configuration customizes a variety of settings, including lowering the CPU requests, adding a volume mount, and adding a preStop hook:

{{< text yaml >}} apiVersion: v1 kind: Pod metadata: name: example spec: containers:

• name: hello image: alpine
• name: istio-proxy image: auto resources: requests: cpu: "100m" volumeMounts:
  • mountPath: /etc/certs name: certs lifecycle: preStop: exec: command: ["sleep", "10"] volumes:
• name: certs secret: secretName: istio-certs {{< /text >}}

In general, any field in a pod can be set. However, care must be taken for certain fields:

• Kubernetes requires the image field to be set before the injection has run. While you can set a specific image to override the default one, it is recommended to set the image to auto which will cause the sidecar injector to automatically select the image to use.
• Some fields in Pod are dependent on related settings. For example, CPU request must be less than CPU limit. If both fields are not configured together, the pod may fail to start.

Additionally, certain fields are configurable by annotations on the pod, although it is recommend to use the above approach to customizing settings.

Custom templates [experimental]

{{< warning >}} This feature is experimental and subject to change, or removal, at any time. {{< /warning >}}

Completely custom templates can also be defined at installation time. For example, to define a custom template that injects the GREETING environment variable into the istio-proxy container:

{{< text yaml >}} apiVersion: operator.istio.io/v1alpha1 kind: IstioOperator metadata: name: istio spec: values: sidecarInjectorWebhook: templates: custom: | spec: containers: - name: istio-proxy env: - name: GREETING value: hello-world {{< /text >}}

Pods will, by default, use the sidecar injection template, which is automatically created. This can be overridden by the inject.istio.io/templates annotation. For example, to apply the default template and our customization, you can set inject.istio.io/templates=sidecar,custom.