Automatic mTLS

By default, Linkerd automatically enables mutual Transport Layer Security(mTLS) for most HTTP-based communication between meshed pods, by establishingand authenticating secure, private TLS connections between Linkerd proxies.Because the Linkerd control plane also runs on the data plane, this means thatcommunication between control plane components are also automatically securedvia mTLS.

(See “Caveats and future work” below for details on which traffic cannot beautomatically encrypted.)

NoteLinkerd uses Kubernetes Service Accounts to define service identity. Thisrequires that the automountServiceAccountToken feature (on by default) isenabled. See the Kubernetes service accountdocumentationfor more.

Once your service has been added, you can validate that mTLS is enabled byfollowing the guide to securing your services withLinkerd.

How does it work?

On install, a trust root, certificate and private key are generated. The trustroot is stored as a KubernetesConfigMap.This is used to verify the identity of any proxy. (Alternatively, Linkerd canuse a trust root of your choosing; see the linkerd install referencedocumentation.) Both certificate and private keyare placed into a KubernetesSecret. It isimportant that this secret stays private and other service accounts in thecluster do not have access. By default, the Secret is placed in the linkerdnamespace and can only be read by the service account used by the Linkerdcontrol plane’s identity component.

On startup, the proxy generates a private key for itself. This key is stored ina tmpfsemptyDir whichnever leaves the pod and stays in memory. After the key has been generated, theproxy connects to the control plane’s identity component. This component is aTLS certificate authority(CA) and is used to signcertificates with the correct identity. Proxies validate the connection toidentity by using the trust root, which is part of the proxy container’sspecification as an environment variable.

Identity in Linkerd is tied to the Kubernetes ServiceAccountthat is being used by the pod. Once the proxy has connected to the identitycontrol plane component, it issues a certificate signing request(CSR). The CSRcontains an initial certificate with the pod’s identity set to its serviceaccount and the actual service acount token so that identity can validatethat the CSR is valid. Once all validation has succeeded, the signed trustbundle is returned to the proxy and it can use that when it acts as both aclient and server.

These certificates are scoped to 24 hours and will be dynamically refreshedusing the same mechanism when required.

Caveats and future work

There are several known gaps in Linkerd’s ability to automatically encrypt andauthenticate all communication in the cluster. These gaps will be fixed infuture releases:

• Non-HTTP traffic is not currently automatically TLS’d. This will beaddressed in a future Linkerd release.

• HTTP requests where the Host header is an IP address, rather than a name,are currently not automatically TLS’d. For example, the connections thatLinkerd’s Prometheus control plane component uses to scrape proxy metrics arenot currently automatically TLS’d. This will be addressed in a future Linkerdrelease.

• Linkerd does not currently enforce mTLS. Any unencrypted requests insidethe mesh will be opportunistically upgraded to mTLS. Any requests originatingfrom inside or outside the mesh will not be automatically mTLS’d by Linkerd.This will be addressed in a future Linkerd release, likely as an opt-inbehavior as it may break some existing applications.

• Ideally, the Service Account token that Linkerd uses would not be shared withother potential uses of that token. In future Kubernetes releases, Kuberneteswill support audience/time-bound Service Account tokens, and Linkerd will usethose instead.