Getting Started
In this guide, we'll walk you through how to install Linkerd into yourKubernetes cluster. Then we'll deploy a sample application to show off whatLinkerd can do.
Installing Linkerd is easy. First, you will install the CLI (command-lineinterface) onto your local machine. Using this CLI, you'll then install thecontrol plane into your Kubernetes cluster. Finally, you'll “mesh” one ormore services by adding the data plane proxies. (See the page for details.)
Before we can do anything, we need to ensure you have access to a Kubernetescluster running 1.13 or later, and a functioning command on yourlocal machine. (One easy option is to run Kubernetes on your local machine. Wesuggest Docker Desktop or, butthere are many options.)
When ready, make sure you're running a recent version of Kubernetes with:
In the next step, we will install the Linkerd CLI and validate that your clusteris ready to install the control plane.
(Note: if you're using a GKE with a “private cluster”, there are some beforeyou can proceed.)
Step 1: Install the CLI
If this is your first time running Linkerd, you will need to download thecommand-line interface (CLI) onto your local machine. This CLI interacts withLinkerd, including installing the control plane onto your Kubernetes cluster.
To install the CLI manually, run:
curl -sL https://run.linkerd.io/install | sh
Alternatively, you can download the CLI directly via theLinkerd releases page.
Next, add linkerd
to your path with:
export PATH=$PATH:$HOME/.linkerd2/bin
If you use , you can instead download and install theCLI with:
However you install it, you can verify the CLI is running correctly with:
linkerd version
You should see the CLI version, and also Server version: unavailable
. This isbecause you haven't installed the control plane on your cluster. Don't worry,you'll be installing the control plane soon.
Kubernetes clusters can be configured in many different ways. To ensure that thecontrol plane will install correctly, the Linkerd CLI can check and validatethat everything is configured correctly.
To check that your cluster is configured correctly and ready to install thecontrol plane, you can run:
linkerd check --pre
Step 3: Install Linkerd onto the cluster
Now that you have the CLI running locally and a cluster that is ready to go,it's time to install the control plane into its own namespace (by default,linkerd
). To do this, run:
The linkerd install
command generates a Kubernetes manifest with all thenecessary control plane resources. (You can inspect the output if desired!).Piping this manifest into kubectl apply
will instruct Kubernetes toadd those resources to your cluster.
Depending on the speed of your cluster's Internet connection, it may take aminute or two for your cluster to pull the Linkerd images. While that ishappening, we can validate the installation by running:
This command will patiently wait until Linkerd has been installed, is runningand becomes healthy. If you're interested in what components were installed,you can run:
kubectl -n linkerd get deploy
Check out the architecturedocumentation for an in depth explanation of what these components are and whatthey do.
NoteLinkerd installs certain resources that require cluster-wide permissions. Forclusters where these permissions are restricted, the alternative instructions, which split theserequirements into a separate, self-contained step, may be useful.
With the control plane installed and running, you can now view the Linkerddashboard by running:
linkerd dashboard &
)The Linkerd dashboard in action
This command sets up a port forward from your local system to the pod. (It's also possible toexpose the dashboard for everyone to access.)
Because the control plane components all have the proxy installed in their pods,each component is also part of the data plane itself. This provides the abilityto dig into what is going on with the control plane itself behind the scenes.In fact, you can run:
linkerd -n linkerd top deploy/linkerd-web
This is the traffic you're generating by looking at the dashboard itself!
Step 5: Install the demo app
To get a feel for how Linkerd would work for one of your services, you caninstall a demo application. The emojivoto application is a standaloneKubernetes application that uses a mix of gRPC and HTTP calls to allow theusers to vote on their favorite emojis.
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 app. If you're using at this point you canvisit http://localhost directly. If you're not usingDocker Desktop, we'll need to forward the web-svc
service. To forwardweb-svc
locally to port 8080, you can run:
Now visit . Voila! The emojivotoapp in all its glory.
Next, let's add Linkerd to emojivoto by running:
kubectl get -n emojivoto deploy -o yaml \
| linkerd inject - \
This command retrieves all of the deployments running in the emojivoto
namespace, runs the manifest through linkerd inject
, and then reapplies it tothe cluster. The linkerd inject
command adds annotations to the pod specinstructing Linkerd to add (“inject”) the proxy as a container to the pod spec.(See Automatic Proxy Injection for more.)
As with install
, inject
is a pure text operation, meaning that you caninspect the input and output before you use it. Once piped into kubectl apply
, Kubernetes will execute a rolling deploy and update each pod with thedata plane's proxies, all without any downtime.
Congratulations! You've now added Linkerd to existing services! Just as withthe control plane, it is possible to verify that everything worked the way itshould with the data plane. To do this check, run:
linkerd -n emojivoto check --proxy
You can now view the Linkerd dashboard and see all the services in the demoapp. Since the demo app comes with a load generator, we can see live trafficmetrics by running:
linkerd -n emojivoto stat deploy
This will show the “golden” metrics for each deployment:
- Success rates
- Request rates
- Latency distribution percentiles
To dig in a little further, it is possible to use top
to get a real-timeview of which paths are being called:
linkerd -n emojivoto top deploy
To go even deeper, we can use shows the stream of requests across asingle pod, deployment, or even everything in the emojivoto namespace:
linkerd -n emojivoto tap deploy/web
All of this functionality is also available in the dashboard, if you would liketo use your browser instead:
)Top Line Metrics
)Top
What about things that happened in the past? Linkerd includes to visualize the metricscollected by Prometheus, and shipswith some pre-configured dashboards. You can get to these by clicking theGrafana icon in the overview page.
)Deployment Detail Dashboard
That's it! 👏
- Use Linkerd to debug the errors in emojivoto
- to Linkerd without downtime
- Learn more about Linkerd's architecture
Welcome to the Linkerd community!