Skip to content
Hands-on IT IT Drills

Day 1: Installing Linkerd

Goal: The Linkerd CLI and the Control Plane are running, linkerd check is green, and you know what is at work in the namespace linkerd. · Duration: approx. 45 min · Prerequisite: Day 0

Briefing

  • Linkerd consists of the Control Plane (namespace linkerd) and a proxy next to every Pod in the mesh. The proxy is written in Rust and is configured only by Linkerd.
  • The open source project now only publishes edge releases, roughly every week or two, named edge-YY.MM.N. Vendors build stable versions (2.x) themselves, for example Buoyant with “Buoyant Enterprise for Linkerd” (account required).
  • The book uses edge-26.11.2 and pins this version everywhere. Edge does not mean “unstable”, but: read the release notes before every change.
  • Installation happens in two steps: first the CRDs, then the Control Plane.

Drill 1: Get the CLI

mkdir -p ~/linkerd/tag01 && cd ~/linkerd/tag01
ARCH=$(dpkg --print-architecture)
V=edge-26.11.2
curl -fsSLO \
  https://github.com/linkerd/linkerd2/releases/download/$V/linkerd2-cli-$V-linux-$ARCH
sha256sum linkerd2-cli-$V-linux-$ARCH
curl -fsSL https://api.github.com/repos/linkerd/linkerd2/releases/tags/$V \
  | grep -o '"digest": "sha256:[0-9a-f]*"'

Expected (abridged):

4596473d74406298eb5c0123cf710d2834b726487996a9e8fa8859ccda3b360e  linkerd2-cli-edge-...
"digest": "sha256:a2f8cd76f157e6a3043d997c2a8ac338ded2b94c8dfc54ce4fd525c973574403"
"digest": "sha256:489834f8fe8e0485987560ac5005c1061a71e44127cb872f009356dfbcba7380"
"digest": "sha256:4596473d74406298eb5c0123cf710d2834b726487996a9e8fa8859ccda3b360e"

The releases have no checksum file of their own. GitHub, however, shows the SHA-256 value for every file. Your sum must be in the list – on arm64 it is a different line.

sudo install -m 0755 linkerd2-cli-$V-linux-$ARCH /usr/local/bin/linkerd
linkerd version --client

Expected:

Client version: edge-26.11.2

Tip: The official script curl … run.linkerd.io/install-edge | sh always installs the latest edge version to ~/.linkerd2/bin. For a lab with pinned versions, the direct download is better.

Save your progress? Sign up for free

Drill 2: Pre-check

linkerd check --pre

Expected (abridged):

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

gateway-api-crd
---------------
√ Gateway API CRDs are installed

pre-kubernetes-setup
--------------------
√ control plane namespace does not already exist
...
Status check results are √

The check only knows a minimum version of Kubernetes. The docs also list the versions the project has tested. Newer versions such as 1.37 usually work but are not officially tested. This book ran completely on 1.37.2.

Linkerd needs the Gateway API CRDs but does not install them itself. On this cluster, Cilium brought them along:

kubectl get crd httproutes.gateway.networking.k8s.io -o \
  jsonpath='{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}{"\n"}'

Expected:

v1.6.3

If they are missing, install them from the kubernetes-sigs/gateway-api release (standard-install.yaml) before you continue.

Save your progress? Sign up for free

Drill 3: Install the CRDs

linkerd install --crds > crds.yaml
grep -c '^kind: CustomResourceDefinition' crds.yaml
kubectl apply -f crds.yaml

Expected (abridged):

10
customresourcedefinition…/authorizationpolicies.policy.linkerd.io created
customresourcedefinition…/egressnetworks.policy.linkerd.io created
customresourcedefinition…/httplocalratelimitpolicies.policy.linkerd.io created
customresourcedefinition…/httproutes.policy.linkerd.io created
customresourcedefinition…/meshtlsauthentications.policy.linkerd.io created
customresourcedefinition…/networkauthentications.policy.linkerd.io created
customresourcedefinition…/serverauthorizations.policy.linkerd.io created
customresourcedefinition…/servers.policy.linkerd.io created
customresourcedefinition…/serviceprofiles.linkerd.io created
customresourcedefinition…/externalworkloads.workload.linkerd.io created

Why separately? CRDs outlive every version of the Control Plane. During an upgrade they come first, so the new Control Plane already finds its types.

Save your progress? Sign up for free

Drill 4: The Control Plane

linkerd install > control-plane.yaml
grep '^kind:' control-plane.yaml | sort | uniq -c

Expected:

      5 kind: ClusterRole
      5 kind: ClusterRoleBinding
      2 kind: ConfigMap
      1 kind: CronJob
      3 kind: Deployment
      1 kind: MutatingWebhookConfiguration
      1 kind: Namespace
      3 kind: Role
      2 kind: RoleBinding
      5 kind: Secret
      8 kind: Service
      4 kind: ServiceAccount
      2 kind: ValidatingWebhookConfiguration

Look at the file before you apply it – 2300 lines, but only three Deployments. Then:

kubectl apply -f control-plane.yaml
kubectl -n linkerd rollout status deploy --timeout=300s
kubectl -n linkerd get pods -o wide

Expected (abridged):

deployment "linkerd-destination" successfully rolled out
deployment "linkerd-identity" successfully rolled out
deployment "linkerd-proxy-injector" successfully rolled out
NAME                                      READY   STATUS    RESTARTS   AGE   IP  ...
linkerd-destination-5dcfd8f776-xlkh4      4/4     Running   0          64s   ...
linkerd-identity-59c56c964b-w6nsj         2/2     Running   0          64s   ...
linkerd-proxy-injector-86b67d54f6-lhshl   2/2     Running   0          64s   ...
Deployment Task
linkerd-identity certificate authority: issues each proxy an mTLS certificate
linkerd-destination tells proxies where a Service points, which policy applies
linkerd-proxy-injector webhook that adds the proxy to Pods when they are created

Save your progress? Sign up for free

Drill 5: Check everything

linkerd check

Expected (abridged):

linkerd-identity
----------------
√ certificate config is valid
√ trust anchors are using supported crypto algorithm
√ trust anchors are within their validity period
√ trust anchors are valid for at least 60 days
√ issuer cert is using supported crypto algorithm
...
control-plane-version
---------------------
√ can retrieve the control plane version
√ control plane is up-to-date
√ control plane and cli versions match
...
Status check results are √
linkerd version

Expected:

Client version: edge-26.11.2
Server version: edge-26.11.2

Save your progress? Sign up for free

Drill 6: Look inside the Control Plane

kubectl -n linkerd get pod -l linkerd.io/control-plane-component=destination \
  -o jsonpath='{range .items[0].spec.initContainers[*]}init:{.name} {end}
{range .items[0].spec.containers[*]}{.name} {end}{"\n"}'
kubectl -n linkerd get pod -l linkerd.io/control-plane-component=destination \
  -o jsonpath='{.items[0].spec.initContainers[*].restartPolicy}{"\n"}'

Expected:

init:linkerd-init init:linkerd-proxy
destination sp-validator policy
Always

Three things stand out:

  • The Control Plane has proxies too – it is itself part of the mesh.
  • linkerd-init sets iptables rules that route all of the Pod’s traffic through the proxy. For this it needs the capability NET_ADMIN. If it is not allowed to do that, the Linkerd CNI plugin is the alternative.
  • linkerd-proxy is a native sidecar: an init container with restartPolicy: Always. It starts before the app and then keeps running.

The certificates live here:

kubectl -n linkerd get secret,configmap | grep -E 'identity|config'

Expected:

secret/linkerd-config-overrides           Opaque              1      2m
secret/linkerd-identity-issuer            Opaque              2      2m
configmap/linkerd-config                 2      2m
configmap/linkerd-identity-trust-roots   1      2m

linkerd install generated a single self-signed certificate on its own that is both trust anchor and issuer. That is convenient but not meant for production – on Day 5 you replace it with your own anchor and issuer.

Save your progress? Sign up for free

Exercise: Speed Drills

  1. Show only the version numbers of the CLI and the Control Plane. Target time: 10 s
  2. Count the Linkerd CRDs in the cluster. Target time: 20 s
  3. Show the webhooks Linkerd has registered. Target time: 30 s
  4. Show CPU and memory of the Control Plane. Target time: 15 s

Solution

linkerd version --short
kubectl get crd -o name | grep -c linkerd
kubectl get mutatingwebhookconfigurations,validatingwebhookconfigurations | grep linkerd
kubectl top pods -n linkerd

Expected (excerpt for 1, 2 and 4):

edge-26.11.2
edge-26.11.2
10
NAME                                      CPU(cores)   MEMORY(bytes)
linkerd-destination-5dcfd8f776-xlkh4      9m           34Mi
linkerd-identity-59c56c964b-w6nsj         2m           14Mi
linkerd-proxy-injector-86b67d54f6-lhshl   2m           17Mi

About 65 MiB for the entire Control Plane – that is the reason for its reputation as a “lightweight mesh”.

Save your progress? Sign up for free

Checkpoint

linkerd check 2>&1 | tail -1

Expected:

Status check results are √
kubectl -n linkerd get deploy

Expected:

NAME                     READY   UP-TO-DATE   AVAILABLE   AGE
linkerd-destination      1/1     1            1           5m
linkerd-identity         1/1     1            1           5m
linkerd-proxy-injector   1/1     1            1           5m
kubectl -n notes get pods -l app=web -o jsonpath='{.items[0].spec.containers[*].name}'

Expected: only web – the app is not in the mesh yet. That changes on Day 2.

Challenge

Generate the manifest for a highly available Control Plane without changing the cluster, and find out what differs from your installation.

Hint: linkerd install refuses to run if Linkerd is already running – unless you tell it to ignore the cluster.

Solution

cd ~/linkerd/tag01
linkerd install --ha --ignore-cluster > ha.yaml
grep -E '^  replicas:' control-plane.yaml | sort | uniq -c
grep -E '^  replicas:' ha.yaml | sort | uniq -c
grep -c 'kind: PodDisruptionBudget' ha.yaml

Expected:

      3   replicas: 1
      3   replicas: 3
3

In HA mode, every Deployment runs three times, with PodDisruptionBudgets and anti-affinity. On this cluster with two workers that would be too much – Day 14 shows the HA installation with Helm.

Save your progress? Sign up for free

Interview Note

  • Which components does the Linkerd Control Plane have? identity (CA), destination (service discovery and policy), proxy-injector (webhook).
  • What is the difference between edge and stable? The project only builds edge releases. Vendors deliver stable versions with support.
  • Why install CRDs separately? So that Control Plane upgrades never run into missing or outdated types.

Enterprise Note

  • Production installs via Helm (charts linkerd-crds and linkerd-control-plane) or GitOps – not via linkerd install | kubectl apply (Day 14).
  • Trust anchor and issuer come from your own PKI or cert-manager, not from linkerd install (Day 5).
  • Keep up with edge versions regularly: a mesh that has not been updated for a year is harder to upgrade than twelve small steps.
  • Without NET_ADMIN for Pods (Pod Security “restricted”), you need the Linkerd CNI plugin. With Cilium, cni.exclusive=false must then be set, otherwise Cilium deletes its configuration.