Feb 21, 2024: Announcing Linkerd 2.15 with support for VM workloads, native sidecars, and SPIFFE! Read more »

This is not the latest version of Linkerd!
This documentation is for an older version of Linkerd. You may want the Linkerd 2.15 (current) documentation instead.


As a complement to the Linkerd feature docs and the Linkerd reference docs, we’ve provided guides and examples of common tasks that you may need to perform when using Linkerd.

Common Linkerd tasks

Adding your services to Linkerd. In order for your services to take advantage of Linkerd, they also need to be meshed by injecting Linkerd's data plane proxy into their pods.

Automated Canary Releases. Reduce deployment risk by combining Linkerd and Flagger to automate canary releases based on service metrics.

Automatic Multicluster Failover. Use the Linkerd Failover extension to failover between clusters.

Automatically Rotating Control Plane TLS Credentials. Use cert-manager to automatically rotate control plane TLS credentials.

Automatically Rotating Webhook TLS Credentials. Use cert-manager to automatically rotate webhook TLS credentials.

Bringing your own Prometheus. Use an existing Prometheus instance with Linkerd.

Configuring Proxy Concurrency. Limit the Linkerd proxy's CPU usage.

Configuring Retries. Configure Linkerd to automatically retry failing requests.

Configuring Timeouts. Configure Linkerd to automatically fail requests that take too long.

Control Plane Debug Endpoints. Linkerd's control plane components provide debug endpoints.

Customizing Linkerd's Configuration with Kustomize. Use Kustomize to modify Linkerd's configuration in a programmatic way.

Debugging 502s. Determine why Linkerd is returning 502 responses.

Debugging gRPC applications with request tracing. Follow a long-form example of debugging a failing gRPC application using live request tracing.

Debugging HTTP applications with per-route metrics. Follow a long-form example of debugging a failing HTTP application using per-route metrics.

Distributed tracing with Linkerd. Use Linkerd to help instrument your application with distributed tracing.

Exporting Metrics. Integrate Linkerd's Prometheus with your existing metrics infrastructure.

Exposing the Dashboard. Make it easy for others to access Linkerd and Grafana dashboards without the CLI.

Generating your own mTLS root certificates. Generate your own mTLS root certificate instead of letting Linkerd do it for you.

Getting Per-Route Metrics. Configure per-route metrics for your application.

Getting started with Linkerd SMI extension. Use Linkerd SMI extension to work with Service Mesh Interface(SMI) resources.

Graceful Pod Shutdown. Gracefully handle pod shutdown signal.

Grafana. Grafana install instructions and how to link it with the Linkerd Dashboard

Ingress traffic. Linkerd works alongside your ingress controller of choice.

Injecting Faults. Practice chaos engineering by injecting faults into services with Linkerd.

Installing Linkerd. Install Linkerd onto your Kubernetes cluster.

Installing Linkerd with Helm. Install Linkerd onto your Kubernetes cluster using Helm.

Installing Multi-cluster Components. Allow Linkerd to manage cross-cluster communication.

Linkerd and Pod Security Policies (PSP). Using Linkerd with a pod security policies enabled.

Manually Rotating Control Plane TLS Credentials. Update Linkerd's TLS trust anchor and issuer certificate.

Modifying the Proxy Log Level. Linkerd proxy log levels can be modified dynamically to assist with debugging.

Multi-cluster communication. Allow Linkerd to manage cross-cluster communication.

Multi-cluster communication with StatefulSets. cross-cluster communication to and from headless services.

Replacing expired certificates. Follow this workflow if any of your TLS certs have expired.

Restricting Access To Services. Use Linkerd policy to restrict access to a service.

Rotating webhooks certificates. Follow these steps to rotate your Linkerd webhooks certificates.

Securing Your Cluster. Best practices for securing your Linkerd installation.

Setting Up Service Profiles. Create a service profile that provides more details for Linkerd to build on.

Troubleshooting. Troubleshoot issues with your Linkerd installation.

Uninstalling Linkerd. Linkerd can be easily removed from a Kubernetes cluster.

Uninstalling Multicluster. Unlink and uninstall Linkerd multicluster.

Upgrading Linkerd. Perform zero-downtime upgrades for Linkerd.

Upgrading Multicluster in Linkerd 2.9. Upgrading Multicluster to Linkerd 2.9.

Using a Custom Cluster Domain. Use Linkerd with a custom cluster domain.

Using A Private Docker Repository. Using Linkerd with a Private Docker Repository.

Using extensions. Add functionality to Linkerd with optional extensions.

Using GitOps with Linkerd with Argo CD. Use Argo CD to manage Linkerd installation and upgrade lifecycle.

Using the Debug Sidecar. Inject the debug container to capture network packets.

Validating your mTLS traffic. You can validate whether or not your traffic is being mTLS'd by Linkerd.