Proxy Configuration

Linkerd provides a set of annotations that can be used to override the data plane proxy’s configuration. This is useful for overriding the default configurations of auto-injected proxies.

The following is the list of supported annotations:

AnnotationDescription
config.alpha.linkerd.io/proxy-wait-before-exit-secondsThe proxy sidecar will stay alive for at least the given period before receiving SIGTERM signal from Kubernetes but no longer than pod’s terminationGracePeriodSeconds. If not provided, it will be defaulted to 0
config.linkerd.io/admin-portProxy port to serve metrics on
config.linkerd.io/control-portProxy port to use for control
config.linkerd.io/debug-imageLinkerd debug container image name
config.linkerd.io/debug-image-pull-policyDocker image pull policy for debug image
config.linkerd.io/debug-image-versionLinkerd debug container image version
config.linkerd.io/disable-identityDisables resources from participating in TLS identity
config.linkerd.io/enable-debug-sidecarInject a debug sidecar for data plane debugging
config.linkerd.io/enable-external-profilesEnable service profiles for non-Kubernetes services
config.linkerd.io/image-pull-policyDocker image pull policy
config.linkerd.io/inbound-portProxy port to use for inbound traffic
config.linkerd.io/init-imageLinkerd init container image name
config.linkerd.io/init-image-versionLinkerd init container image version
config.linkerd.io/opaque-portsPorts that skip the proxy’s protocol detection mechanism and are proxied opaquely. Comma-separated list of values, where each value can be a port number or a range a-b.
config.linkerd.io/outbound-portProxy port to use for outbound traffic
config.linkerd.io/proxy-cpu-limitMaximum amount of CPU units that the proxy sidecar can use
config.linkerd.io/proxy-cpu-requestAmount of CPU units that the proxy sidecar requests
config.linkerd.io/proxy-imageLinkerd proxy container image name
config.linkerd.io/proxy-log-formatLog format (plain or json) for the proxy
config.linkerd.io/proxy-log-levelLog level for the proxy
config.linkerd.io/proxy-memory-limitMaximum amount of Memory that the proxy sidecar can use
config.linkerd.io/proxy-memory-requestAmount of Memory that the proxy sidecar requests
config.linkerd.io/proxy-outbound-connect-timeoutUsed to configure the outbound TCP connection timeout in the proxy
config.linkerd.io/proxy-uidRun the proxy under this user ID
config.linkerd.io/proxy-versionTag to be used for the Linkerd proxy images
config.linkerd.io/skip-inbound-portsPorts that should skip the proxy and send directly to the application. Comma-separated list of values, where each value can be a port number or a range a-b.
config.linkerd.io/skip-outbound-portsOutbound ports that should skip the proxy. Comma-separated list of values, where each value can be a port number or a range a-b.
linkerd.io/injectControls whether or not a pod should be injected; accepted values are enabled, disabled and ingress

For example, to update an auto-injected proxy’s CPU and memory resources, we insert the appropriate annotations into the spec.template.metadata.annotations of the owner’s pod spec, using kubectl edit like this:

  1. spec:
  2. template:
  3. metadata:
  4. annotations:
  5. config.linkerd.io/proxy-cpu-limit: "1"
  6. config.linkerd.io/proxy-cpu-request: "0.2"
  7. config.linkerd.io/proxy-memory-limit: 2Gi
  8. config.linkerd.io/proxy-memory-request: 128Mi

See here for details on tuning the proxy’s resource usage.

For proxies injected using the linkerd inject command, configuration can be overridden using the command-line flags.

Ingress Mode

Proxy ingress mode is a mode of operation designed to help Linkerd integrate with certain ingress controllers. Ingress mode is necessary if the ingress itself cannot be otherwise configured to use the Service port/ip as the destination.

When an individual Linkerd proxy is set to ingress mode, it will route requests based on their :authority, Host, or l5d-dst-override headers instead of their original destination. This will inform Linkerd to override the endpoint selection of the ingress container and to perform its own endpoint selection, enabling features such as per-route metrics and traffic splitting.

The proxy can be made to run in ingress mode by used the linkerd.io/inject: ingress annotation rather than the default linkerd.io/inject: enabled annotation. This can also be done with the --ingress flag in the inject CLI command:

  1. kubectl get deployment <ingress-controller> -n <ingress-namespace> -o yaml | linkerd inject --ingress - | kubectl apply -f -