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. Add your services to the mesh.

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

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.

Enabling Add-ons. Extend Linkerd's featureset with add-ons.

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.

Graceful Pod Shutdown. Gracefully handle pod shutdown signal.

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 to your own Kubernetes cluster.

Installing Linkerd with Helm. Install Linkerd onto your own 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.

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

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

Securing Your Application with mTLS. Linkerd encrypts your service's traffic by default.

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. Upgrade Linkerd to the latest version.

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 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.