Automatic Proxy Injection
Linkerd automatically adds the data plane proxy to pods when the
linkerd.io/inject: enabled
annotation is present on a namespace or any
workloads, such as deployments or pods. This is known as “proxy injection”.
See Adding Your Service for a walkthrough of how to use this feature in practice.
Note
Details
Proxy injection is implemented as a Kubernetes admission
webhook.
This means that the proxies are added to pods within the Kubernetes cluster
itself, regardless of whether the pods are created by kubectl
, a CI/CD
system, or any other system.
For each pod, two containers are injected:
linkerd-init
, a Kubernetes Init Container that configuresiptables
to automatically forward all incoming and outgoing TCP traffic through the proxy. (Note that this container is not injected if the Linkerd CNI Plugin has been enabled.)linkerd-proxy
, the Linkerd data plane proxy itself.
Note that simply adding the annotation to a resource with pre-existing pods
will not automatically inject those pods. You will need to update the pods
(e.g. with kubectl rollout restart
etc.) for them to be injected. This is
because Kubernetes does not call the webhook until it needs to update the
underlying resources.
Exclusions
At install time, Kubernetes is configured to avoid calling Linkerd’s proxy
injector for resources in the kube-system
and cert-manager
namespaces. This
is to prevent injection on components that are themselves required for Linkerd
to function.
The injector will not run on components in these namespaces, regardless of any
linkerd.io/inject
annotations.
Overriding injection
Automatic injection can be disabled for a pod or deployment for which it would
otherwise be enabled, by adding the linkerd.io/inject: disabled
annotation.
Manual injection
The linkerd inject
CLI command is a text
transform that, by default, simply adds the inject annotation to a given
Kubernetes manifest.
Alternatively, this command can also perform the full injection purely on the
client side with the --manual
flag. This was the default behavior prior to
Linkerd 2.4; however, having injection to the cluster side makes it easier to
ensure that the data plane is always present and configured correctly,
regardless of how pods are deployed.
See the linkerd inject
reference for more
information.