Installing Linkerd

Before you can use Linkerd, you'll need to install thecontrol plane. This pagecovers how to accomplish that, as well as common problems that you mayencounter.

Note that the control plane is typically installed by using Linkerd's CLI. SeeGetting Started for how to install the CLI onto your localenvironment.

Note also that, once the control plane is installed, you'll need to “mesh” anyservices you want Linkerd active for. SeeAdding Your Service for how to add Linkerd's dataplane to your services.

Requirements

Linkerd 2.x requires a functioning Kubernetes cluster on which to run. Thiscluster may be hosted on a cloud provider or may be running locally viaMinikube or Docker for Desktop.

You can validate that this Kubernetes cluster is configured appropriately forLinkerd by running

  1. linkerd check --pre

GKE

If installing Linkerd on GKE, there are some extra steps required depending onhow your cluster has been configured. If you are using any of these features,check out the additional instructions.

Installing

Once you have a cluster ready, generally speaking, installing Linkerd is aseasy as running linkerd install to generate a Kubernetes manifest, andapplying that to your cluster, for example, via

  1. linkerd install | kubectl apply -f -

See Getting Started for an example.

NoteMost common configuration options are provided as flags for install. See thereference documentation for a complete list ofoptions. To do configuration that is not part of the install command, see howyou can create a customized install.

NoteFor organizations that distinguish cluster privileges by role, jump to theMulti-stage install section.

Verification

After installation, you can validate that the installation was successful byrunning:

  1. linkerd check

Uninstalling

See Uninstalling Linkerd.

Multi-stage install

If your organization assigns Kuberenetes cluster privileges based on role(typically cluster owner and service owner), Linkerd provides a “multi-stage”installation to accomodate these two roles. The two installation stages areconfig (for the cluster owner) and control-plane (for the service owner).The cluster owner has privileges necessary to create namespaces, as well asglobal resources including cluster roles, bindings, and custom resourcedefinitions. The service owner has privileges within a namespace necessary tocreate deployments, configmaps, services, and secrets.

Stage 1: config

The config stage is intended to be run by the cluster owner, the role withmore privileges. It is also the cluster owner's responsbility to run theinitial pre-install check:

  1. linkerd check --pre

Once the pre-install check passes, install the config stage with:

  1. linkerd install config | kubectl apply -f -

In addition to creating the linkerd namespace, this command installs thefollowing resources onto your Kubernetes cluster:

  • ClusterRole
  • ClusterRoleBinding
  • CustomResourceDefinition
  • MutatingWebhookConfiguration
  • PodSecurityPolicy
  • Role
  • RoleBinding
  • Secret
  • ServiceAccount
  • ValidatingWebhookConfiguration

To validate the config stage succeeded, run:

  1. linkerd check config

Stage 2: control-plane

Following successful installation of the config stage, the service owner mayinstall the control-plane with:

  1. linkerd install control-plane | kubectl apply -f -

This command installs the following resources onto your Kubernetes cluster, allwithin the linkerd namespace:

  • ConfigMap
  • Deployment
  • Secret
  • Service

To validate the control-plane stage succeeded, run:

  1. linkerd check