Inject

The linkerd inject command allows for a quick and reliable setup of the Linkerd Proxy in a Kubernetes Deployment. This page is useful as a reference to help you understand what linkerd inject is doing under the hood, as well as provide a reference for the flags that can be passed at the command line.

If you run the command linkerd inject -h it will provide you with the same information as the table below:

Flag Explanation Example
--api-port The port where the Linkerd controller is running (default 8086). If you changed any of the port settings on linkerd install this flag will be necessary. --api-port=9045
--control-port The proxy port to use for control (default 4190). This is the port the Linkerd Proxy Pod uses communicates with the control plane. If 4190 is a reserved port for your application, it can be changed with this flag. --control-port=5431
-h, --help The command that prints this table out, but on the command line. -h
--image-pull-policy The Docker image pull policy (default "IfNotPresent"). For the injected Linkerd Proxy images (or your own modified variant) choose whether or not you want to have the Kubelet pull the image from the registry Always or Ony If Not Present. --image-pull-policy="Always"
--inbound-port The proxy port to use for inbound traffic (default 4143). This port number is arbitrary, but can be changed if your Pod has that port reserved inbound or outbound already. --inbound-port=1234
--init-image The Linkerd init container image name (default "gcr.io/linkerd-io/proxy-init"). If you have modified (or made private) the Linkerd Proxy Init Container, you will adjust that here. --init-image="quay.io/org/imagename"
-v, --linkerd-version Tag to be used for Linkerd images (default "v18.8.2"). IMPORTANT this version should be the same as your Linkerd control plane version. -v="1.0.0"
--metrics-port The proxy port to serve metrics on (default 4191). This port number is arbitrary, but you will want to update your Prometheus installation to match this port number if you change it. --metrics-port=10234
--outbound-port The proxy port to use for outbound traffic (default 4140). This port number is arbitrary, but can be changed if your Pod has that port reserved inbound or outbound already. --outbound-port=1234
--proxy-bind-timeout The timeout the proxy will use (default "10s"). The amount of time to allow the proxy to bind to the Pod's network interface and begin receiving traffic on behalf of your deployment. If you have especially long start time for a container, you may consider adjusting this. This string will eventually be converted to a Rust Duration, so you'll want to keep this this of the form "[0-9]*s" --proxy-bind-timeout="30s"
--proxy-image The linkerd proxy container image name (default "gcr.io/linkerd-io/proxy"). If you have modified (or made private) the Linkerd Proxy Init Container, you will adjust that here. --proxy-image="quay.io/org/imagename"
--proxy-log-level The log level for the proxy (default "warn,linkerd2_proxy=info"). The first value is the log level for the Init Container, and the second is the level for the Proxy Container. --proxy-log-level="info,linkerd2_proxy=debug"
--proxy-uid Run the proxy under this user ID (default 2102) --proxy-uid=123
--proxy-cpu Set the amount of CPU units that the sidecar requests --proxy-cpu=10m
--proxy-memory Set the amount of Memory units that the sidecar requests --proxy-memory=50Mi
--registry Docker registry to pull images from (default "gcr.io/linkerd-io") --registry="quay.io/ygrene
--skip-inbound-ports Ports that should skip the proxy and send directly to the application (default []). IMPORTANT! If there is a port you do not want Linkerd proxying (for example SMTP port 25) you will need to put it in this list. --skip-inbound-ports=25,26,27
--skip-outbound-ports Outbound ports that should skip the proxy (default []). Similarly to the above, if there are outbound ports you don't want leaving the pod from the --outbound-port (such as MySQL,) they need to be listed here. --skip-outbound-ports=25,3306,5432
--tls Enable TLS; valid settings: "optional". Whether or not you want Linkerd Proxy to attempt an mTLS session between two Pods in the mesh. The only option that is valid is "optional". --tls="optional"
--api-addr Override the kubeconfig and communicate directly with the control plane at host:port (mostly for testing). --api-addr="127.0.0.1:80"
--kubeconfig Path to the kubeconfig file to use for CLI requests. The local path for your Kubernetes config manifest. --kubeconfig="~/.kube/config"
-l, --linkerd-namespace Namespace in which Linkerd is installed (default "linkerd"). If you modified the linkerd install command and adjusted the Kubernetes Namespace it was deployed into, you'll want to adjust it here. -l="default"
--verbose Turn on debug logging. Log all the things. (Especially those things that linkerd inject does.) --verbose

What linkerd inject Is Doing

linkerd inject is modifying the Kubernetes Deployment manifest that is being passed to it either as a file or as a stream to its stdin. It is adding two things:

  1. An Init Container (supported as of Kubernetes version 1.6 or greater)

  2. A Linkerd Proxy sidecar container into each Pod belonging to your Deployment

The Init Container is responsible for pulling configuration (such as certificates) from the Kubernetes API/Linkerd Controller, as well as providing configuration to the Linkerd Proxy container for its runtime.

Example Deployment

Let's say for example you have the following deployment saved as deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-deployment
      env: default
  template:
    metadata:
      labels:
        app: example-deployment
        env: default
    spec:
      containers:
      - name: app
        image: quay.io/ygrene/hello-docker
        ports:
        - containerPort: 3000

Now, we can run the linkerd inject command as follows:

linkerd inject \
  --proxy-log-level="debug" \
  --skip-outbound-ports=3306 \
  deployment.yaml > deployment_with_linkerd.yaml

The output of that file should look like the following:

apiVersion: apps/v1
kind: Deployment
metadata:
  creationTimestamp: null
  name: example-deployment
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example-deployment
      env: default
  strategy: {}
  template:
    metadata:
      annotations:
        linkerd.io/created-by: linkerd/cli v18.8.2
        linkerd.io/proxy-version: v18.8.2
      creationTimestamp: null
      labels:
        app: example-deployment
        env: default
        linkerd.io/control-plane-ns: linkerd
        linkerd.io/proxy-deployment: example-deployment
    spec:
      containers:
      - image: quay.io/ygrene/hello-docker
        name: app
        ports:
        - containerPort: 3000
        resources: {}
      - env:
        - name: LINKERD2_PROXY_LOG
          value: debug
        - name: LINKERD2_PROXY_BIND_TIMEOUT
          value: 10s
        - name: LINKERD2_PROXY_CONTROL_URL
          value: tcp://proxy-api.linkerd.svc.cluster.local:8086
        - name: LINKERD2_PROXY_CONTROL_LISTENER
          value: tcp://0.0.0.0:4190
        - name: LINKERD2_PROXY_METRICS_LISTENER
          value: tcp://0.0.0.0:4191
        - name: LINKERD2_PROXY_PRIVATE_LISTENER
          value: tcp://127.0.0.1:4140
        - name: LINKERD2_PROXY_PUBLIC_LISTENER
          value: tcp://0.0.0.0:4143
        - name: LINKERD2_PROXY_POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        image: gcr.io/linkerd-io/proxy:v18.8.2
        imagePullPolicy: IfNotPresent
        name: linkerd-proxy
        ports:
        - containerPort: 4143
          name: linkerd-proxy
        - containerPort: 4191
          name: linkerd-metrics
        resources: {}
        securityContext:
          runAsUser: 2102
        terminationMessagePolicy: FallbackToLogsOnError
      initContainers:
      - args:
        - --incoming-proxy-port
        - "4143"
        - --outgoing-proxy-port
        - "4140"
        - --proxy-uid
        - "2102"
        - --inbound-ports-to-ignore
        - 4190,4191
        - --outbound-ports-to-ignore
        - "3306"
        image: gcr.io/linkerd-io/proxy-init:v18.8.2
        imagePullPolicy: IfNotPresent
        name: linkerd-init
        resources: {}
        securityContext:
          capabilities:
            add:
            - NET_ADMIN
          privileged: false
        terminationMessagePolicy: FallbackToLogsOnError
status: {}
---

Note here how the initContainer and linkerd-proxy sidecar are added to the manifest with configuration we passed as command line flags.