Istio sidecar injection: enabling automatic injection, adding exceptions and debugging

Hey folks. Today let’s talk a little bit about Istio sidecar injection in Kubernetes.

Istio in Kubernetes works using a sidecar deployment model, where a helper container (sidecar) gets attached to your main container (service) within a single Pod. By doing that, your service and the sidecar container share the same network, and can be seen like two processes in a single host. Thus Istio can intercept all network calls to and from your main container and do its magic to improve service-to-service communication.

This sidecar container, named istio-proxy can be injected into your service Pod in two ways: manually and automatically. Even this manual technique is not 100% done by hand. Let’s see.

Manual injection

Istio ships with a tool called istioctl. Yeah, it seems it’s inspired in some other loved tool :). One of its feature is the ability to inject the istio-proxy sidecar into your service Pod. Let’s use it, using a simple busybox pod as an example:

$ cat busybox.yaml 
apiVersion: v1
kind: Pod
  name: busybox-test
  - name: busybox-container
    image: busybox
    command: ['sh', '-c', 'echo Hello Kubernetes! && sleep infinity']

$ istioctl kube-inject -f busybox.yaml > busybox-injected.yaml

[jwendell@jw-laptop ~]$ cat busybox-injected.yaml 
apiVersion: v1
kind: Pod
  name: busybox-test
  - command:
    - sh
    - -c
    - echo Hello Kubernetes! && sleep infinity
    image: busybox
    name: busybox-container

  - image:
    imagePullPolicy: IfNotPresent
    name: istio-proxy
      - proxy
      - sidecar

As you can see above, that command generated another yaml file, similar to the input (busybox pod) but with the sidecar (istio-proxy) added into the pod. So, in some way this is not a 100% manual job, right? It saves us a bunch of typing. You are ready to apply this modified yaml into your kubernetes cluster:

$ kubectl apply -f busybox-injected.yaml
# or, if you don't want to have an intermediate file, apply directly using the original file:
$ kubectl apply -f <(istioctl kube-inject -f busybox.yaml)

One natural question that might come is: Where does that data come from? How does it know that the sidecar image is The answer is simple: All that data comes from a ConfigMap that lives in the Istio control plane, on the istio-system namespace:

$ kubectl -n istio-system describe configmap istio-sidecar-injector
Name:         istio-sidecar-injector
Namespace:    istio-system

policy: enabled
template: |-
  - name: istio-init
    image: ""

You can edit this ConfigMap with the values you want to inject into your pods. As you can see, that is mostly a template that will get appended into your pod definition. If you want to use other image for the istio-proxy container, use other tag, or wish to tweak anything that will get injected, this is the stuff you need to edit. Remember that this ConfigMap is used for injection in all your pods in the service mesh. Be careful 🙂

Because istioctl reads a ConfigMap in order to know what to inject, that means you need to have access to a working Kubernetes cluster with Istio properly installed. If for some reason you don’t have such access, you can still use istioctl, by supplying a local configuration file:

# run this previosly, with proper access to the k8s cluster
$ kubectl -n istio-system get configmap istio-sidecar-injector -o=jsonpath='{.data.config}' > inject-config.yaml
# feel free to modify that file, and you can run at any point later:
$ istioctl kube-inject --injectConfigFile inject-config.yaml ...

Automatic injection

The other way of having istio-proxy injected into your pods is by telling Istio to automatically do that for you. In fact, this is enabled by default for all namespaces with the label istio-injection=enabled. This means that, if a namespace has such label, all pods within it will get the istio-proxy sidecar automatically. You don’t need to run istioctl or do anything with your yaml files!

The way it works is quite simple: It makes use of a Kubernetes feature called MutatingWebhook which consists in Kubernetes notifying Istio whenever a new pod is about to be created, and giving Istio the chance to modify the pod spec on the fly, just before actually creating that pod. Thus, Istio injects the istio-proxy sidecar using the template found in that ConfigMap we saw above.

Sounds nice, right?

You might be asking yourself: Hey, this is too intrusive! Yep, it might be, all depends on your needs. This automatic injection is very flexible though:

  • In the istio-sidecar-injector ConfigMap there is a boolean flag indicating whether this automatic injection is enabled or not.
  • Only namespaces labelled accordingly will get automatic injection. You can selectively choose which namespaces will have automatic injection.
  • Also, you can tweak this label, changing it or even removing that filter (meaning injection will happen automatically in all namespaces! Be careful!) by editing the MutatingWebhookConfiguration: kubectl -n istio-system edit MutatingWebhookConfiguration istio-sidecar-injector. Look for the namespaceSelector field.
  • You can prevent the injection to happen in selective pods. If a pod has the annotation "false" then Istio will not inject the sidecar in it.
  • You can invert the logic if you are more conservative. Disable the automatic injection for everyone and enable it only for selected pods. For that you just need to set the policy to false (kubectl -n istio-system edit configmap istio-sidecar-injector) and annotate the pods you want to get injected with "true"

I want more flexibility!

Here is a use case where the flexibility above was not enough:

For those of you who are not familiar with Openshift (Red Hat Kubernetes distribution), it has a feature called source-to-image – s2i, which magically creates container images based on source code. You supply a git repository (works with many programming languages!) as the input and gets a container image, running on Openshift as the result.

It’s an awesome feature! I’ll not get into details here, I’m just going to tell you what we need to know right now: In order to do that, Openshift creates one or more intermediate, auxiliary pods to build the source code. When build finishes, the binary artifacts goes to the resulting container image, ready to run on Openshift, and those auxiliary pods are then discarded.

If we enable automatic injection in a given namespace and use Openshift’s s2i feature, this means that all pods will get the sidecar injected. Even those builder (intermediate, auxiliary) pods! Worse, as they are not under our control (they are created by Openshift, not by us), we cannot annotate them to not get the sidecar injected. Builds do not behave well with the sidecar injected, so we don’t want they to be automatically injected. What to do now?

Well, a possible solution is to take the conservative approach explained in the last bullet above: Disabling the automatic injection for everyone and enable it only for selected pods. That works, but require you to actively annotate the pods you want the automatic injection to happen.

Or… There’s a new solution for this problem:

The new solution

Starting with 1.1.0, Istio automatic injection has a way to add exceptions based on labels, that mean: Do not inject the sidecar in pods that match those labels, even if the policy is true and this namespace is marked to have automatic injection. You can add those exceptions in the istio-sidecar-injector ConfigMap:

$ kubectl -n istio-system describe configmap istio-sidecar-injector
apiVersion: v1
kind: ConfigMap
  name: istio-sidecar-injector
  config: |-
    policy: enabled
      - matchExpressions:
        - {key:, operator: Exists}
      - matchExpressions:
        - {key:, operator: Exists}
    template: |-

You can see above a field neverInjectSelector. It’s an array of Kubernetes label selectors. They are OR‘d, stopping at the first match. The above statement means: Never inject on pods that have the label or – the values of the labels don’t matter, we are just checking if the keys exist. With this rule added, our Openshift s2i use case is covered, meaning auxiliary pods will not have sidecars injected (because s2i auxiliary pods do contain those labels).

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

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

It’s worth to note that annotations in the pods still have the preference. If a pod is annotated with "true/false" then it will be honored. So, the order of evaluation is:

Pod Annotations → NeverInjectSelector → AlwaysInjectSelector → Namespace Policy

As this {Never,Always}InjectSelector is a recent addition, I still have to update the docs to mention it, but for all other stuff, for more information and examples check out the official documentation.

Why is my pod [not] getting injected?

This is a very common question. You have followed all the instructions (like labeling the namespace with istio-injection=enabled) and your pods are not receiving the automatic injection.

Or quite the opposite, you annotated your pod with "false" and it is getting injected. Why?

One thing you can do in order to find out what’s going on is to look at the sidecar-injector pod logs:

$ pod=$(kubectl -n istio-system get pods -l istio=sidecar-injector -o jsonpath='{.items[0]}')
$ kubectl -n istio-system logs -f $pod

Then you can create your pods and watch that log for any output. For a more verbose log output – trust me, it’s really useful – then we should edit the sidecar-injector deployment and append the argument --log_output_level=default:debug into the sidecar-injector container executable:

$ kubectl -n istio-system edit deployment istio-sidecar-injector
      - args:
        - --caCertFile=/etc/istio/certs/root-cert.pem
        - --tlsCertFile=/etc/istio/certs/cert-chain.pem
        - --tlsKeyFile=/etc/istio/certs/key.pem
        - --injectConfig=/etc/istio/inject/config
        - --meshConfig=/etc/istio/config/mesh
        - --healthCheckInterval=2s
        - --healthCheckFile=/health
        - --log_output_level=default:debug
        imagePullPolicy: IfNotPresent

Save it and exit your editor. Now Kubernetes is redeploying the sidecar-injector pod and the debug flag must be in effect. Wait a few seconds for the pod to be alive then you can watch the logs again:

$ pod=$(kubectl -n istio-system get pods -l istio=sidecar-injector -o jsonpath='{.items[0]}')
$ kubectl -n istio-system logs -f $pod

If even with the debug output enabled you did not see anything relevant in your logs, that means that the sidecar-injector pod is not even being notified about the pod creation. It’s not being invoked to do the automatic injection. This can be due to a misconfiguration regarding the namespace label. Check if the namespace is labeled according with what it’s in the MutatingWebhookConfiguration. By default the namespace should have the label istio-injection=enabled. Verify if this has changed by running kubectl -n istio-system edit MutatingWebhookConfiguration istio-sidecar-injector and checking the field namespaceSelector.

When you are finished with your debug session, you can edit the deployment again and remove that debug argument.

That’s it. Hope that helps. Feel free to ask or comment anything, here or on twitter! See you soon!

Leave a Reply

Your email address will not be published.