instruction: How do you deploy and configure Linkerd service mesh?
output: Getting Started | 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 Getting Started Welcome to Linkerd! 🎈 In this guide, we&rsquo;ll walk you through how to install Linkerd into your Kubernetes cluster. Then we&rsquo;ll deploy a sample application to show off what Linkerd can do. This guide is designed to walk you through the basics of Linkerd. First, you&rsquo;ll install the CLI (command-line interface) onto your local machine. Using this CLI, you&rsquo;ll then install the control plane onto your Kubernetes cluster. Finally, you&rsquo;ll &ldquo;mesh&rdquo; a application by adding Linkerd&rsquo;s data plane to it. Note This page contains quick start instructions intended for non-production installations. For production-oriented configurations, we suggest reviewing resources in Going to Production . Step 0: Setup Before anything else, we need to ensure you have access to modern Kubernetes cluster and a functioning kubectl command on your local machine. (If you don&rsquo;t already have a Kubernetes cluster, one easy option is to run one on your local machine. There are many ways to do this, including kind , k3d , Docker for Desktop , and more .) Validate your Kubernetes setup by running: kubectl version --short You should see output with both a Client Version and Server Version component. Now that we have our cluster, we&rsquo;ll install the Linkerd CLI and use it validate that your cluster is capable of hosting Linkerd. Note If you&rsquo;re using a GKE &ldquo;private cluster&rdquo; or Calico CNI, there are some extra steps required before you can proceed to the next step. Step 1: Install the CLI If this is your first time running Linkerd, you will need to download the linkerd CLI onto your local machine. The CLI will allow you to interact with your Linkerd deployment. To install the CLI manually, run: curl --proto &#39;=https&#39; --tlsv1.2 -sSfL https://run.linkerd.io/install | sh Be sure to follow the instructions to add it to your path. (Alternatively, if you use Homebrew , you can install the CLI with brew install linkerd . You can also download the CLI directly via the Linkerd releases page .) Once installed, verify the CLI is running correctly with: linkerd version You should see the CLI version, and also Server version: unavailable . This is because you haven&rsquo;t installed the control plane on your cluster. Don&rsquo;t worry—we&rsquo;ll fix that soon enough. Step 2: Validate your Kubernetes cluster Kubernetes clusters can be configured in many different ways. Before we can install the Linkerd control plane, we need to check and validate that everything is configured correctly. To check that your cluster is ready to install Linkerd, run: linkerd check --pre If there are any checks that do not pass, make sure to follow the provided links and fix those issues before proceeding. Step 3: Install Linkerd onto your cluster Now that you have the CLI running locally and a cluster that is ready to go, it&rsquo;s time to install Linkerd on your Kubernetes cluster. To do this, run: linkerd install --crds | kubectl apply -f - followed by: linkerd install | kubectl apply -f - These commands generate Kubernetes manifests with all the core resources required for Linkerd (feel free to inspect this output if you&rsquo;re curious). Piping these manifests into kubectl apply then instructs Kubernetes to add those resources to your cluster. The install --crds command installs Linkerd&rsquo;s Custom Resource Definitions (CRDs), which must be installed first, while the install command installs the Linkerd control plane. Note The CLI-based install presented here is quick and easy, but there are a variety of other ways to install Linkerd, including by using Helm charts or by using a marketplace install from your Kubernetes provider. Depending on the speed of your cluster&rsquo;s Internet connection, it may take a minute or two for the control plane to finish installing. Wait for the control plane to be ready (and verify your installation) by running: linkerd check Step 4: Install the demo app Congratulations, Linkerd is installed! However, it&rsquo;s not doing anything just yet. To see Linkerd in action, we&rsquo;re going to need an application. Let&rsquo;s install a demo application called Emojivoto . Emojivoto is a simple standalone Kubernetes application that uses a mix of gRPC and HTTP calls to allow the user to vote on their favorite emojis. Install Emojivoto into the emojivoto namespace by running: curl --proto &#39;=https&#39; --tlsv1.2 -sSfL https://run.linkerd.io/emojivoto.yml \ | kubectl apply -f - This command installs Emojivoto onto your cluster, but Linkerd hasn&rsquo;t been activated on it yet—we&rsquo;ll need to &ldquo;mesh&rdquo; the application before Linkerd can work its magic. Before we mesh it, let&rsquo;s take a look at Emojivoto in its natural state. We&rsquo;ll do this by forwarding traffic to its web-svc service so that we can point our browser to it. Forward web-svc locally to port 8080 by running: kubectl -n emojivoto port-forward svc/web-svc 8080:80 Now visit http://localhost:8080 . Voila! You should see Emojivoto in all its glory. If you click around Emojivoto, you might notice that it&rsquo;s a little broken! For example, if you try to vote for the donut emoji, you&rsquo;ll get a 404 page. Don&rsquo;t worry, these errors are intentional. (In a later guide, we&rsquo;ll show you how to use Linkerd to identify the problem .) With Emoji installed and running, we&rsquo;re ready to mesh it—that is, to add Linkerd&rsquo;s data plane proxies to it. We can do this on a live application without downtime, thanks to Kubernetes&rsquo;s rolling deploys. Mesh your Emojivoto application by running: kubectl get -n emojivoto deploy -o yaml \ | linkerd inject - \ | kubectl apply -f - This command retrieves all of the deployments running in the emojivoto namespace, runs their manifests through linkerd inject , and then reapplies it to the cluster. (The linkerd inject command simply adds annotations to the pod spec that instruct Linkerd to inject the proxy into the pods when they are created.) As with install , inject is a pure text operation, meaning that you can inspect the input and output before you use it. Once piped into kubectl apply , Kubernetes will execute a rolling deploy and update each pod with the data plane&rsquo;s proxies. Congratulations! You&rsquo;ve now added Linkerd to an application! Just as with the control plane, it&rsquo;s possible to verify that everything is working the way it should on the data plane side. Check your data plane with: linkerd -n emojivoto check --proxy And, of course, you can visit http://localhost:8080 and once again see Emojivoto in all its meshed glory. Step 5: Explore Linkerd! Perhaps that last step was a little unsatisfying. We&rsquo;ve added Linkerd to Emojivoto, but there are no visible changes to the application! That is part of Linkerd&rsquo;s design—it does its best not to interfere with a functioning application. Let&rsquo;s take a closer look at what Linkerd is actually doing. To do this, we&rsquo;ll need to install an extension . Linkerd&rsquo;s core control plane is extremely minimal, so Linkerd ships with extensions that add non-critical but often useful functionality to Linkerd, including a variety of dashboards. Let&rsquo;s install the viz extension, which will install an on-cluster metric stack and dashboard. To install the viz extension, run: linkerd viz install | kubectl apply -f - # install the on-cluster metrics stack Once you&rsquo;ve installed the extension, let&rsquo;s validate everything one last time: linkerd check With the control plane and extensions installed and running, we&rsquo;re now ready to explore Linkerd! Access the dashboard with: linkerd viz dashboard &amp; You should see a screen like this: The Linkerd dashboard in action Click around, explore, and have fun! For extra credit, see if you can find the live metrics for each Emojivoto component, and determine which one has a partial failure. (See the debugging tutorial below for much more on this.) That&rsquo;s it! 👏 Congratulations, you have joined the exalted ranks of Linkerd users! Give yourself a pat on the back. What&rsquo;s next? Here are some steps we recommend: Learn how to use Linkerd to debug the errors in Emojivoto . Learn how to add your own services to Linkerd without downtime. Learn how to install other Linkerd extensions such as Jaeger and the multicluster extension. Learn more about Linkerd&rsquo;s architecture Learn how to set up automatic control plane mTLS credential rotation for long-lived clusters. Learn how to restrict access to services using authorization policy . Hop into the #linkerd channel on the Linkerd Slack and say hi! Above all else: welcome to the Linkerd community! 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.