In this guide, we’ll walk you through how to install Linkerd into your Kubernetes cluster. Then we’ll deploy a sample application to show off what Linkerd can do.

A service mesh is an infrastructure layer that allows you to manage communication between your application’s microservices.

Service mesh in Kubernetes enables services to detect each other and communicate. It also uses intelligent routing to control API calls and the flow of traffic between endpoints and services. This further enables canaries or rolling upgrades, blue/green, and other advanced deployment strategies.

Linkerd is an ultralight, security-first service mesh for Kubernetes. Linkerd adds critical security, observability, and reliability features to your Kubernetes stack with no code change required.

At a high level, Linkerd consists of a control plane and a data plane.

• The control plane is a set of services that and provide control over Linkerd as a whole.
• The data plane consists of transparent micro-proxies that run “next” to each service instance, as sidecar containers in the pods. These proxies automatically handle all TCP traffic to and from the service, and communicate with the control plane for configuration.

Linkerd also provides a CLI that can be used to interact with the control and data planes.

Ensure that you have accesst to the cluster and that you have a functioning kubectl command locally.

Validate your Kubernetes setup by running:

kubectl version --short

Install Cli

The CLI will allow you to interact with your Linkerd deployment.

To install the CLI manually, run:

curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh

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’t installed the control plane on your cluster. Don’t worry—we’ll fix that soon enough.

Validate your kubernetes cluster

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.

This is the outout on my cluster

➜ linkerd check --pre
Linkerd core checks
===================

kubernetes-api
--------------
√ can initialize the client
√ can query the Kubernetes API

kubernetes-version
------------------
√ is running the minimum Kubernetes API version
√ is running the minimum kubectl version

pre-kubernetes-setup
--------------------
√ control plane namespace does not already exist
√ can create non-namespaced resources
√ can create ServiceAccounts
√ can create Services
√ can create Deployments
√ can create CronJobs
√ can create ConfigMaps
√ can create Secrets
√ can read Secrets
√ can read extension-apiserver-authentication configmap
√ no clock skew detected

linkerd-version
---------------
√ can determine the latest version
√ cli is up-to-date

Status check results are √

Install Linkerd

To install, Use this

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. Piping these manifests into kubectl apply then instructs Kubernetes to add those resources to your cluster. The install --crds command installs Linkerd’s Custom Resource Definitions (CRDs), which must be installed first, while the install command installs the Linkerd control plane.

Wait for the control plane to be ready (and verify your installation) by running:

linkerd check

If everything goes as expected, youshould get a message that Status check results are √.

Install a demo app

To see Linkerd in action, we’re going to need an application. The Linkerd team provides 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.

First download the manifest for the app to the current directory:

curl -O --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/emojivoto.yml

Be free to inspect the downloaded file. Basically, it installs the Emojivoto application into the emojivoto namespace. Apply with this command:

➜ kubectl apply -f emojivoto.yml
namespace/emojivoto created
serviceaccount/emoji created
serviceaccount/voting created
serviceaccount/web created
service/emoji-svc created
service/voting-svc created
service/web-svc created
deployment.apps/emoji created
deployment.apps/vote-bot created
deployment.apps/voting created
deployment.apps/web created

The application will be instralled but Linkerd hasn’t been activated on it yet—we’ll need to “mesh” the application before Linkerd can work its magic.

Before we mesh it, let’s take a look at Emojivoto in its natural state. We’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’s a little broken! For example, if you try to vote for the donut emoji, you’ll get a 404 page. Don’t worry, these errors are intentional.

With Emoji installed and running, we’re ready to mesh it—that is, to add Linkerd’s data plane proxies to it. We can do this on a live application without downtime, thanks to Kubernetes’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’s proxies.

You’ve now added Linkerd to an application! Just as with the control plane, it’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.

Explore Linkerd

You will note that from the last step after adding linkerd to Emojivote, there is no physical change in the application. That is part of Linkerd’s design—it does its best not to interfere with a functioning application.

Let’s take a closer look at what Linkerd is actually doing. To do this, we’ll need to install an extension. Linkerd’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’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’ve installed the extension, let’s validate everything one last time:

linkerd check

With the control plane and extensions installed and running, we’re now ready to explore Linkerd! Access the dashboard with:

linkerd viz dashboard &

Click around, explore, and have fun! 

Cleaning up

If you no longer want to have linkerd installed in your system, you can use the following commands to achieve that.

Deleting extensions

linkerd viz uninstall | kubectl delete -f -