Day 1: Installing Linkerd
Goal: The Linkerd CLI and the Control Plane are running,
linkerd checkis green, and you know what is at work in the namespacelinkerd. · 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.2and 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 --clientExpected:
Client version: edge-26.11.2
Tip: The official script
curl … run.linkerd.io/install-edge | shalways 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 --preExpected (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.yamlExpected (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 -cExpected:
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 wideExpected (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 checkExpected (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 versionExpected:
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-initsets iptables rules that route all of the Pod’s traffic through the proxy. For this it needs the capabilityNET_ADMIN. If it is not allowed to do that, the Linkerd CNI plugin is the alternative.linkerd-proxyis a native sidecar: an init container withrestartPolicy: 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
- Show only the version numbers of the CLI and the Control Plane. Target time: 10 s
- Count the Linkerd CRDs in the cluster. Target time: 20 s
- Show the webhooks Linkerd has registered. Target time: 30 s
- 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 linkerdExpected (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 -1Expected:
Status check results are √
kubectl -n linkerd get deployExpected:
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.yamlExpected:
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-crdsandlinkerd-control-plane) or GitOps – not vialinkerd 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_ADMINfor Pods (Pod Security “restricted”), you need the Linkerd CNI plugin. With Cilium,cni.exclusive=falsemust then be set, otherwise Cilium deletes its configuration.