Kubernetes sidecar injection service
Branch: master
Clone or download
Latest commit 43a2c09 Feb 5, 2019



Uses MutatingAdmissionWebhook in Kubernetes to inject sidecars into new deployments at resource creation time

GitHub release Travis (.org) Docker Automated build Docker Build Status MicroBadger Size Docker Pulls Docker Stars Godoc

What is this?

At Tumblr, we run some containers that have complicated sidecar setups. A kubernetes pod may run 5+ other containers, with some associated volumes and environment variables. It became clear quickly that keeping these sidecars in line would become an operational hassle; making sure every service uses the correct version of each dependency, updating global environment variable sets as configurations in our DCs change, etc.

To help solve this, we wrote the k8s-sidecar-injector. It is a small service that runs in each Kubernetes cluster, and listens to the Kubernetes API via webhooks. For each pod creation, the injector gets a (mutating admission) webhook, asking whether or not to allow the pod launch, and if allowed, what changes we would like to make to it. For pods that have special annotations on them (injector.tumblr.com/request=some-sidecar-name), we rewrite the pod configuration to include the containers, volumes, and environment variables defined in the sidecar some-sidecar-name's configuration.

This enabled us to keep sane, centralized configuration for oft-used, but infrequently cared about configuration for our sidecars.


See /docs/configuration.md to get started with setting up your sidecar injector's configurations.


See /docs/deployment.md to see what a sample deployment may look like for you!

How it works

  1. A pod is created. It has annotation injector.tumblr.com/request=logger-v1
  2. K8s webhooks out to this service, asking whether to allow this pod creation, and how to mutate it
  3. If the pod is annotated with injector.tumblr.com/status=injected: Do nothing! Return "allowed" to pod creation
  4. Pull the "logger-v1" sidecar config, patch the resource, and return it to k8s
  5. Pod will launch in k8s with the modified configuration

A crappy ASCII diagram will help :)

     +------------------------------+          +----------------+ |                 |
     |                              |          |                | |  Sidecar        |
     |   MutatingAdmissionWebhook   |          |   Sidecar      | |  configuration  |
     |                              |          |   ConfigMaps   | |  files on disk  |
     +------------+-----------------+          |                | |                 |
                  |                            +--------+-------+ +------+----------+
discover injector |                                     |                |
endoints          |                    watch ConfigMaps |                | load from disk
                  |                                     |                |
          +-------v--------+    pod launch          +---v----------------v-----+
          |                +------------------------>                          |
          |   Kubernetes   |                        |   k8s-sidecar-injector   |
          |   API Server   <------------------------+                          |
          |                |    mutated pod spec    +--------------------------+


The image is build and published on the Hub at https://hub.docker.com/r/tumblr/k8s-sidecar-injector/. See /docs/deployment.md for how to run this in Kubernetes.

By hand

This needs some special configuration surrounding the TLS certs, but if you have already read docs/configuration.md, you can run this manually with:

$ ./bin/k8s-sidecar-injector --tls-port=9000 --config-directory=conf/ --tls-cert-file="${TLS_CERT_FILE}" --tls-key-file="${TLS_KEY_FILE}"

NOTE: this is not a supported method of running in production. You are highly encouraged to read docs/deployment.md to deploy this to Kubernetes in The Supported Way.


See hacking.md


Apache 2.0

Copyright 2019, Tumblr, Inc.