Installing Linkerd
Before you can use Linkerd, you’ll need to install the core control plane. This page covers how to accomplish that, as well as common problems that you may encounter.
Note that the control plane is typically installed by using Linkerd’s CLI. See Getting Started for how to install the CLI onto your local environment.
Linkerd also comprises of some first party extensions which add additional features i.e viz
, multicluster
and jaeger
. See Extensions to understand how to install them.
Note also that, once the control plane is installed, you’ll need to “mesh” any services you want Linkerd active for. See Adding Your Service for how to add Linkerd’s data plane to your services.
Requirements
Linkerd 2.x requires a functioning Kubernetes cluster on which to run. This cluster may be hosted on a cloud provider or may be running locally via Minikube or Docker for Desktop.
You can validate that this Kubernetes cluster is configured appropriately for Linkerd by running
linkerd check --pre
GKE
If installing Linkerd on GKE, there are some extra steps required depending on how 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 as easy as running linkerd install
to generate a Kubernetes manifest, and applying that to your cluster, for example, via
linkerd install | kubectl apply -f -
See Getting Started for an example.
Note
Most common configuration options are provided as flags for install
. See the reference documentation for a complete list of options. To do configuration that is not part of the install
command, see how you can create a customized install.
Note
For organizations that distinguish cluster privileges by role, jump to the Multi-stage install section.
Verification
After installation, you can validate that the installation was successful by running:
linkerd check
Uninstalling
See Uninstalling Linkerd.
Multi-stage install
If your organization assigns Kubernetes cluster privileges based on role (typically cluster owner and service owner), Linkerd provides a “multi-stage” installation to accommodate these two roles. The two installation stages are config
(for the cluster owner) and control-plane
(for the service owner). The cluster owner has privileges necessary to create namespaces, as well as global resources including cluster roles, bindings, and custom resource definitions. The service owner has privileges within a namespace necessary to create deployments, configmaps, services, and secrets.
Stage 1: config
The config
stage is intended to be run by the cluster owner, the role with more privileges. It is also the cluster owner’s responsibility to run the initial pre-install check:
linkerd check --pre
Once the pre-install check passes, install the config stage with:
linkerd install config | kubectl apply -f -
In addition to creating the linkerd
namespace, this command installs the following resources onto your Kubernetes cluster:
- ClusterRole
- ClusterRoleBinding
- CustomResourceDefinition
- MutatingWebhookConfiguration
- PodSecurityPolicy
- Role
- RoleBinding
- Secret
- ServiceAccount
- ValidatingWebhookConfiguration
To validate the config
stage succeeded, run:
linkerd check config
Stage 2: control-plane
Following successful installation of the config
stage, the service owner may install the control-plane
with:
linkerd install control-plane | kubectl apply -f -
This command installs the following resources onto your Kubernetes cluster, all within the linkerd
namespace:
- ConfigMap
- Deployment
- Secret
- Service
To validate the control-plane
stage succeeded, run:
linkerd check