instruction: How do you deploy and configure Linkerd service mesh?
output: Automatic mTLS | Linkerd Docs Community Get Involved Adopters & Case Studies Linkerd Ambassadors Become an Ambassador Buoyant's Linkerd Forum Blog FAQ Enterprise Star Join Forum Announcing Linkerd 2.18: Battlescars, lessons learned, and preliminary Windows support Learn more You are viewing docs for an older version of Linkerd. You may want the latest documentation for this page instead. Linkerd edge Linkerd 2.18 Linkerd 2.17 Linkerd 2.16 Linkerd 2.15 Linkerd 2.14 Linkerd 2.13 Linkerd 2.12 Linkerd 2.11 Linkerd 2.10 Overview Getting Started Features HTTP, HTTP/2, and gRPC Proxying TCP Proxying and Protocol Detection Retries and Timeouts Automatic mTLS Ingress Telemetry and Monitoring Load Balancing Authorization Policy Automatic Proxy Injection CNI Plugin Dashboard and on-cluster metrics stack Distributed Tracing Fault Injection High Availability HTTP Access Logging Multi-cluster communication Proxy Init Iptables Modes Service Profiles Topology Aware Routing Traffic Split (canaries, blue/green deploys) Tasks Adding your services to Linkerd Automated Canary Releases Automatic Multicluster Failover Automatically Rotating Control Plane TLS Credentials Automatically Rotating Webhook TLS Credentials Bringing your own Prometheus Configuring Per-Route Policy Configuring Proxy Concurrency Configuring Retries Configuring Timeouts Control Plane Debug Endpoints Customizing Linkerd's Configuration with Kustomize Debugging 502s Debugging gRPC applications with request tracing Debugging HTTP applications with per-route metrics Distributed tracing with Linkerd Enabling Topology Aware Routing Exporting Metrics Exposing the Dashboard Generating your own mTLS root certificates Getting Per-Route Metrics Getting started with Linkerd SMI extension Graceful Pod Shutdown Grafana Ingress traffic Injecting Faults Installing Linkerd Installing Linkerd with Helm Installing Multi-cluster Components Linkerd and Pod Security Policies (PSP) Manually Rotating Control Plane TLS Credentials Modifying the Proxy Log Level Multi-cluster communication Multi-cluster communication with StatefulSets Replacing expired certificates Restricting Access To Services Rotating webhooks certificates Securing Linkerd Tap Setting Up Service Profiles Troubleshooting Uninstalling Linkerd Uninstalling Multicluster Upgrading Linkerd Using a Custom Cluster Domain Using A Private Docker Repository Using extensions Using GitOps with Linkerd with Argo CD Using the Debug Sidecar Validating your mTLS traffic Reference Architecture Authorization Policy CLI authz check completion diagnostics identity inject install install-cni jaeger multicluster profile uninject uninstall upgrade version viz Cluster Configuration Extensions List Helm Chart Version Matrix IPTables Reference Proxy Configuration Proxy Log Level Proxy Metrics Service Profiles What is a service mesh? Frequently Asked Questions Releases and Versions Design Principles Going to Production Service Mesh Glossary Automatic mTLS By default, Linkerd automatically enables mutually-authenticated Transport Layer Security (mTLS) for all TCP traffic between meshed pods. This means that Linkerd adds authenticated, encrypted communication to your application with no extra work on your part. (And because the Linkerd control plane also runs on the data plane, this means that communication between Linkerd&rsquo;s control plane components are also automatically secured via mTLS.) See Caveats and future work below for some details. What is mTLS? mTLS, or mutual TLS, is simply &ldquo;regular TLS&rdquo; with the extra stipulation that the client is also authenticated. TLS guarantees authenticity, but by default this only happens in one direction&ndash;the client authenticates the server but the server doesn’t authenticate the client. mTLS makes the authenticity symmetric. mTLS is a large topic. For a broad overview of what mTLS is and how it works in Kuberentes clusters, we suggest reading through A Kubernetes engineer&rsquo;s guide to mTLS . Which traffic can Linkerd automatically mTLS? Linkerd transparently applies mTLS to all TCP communication between meshed pods. However, there are still ways in which you may still have non-mTLS traffic in your system, including: Traffic to or from non-meshed pods (e.g. Kubernetes healthchecks) Traffic on ports that were marked as skip ports , which bypass the proxy entirely. You can verify which traffic is mTLS&rsquo;d in a variety of ways. External systems such as Buoyant Cloud can also automatically generate reports of TLS traffic patterns on your cluster. Operational concerns Linkerd&rsquo;s mTLS requires some preparation for production use, especially for long-lived clusters or clusters that expect to have cross-cluster traffic. The trust anchor generated by the default linkerd install CLI command expires after 365 days. After that, it must be manually rotated —a non-trivial task. Alternatively, you can provide the trust anchor yourself and control the expiration date, e.g. setting it to 10 years rather than one year. Kubernetes clusters that make use of Linkerd&rsquo;s multi-cluster communication must share a trust anchor. Thus, the default linkerd install setup will not work for this situation and you must provide an explicit trust anchor. Similarly, the default cluster issuer certificate and key expire after a year. These must be rotated before they expire . Alternatively, you can set up automatic rotation with cert-manager . External systems such as Buoyant Cloud can be used to monitor cluster credentials and to send reminders if they are close to expiration. How does Linkerd&rsquo;s mTLS implementation work? The Linkerd control plane contains a certificate authority (CA) called identity . This CA issues TLS certificates to each Linkerd data plane proxy. Each certificate is bound to the Kubernetes ServiceAccount identity of the containing pod. These TLS certificates expire after 24 hours and are automatically rotated. The proxies use these certificates to encrypt and authenticate TCP traffic to other proxies. On the control plane side, Linkerd maintains a set of credentials in the cluster: a trust anchor, and an issuer certificate and private key. These credentials can be generated by Linkerd during install time, or optionally provided by an external source, e.g. Vault or cert-manager . The issuer certificate and private key are stored in a Kubernetes Secret ; this Secret is placed in the linkerd namespace and can only be read by the service account used by the Linkerd control plane &rsquo;s identity component. On the data plane side, each proxy is passed the trust anchor in an environment variable. At startup, the proxy generates a private key, stored in a tmpfs emptyDir which stays in memory and never leaves the pod. The proxy connects to the control plane&rsquo;s identity component, validating the connection to identity with the trust anchor, and issues a certificate signing request (CSR) . The CSR contains an initial certificate with identity set to the pod&rsquo;s Kubernetes ServiceAccount , and the actual service account token, so that identity can validate that the CSR is valid. After validation, the signed trust bundle is returned to the proxy, which can use it as both a client and server certificate. These certificates are scoped to 24 hours and dynamically refreshed using the same mechanism. Finally, when a proxy receives an outbound connection from the application container within its pod, it looks up that destination with the Linkerd control plane. If it&rsquo;s in the Kubernetes cluster, the control plane provides the proxy with the destination&rsquo;s endpoint addresses, along with metadata including an identity name. When the proxy connects to the destination, it initiates a TLS handshake and verifies that that the destination proxy&rsquo;s certificate is signed by the trust anchor and contains the expected identity. TLS protocol parameters Linkerd currently uses the following TLS protocol parameters for mTLS connections, although they may change in future versions: TLS version 1.3 Cipher suite TLS_CHACHA20_POLY1305_SHA256 as specified in RFC 8446 . Caveats and future work Linkerd does not require mTLS unless authorization policies are configured. Ideally, the ServiceAccount token that Linkerd uses would not be shared with other potential uses of that token. In future Kubernetes releases, Kubernetes will support audience/time-bound ServiceAccount tokens, and Linkerd will use those instead. Linkerd was originally created by Buoyant View Code of Conduct Community GitHub Slack Linkerd Forum Follow Linkedin YouTube Twitter Edit This Site Copyright © 2025 Linkerd Authors. All rights reserved.