Quick Start with Linkerd v2 Service Mesh

In this guide, we'll walk you through how to install Linkerd into your Kubernetes cluster. We'll then deploy a sample application to showcase Linkerd's capabilities.

Installing Linkerd is easy. First, you'll install the CLI (command line interface) on your local machine. Using this CLI, you'll then install the control plane onto your Kubernetes cluster. Finally, you'll "mesh" one or more of your own services by adding Linkerd's data plane to them.

set up

Before we do anything, we need to make sure you can access a Kubernetes cluster and run kubectl commands on your local machine. (If you don’t already have a Kubernetes cluster, an easy option is to run one on your local machine. There are many ways to do this, including kind, k3d, Docker for Desktop, and many more.)

You can verify the setup by running the following command:

 kubectl version --short  

You should see output that includes Client Version and Server Version components.

Now that we have a cluster, we will install the Linkerd CLI and use it to verify that your cluster is capable of hosting the Linkerd control plane.

Installing the CLI

If this is your first time running Linkerd, you'll need to download the linkerd command-line interface (CLI) to your local machine. The CLI will allow you to interact with your Linkerd deployment.

To install the CLI manually, run:

 curl -sL 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 through the Linkerd releases page.

After installation, verify that the CLI is functioning properly using the following command:

 linkerd version

You should see the CLI version and Server version: unavailable. This is because you haven't installed the control plane on your cluster yet. Don't worry - we'll fix this soon.

Verify your Kubernetes cluster

Kubernetes clusters can be configured in a number of different ways. Before we install the Linkerd control plane, we need to check and verify that everything is configured correctly. To check that your cluster is ready for Linkerd installation, run:

 linkerd check   --pre  

If any of the checks fail, make sure to follow the links provided and resolve those issues before continuing.

Install the Control Plane in your cluster

Now that you have the CLI running locally and your cluster is ready, it’s time to install the control plane.

The first step is to install the control plane core. To do this, run:

 linkerd install | kubectl apply -f -

In this command, the linkerd install command generates a Kubernetes manifest that contains all the necessary control plane resources. Piping this manifest into kubectl apply then instructs Kubernetes to add these resources to your cluster.

Now let's wait for the control plane to finish installing. Depending on the speed of your cluster's Internet connection, this may take a minute or two. Wait for the control plane to be ready (and verify your installation) by running the following command:

 linkerd check  

Next, we'll install some extensions. Extensions add non-critical but generally useful functionality to Linkerd. For this guide, we'll need the viz extension, which installs Prometheus, the dashboard, and metrics components onto your cluster:

 linkerd viz install | kubectl apply -f - # on -cluster metrics stack

Optionally, you can install other extensions at this time. For example:

 ## optional
 linkerd jaeger install | kubectl apply -f - # Jaeger collector and UI
 linkerd multicluster install | kubectl apply -f - # multi-cluster components

Note that extensions can also come from third-party sources. For example, Buoyant Cloud is a free hosted metrics dashboard for Linkerd. It can be installed with viz, but it is optional:

 ## optional
 curl -sL buoyant.cloud/install | sh
 linkerd buoyant install | kubectl apply -f - # hosted metrics dashboard

Once you have installed the viz extension and any other extensions you want, we'll verify everything again:

 linkerd check  

Assuming everything is green, we are ready to move on to the next step!

Navigating Linkerd

With the control plane and extensions installed and running, you can now view the Linkerd dashboard by running:

 linkerd viz dashboard &

This command sets the port from your local system to the linkerd-web pod. (This also exposes the dashboard for everyone to access.)

Since the control plane components all have agents installed in their pods, each component is also part of the data plane itself. This provides the ability to gain insight into what is happening behind the scenes in the control plane itself. In fact, you can run:

 linkerd -n linkerd-viz viz top deploy/web

This is the traffic you generate just by viewing the dashboard itself!

Install the demo app

To see how Linkerd works for one of your services, you can install a demo application. The emojivoto application is a standalone Kubernetes application that uses a mix of gRPC and HTTP calls to allow users to vote on their favorite emoji.

Install emojivoto into the emojivoto namespace by running:

 curl -sL https://run.linkerd.io/emojivoto.yml \
 | kubectl apply -f -

Before we mesh it, let's take a look at the application. If you are using Docker Desktop at this point, you can access http://localhost directly. If you are not using Docker Desktop, we need to forward the web-svc service. To forward web-svc locally to port 8080, you can run:

 kubectl -n emojivoto port- forward svc/web-svc 8080:80

Now visit http://localhost:8080.

Clicking around, you might notice that some parts of emojivoto are broken! For example, if you click on a doughnut emoji, you’ll get a 404 page. Don’t worry, these errors are intentional. (We can use Linkerd to identify the problem. If you’re interested in how to figure out exactly what’s going on, check out the debugging guide.)

Next, let's add the linker to emojivoto by running:

 kubectl get -n emojivoto deploy -o yaml \
 | linkerd inject - \
 | kubectl apply -f -

This command retrieves all deployments running in the emojivoto namespace, runs the manifest through linkerd inject, and then reapplies it to the cluster. The linkerd inject command adds annotations to the pod spec that instructs Linkerd to add ("inject") the proxy as a container into the pod spec. (For more information, see Automatic Proxy Injection.)

Like install, inject is a plain text operation, which means you can inspect the input and output before using it. Once piped to kubectl apply, Kubernetes will perform a rolling deploy and update each pod with the data plane proxy, all without any downtime.

Congratulations! You have now added Linkerd to an existing service! Just like with the control plane, you can verify that everything is working as it should with the data plane. To do this check, run:

 linkerd -n emojivoto check   --proxy  

Monitor its operation

You can now check the Linked panel and see all the services in the demo app. Since the demo app comes with a load generator, we can view live traffic metrics by running the following command:

 linkerd -n emojivoto viz stat deploy

This will show the "golden" metrics for each deployment:

• Success rates
• Request rates
• Latency distribution percentiles

To drill down further, you can use top to see which paths are being called in real time:

 linkerd -n emojivoto viz top deploy

To go even deeper, we can use tap to show the request flow across a single pod, deployment, or even everything in the emojivoto namespace:

 linkerd -n emojivoto viz tap deploy/web

If you prefer to use your browser instead, all of these features are also available in the dashboard:

So what about what happened in the past? Linkerd includes Grafana to visualize the metrics collected by Prometheus, and comes with some preconfigured dashboards. You can access these by clicking the Grafana icon in the overview page.