# Linkerd Getting Started Guide **URL:** \ **Category:** Linkerd General Discussion\ **Created:** [March 22, 2023, 8:13pm UTC](https://linkerd.buoyant.io/t/linkerd-getting-started-guide/55 "2023-03-22T20:13:57Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![william](https://yyz1.discourse-cdn.com/flex029/user_avatar/linkerd.buoyant.io/william/32/5_2.png) [@william](https://linkerd.buoyant.io/u/william)\ **Post date:** [March 22, 2023, 8:13pm UTC](https://linkerd.buoyant.io/t/linkerd-getting-started-guide/55/1 "2023-03-22T20:13:57Z")
# Welcome to Linkerd! 🎈 In this guide, we’ll walk you through how to install the Linkerd onto your Kubernetes cluster. _Note: This guide has been updated to cover Linkerd 2.13._ First, we’ll install the linkerd CLI onto your local machine. Using this CLI, you’ll then install the Linkerd _control plane_ onto your Kubernetes cluster and connect that cluster to Buoyant Cloud. Finally, we’ll “mesh” an application by adding Linkerd’s _data plane_ to it. ## Step 0: Setup Before anything else, we need to ensure you have access to a modern Kubernetes cluster and a functioning `kubectl` command on your local machine. (If you don’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](https://kind.sigs.k8s.io/), [k3d](https://k3d.io/), [Docker for Desktop](https://www.docker.com/products/docker-desktop), [and more](https://kubernetes.io/docs/setup/).) Validate your Kubernetes setup by running: ```bash kubectl version --short ``` You should see output that includes both a `Client Version` and `Server Version`. Now that we have our cluster, we’ll install the Linkerd CLI and use it validate that your cluster is capable of hosting Linkerd. ℹ If you’re using a GKE “private cluster” or Calico CNI, there are some [extra steps required](https://linkerd.io/2/reference/cluster-configuration/#private-clusters) before you can proceed to the next step. ## Step 1: Install the CLI To install the CLI, run: ```bash curl -sSL https://linkerd.buoyant.io/install | sh ``` Be sure to follow the instructions to add it to your path: ```bash export PATH=$HOME/.linkerd2/bin:$PATH ``` Once installed, verify the toolkit CLI is running correctly with: ```bash 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. ## 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: ```bash 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 toolkit CLI running locally and a cluster that is ready to go, it’s time to install Linkerd on your cluster! In this guide, we’re going to do the simplest option: a CLI-based install. This path is “demo grade”. For production, we’d want to do things a little differently: we’d want to install We’ll do this with two commands: ```bash linkerd install --crds | kubectl apply -f - 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’re curious). 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. ℹ 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](https://linkerd.io/2/tasks/install-helm/) or by using a marketplace install from your Kubernetes provider. Depending on the speed of your cluster’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: ```bash linkerd check ``` ## Step 4: Create your Buoyant Cloud account Next, we’ll connect our Linkerd deployment to Buoyant Cloud. Connecting your cluster allows you to get automated health monitoring, notifications of security vulnerabilities, and automated data plane upgrades. Start by [creating a Buoyant Cloud account](https://buoyant.cloud/settings?cli=1) and following the simple instructions. You should see something like: ```bash BUOYANT_CLOUD_CLIENT_ID= BUOYANT_CLOUD_CLIENT_SECRET= linkerd buoyant install --cluster-name=my-new-cluster | kubectl apply -f - ``` (If you’re using Helm for this cluster, there will be slightly different instructions.) Run those commands and then verify everything worked: ```bash linkerd check ``` Congrats! Your cluster is now automatically monitored for health and security. You can take a quick peek at the overall health of your cluster with: ```bash linkerd buoyant dashboard ``` ## Step 5: Install a demo app Linkerd is installed, but it’s not really doing anything just yet. To see Linkerd in action, we’re going to need an application. Let’s install a demo application called _Emojivoto_. This 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: ```bash curl -sSL https://run.linkerd.io/emojivoto.yml | kubectl apply -f - ``` This command installs Emojivoto onto your cluster, 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: ```bash kubectl -n emojivoto port-forward svc/web-svc 8080:80 & ``` Now visit [http://localhost:8080](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. (In a later guide, we’ll show you how to [use Linkerd to identify the problem](https://linkerd.io/2/debugging-an-app/).) 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: ```bash 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. Congratulations! 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: ```bash linkerd -n emojivoto check --proxy ``` And, of course, you can visit [http://localhost:8080](http://localhost:8080/) and once again see Emojivoto in all its meshed glory. ## Step 7: Explore Buoyant Cloud! While Linkerd is running on your cluster (or clusters!), Buoyant Cloud is continually monitoring its health and security, and will send you alerts when To take a quick look at the health of your Linkerd deployments, at any point you can visit [Buoyant Cloud](https://buoyant.cloud/) or simply run: ```bash linkerd buoyant dashboard ``` Click around, explore, and have fun! ## That’s it! 👏 Congratulations, you’ve installed Linkerd have joined the exalted ranks of service mesh users! Give yourself a pat on the back. What’s next? Here are some possible next steps: - [Introduce yourself](#introduce-yourself) on these very forums! - Explore Buoyant’s [Linkerd Production Runbook](https://buoyant.io/runbook/linkerd-runbook/). - Learn more about [Linkerd’s architecture](https://linkerd.io/2/reference/architecture/) - Learn how to use Linkerd to [debug the errors in Emojivoto](https://linkerd.io/2/debugging-an-app/). - Learn how to [add your own services](https://linkerd.io/2/adding-your-service/) to Linkerd without downtime. - Learn how to install [Linkerd extensions](https://linkerd.io/2/tasks/extensions/) such as Jaeger and the multicluster extension. - Learn how to set up [automatic control plane mTLS credential rotation](https://linkerd.io/2/tasks/automatically-rotating-control-plane-tls-credentials/) for long-lived clusters. - Learn how to [restrict access to services using authorization policy](https://linkerd.io/2/tasks/restricting-access/). Above all else: welcome to the Linkerd community! ---
**Author:** ![william](https://yyz1.discourse-cdn.com/flex029/user_avatar/linkerd.buoyant.io/william/32/5_2.png) [@william](https://linkerd.buoyant.io/u/william)\ **Post date:** [April 11, 2023, 3:13pm UTC](https://linkerd.buoyant.io/t/linkerd-getting-started-guide/55/3 "2023-04-11T15:13:18Z")
---
**Author:** ![william](https://yyz1.discourse-cdn.com/flex029/user_avatar/linkerd.buoyant.io/william/32/5_2.png) [@william](https://linkerd.buoyant.io/u/william)\ **Post date:** [April 11, 2023, 3:13pm UTC](https://linkerd.buoyant.io/t/linkerd-getting-started-guide/55/4 "2023-04-11T15:13:46Z")