Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Linkerd is an open-source service mesh and CNCF incubating project. Linkerd is an ultralight service mesh that provides features that include traffic management, service identity and security, reliability, and observability. For more information about Linkerd, see the official Linkerd FAQ and Linkerd Architecture documentation.
This article shows you how to install Linkerd. The Linkerd linkerd client binary is installed onto your client machine and the Linkerd components are installed into a Kubernetes cluster on AKS.
Note
These instructions reference Linkerd version stable-2.6.0.
The Linkerd stable-2.6.x can be run against Kubernetes versions 1.13+. You can find additional stable and edge Linkerd versions at GitHub - Linkerd Releases.
In this article, you learn how to:
- Download and install the Linkerd linkerd client binary
- Install Linkerd on AKS
- Validate the Linkerd installation
- Access the Dashboard
- Uninstall Linkerd from AKS
Before you begin
The steps detailed in this article assume that you've created an AKS cluster (Kubernetes 1.13 and above, with Kubernetes RBAC enabled) and have established a kubectl connection with the cluster. If you need help with any of these items, then see the AKS quickstart.
All Linkerd pods must be scheduled to run on Linux nodes - this setup is the default in the installation method detailed below and requires no additional configuration.
This article separates the Linkerd installation guidance into several discrete steps. The result is the same in structure as the official Linkerd getting started guidance.
Download and install the Linkerd linkerd client binary
In a bash-based shell on Linux or Windows Subsystem for Linux, use curl to download the Linkerd release as follows:
# Specify the Linkerd version that will be leveraged throughout these instructions
LINKERD_VERSION=stable-2.6.0
curl -sLO "https://github.com/linkerd/linkerd2/releases/download/$LINKERD_VERSION/linkerd2-cli-$LINKERD_VERSION-linux"
The linkerd client binary runs on your client machine and allows you to interact with the Linkerd service mesh. Use the following commands to install the Linkerd linkerd client binary in a bash-based shell on Linux or Windows Subsystem for Linux. These commands copy the linkerd client binary to the standard user program location in your PATH.
sudo cp ./linkerd2-cli-$LINKERD_VERSION-linux /usr/local/bin/linkerd
sudo chmod +x /usr/local/bin/linkerd
If you'd like command-line completion for the Linkerd linkerd client binary, then set it up as follows:
# Generate the bash completion file and source it in your current shell
mkdir -p ~/completions && linkerd completion bash > ~/completions/linkerd.bash
source ~/completions/linkerd.bash
# Source the bash completion file in your .bashrc so that the command-line completions
# are permanently available in your shell
echo "source ~/completions/linkerd.bash" >> ~/.bashrc
Download and install the Linkerd linkerd client binary
In a bash-based shell on MacOS, use curl to download the Linkerd release as follows:
# Specify the Linkerd version that will be leveraged throughout these instructions
LINKERD_VERSION=stable-2.6.0
curl -sLO "https://github.com/linkerd/linkerd2/releases/download/$LINKERD_VERSION/linkerd2-cli-$LINKERD_VERSION-darwin"
The linkerd client binary runs on your client machine and allows you to interact with the Linkerd service mesh. Use the following commands to install the Linkerd linkerd client binary in a bash-based shell on MacOS. These commands copy the linkerd client binary to the standard user program location in your PATH.
sudo cp ./linkerd2-cli-$LINKERD_VERSION-darwin /usr/local/bin/linkerd
sudo chmod +x /usr/local/bin/linkerd
If you'd like command-line completion for the Linkerd linkerd client binary, then set it up as follows:
# Generate the bash completion file and source it in your current shell
mkdir -p ~/completions && linkerd completion bash > ~/completions/linkerd.bash
source ~/completions/linkerd.bash
# Source the bash completion file in your .bashrc so that the command-line completions
# are permanently available in your shell
echo "source ~/completions/linkerd.bash" >> ~/.bashrc
Download and install the Linkerd linkerd client binary
In a PowerShell-based shell on Windows, use Invoke-WebRequest to download the Linkerd release as follows:
# Specify the Linkerd version that will be leveraged throughout these instructions
$LINKERD_VERSION="stable-2.6.0"
# Enforce TLS 1.2
[Net.ServicePointManager]::SecurityProtocol = "tls12"
$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -URI "https://github.com/linkerd/linkerd2/releases/download/$LINKERD_VERSION/linkerd2-cli-$LINKERD_VERSION-windows.exe" -OutFile "linkerd2-cli-$LINKERD_VERSION-windows.exe"
The linkerd client binary runs on your client machine and allows you to interact with the Linkerd service mesh. Use the following commands to install the Linkerd linkerd client binary in a PowerShell-based shell on Windows. These commands copy the linkerd client binary to a Linkerd folder and then make it available both immediately (in current shell) and permanently (across shell restarts) via your PATH. You don't need elevated (Admin) privileges to run these commands and you don't need to restart your shell.
# Copy linkerd.exe to C:\Linkerd
New-Item -ItemType Directory -Force -Path "C:\Linkerd"
Copy-Item -Path ".\linkerd2-cli-$LINKERD_VERSION-windows.exe" -Destination "C:\Linkerd\linkerd.exe"
# Add C:\Linkerd to PATH.
# Make the new PATH permanently available for the current User
$USER_PATH = [environment]::GetEnvironmentVariable("PATH", "User") + ";C:\Linkerd\"
[environment]::SetEnvironmentVariable("PATH", $USER_PATH, "User")
# Make the new PATH immediately available in the current shell
$env:PATH += ";C:\Linkerd\"
Install Linkerd on AKS
Before we install Linkerd, we'll run pre-installation checks to determine if the control plane can be installed on our AKS cluster:
linkerd check --pre
You should see something like the following to indicate that your AKS cluster is a valid installation target for Linkerd:
kubernetes-api
--------------
√ can initialize the client
√ can query the Kubernetes API
kubernetes-version
------------------
√ is running the minimum Kubernetes API version
√ is running the minimum kubectl version
pre-kubernetes-setup
--------------------
√ control plane namespace does not already exist
√ can create Namespaces
√ can create ClusterRoles
√ can create ClusterRoleBindings
√ can create CustomResourceDefinitions
√ can create PodSecurityPolicies
√ can create ServiceAccounts
√ can create Services
√ can create Deployments
√ can create CronJobs
√ can create ConfigMaps
√ no clock skew detected
pre-kubernetes-capability
-------------------------
√ has NET_ADMIN capability
√ has NET_RAW capability
pre-linkerd-global-resources
----------------------------
√ no ClusterRoles exist
√ no ClusterRoleBindings exist
√ no CustomResourceDefinitions exist
√ no MutatingWebhookConfigurations exist
√ no ValidatingWebhookConfigurations exist
√ no PodSecurityPolicies exist
linkerd-version
---------------
√ can determine the latest version
√ cli is up-to-date
Status check results are √
Now it's time to install the Linkerd components. Use the linkerd and kubectl binaries to install the Linkerd components into your AKS cluster. A linkerd namespace will be automatically created, and the components will be installed into this namespace.
linkerd install | kubectl apply -f -
Linkerd deploys a number of objects. You'll see the list from the output of your linkerd install command above. The deployment of the Linkerd components should take around 1 minute to complete, depending on your cluster environment.
At this point, you've deployed Linkerd to your AKS cluster. To ensure we have a successful deployment of Linkerd, let's move on to the next section to Validate the Linkerd installation.
Validate the Linkerd installation
Confirm that the resources have been successfully created. Use the kubectl get svc and kubectl get pod commands to query the linkerd namespace, where the Linkerd components were installed by the linkerd install command:
kubectl get svc --namespace linkerd --output wide
kubectl get pod --namespace linkerd --output wide
The following example output shows the services and pods (scheduled on Linux nodes) that should now be running:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
linkerd-controller-api ClusterIP 10.0.110.67 <none> 8085/TCP 66s linkerd.io/control-plane-component=controller
linkerd-destination ClusterIP 10.0.224.29 <none> 8086/TCP 66s linkerd.io/control-plane-component=controller
linkerd-dst ClusterIP 10.0.225.148 <none> 8086/TCP 66s linkerd.io/control-plane-component=destination
linkerd-grafana ClusterIP 10.0.61.124 <none> 3000/TCP 65s linkerd.io/control-plane-component=grafana
linkerd-identity ClusterIP 10.0.6.104 <none> 8080/TCP 67s linkerd.io/control-plane-component=identity
linkerd-prometheus ClusterIP 10.0.27.168 <none> 9090/TCP 65s linkerd.io/control-plane-component=prometheus
linkerd-proxy-injector ClusterIP 10.0.100.133 <none> 443/TCP 64s linkerd.io/control-plane-component=proxy-injector
linkerd-sp-validator ClusterIP 10.0.221.5 <none> 443/TCP 64s linkerd.io/control-plane-component=sp-validator
linkerd-tap ClusterIP 10.0.18.14 <none> 8088/TCP,443/TCP 64s linkerd.io/control-plane-component=tap
linkerd-web ClusterIP 10.0.37.108 <none> 8084/TCP,9994/TCP 66s linkerd.io/control-plane-component=web
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
linkerd-controller-66ddc9f94f-cm9kt 3/3 Running 0 66s 10.240.0.50 aks-linux-16165125-vmss000001 <none> <none>
linkerd-destination-c94bc454-qpkng 2/2 Running 0 66s 10.240.0.78 aks-linux-16165125-vmss000002 <none> <none>
linkerd-grafana-6868fdcb66-4cmq2 2/2 Running 0 65s 10.240.0.69 aks-linux-16165125-vmss000002 <none> <none>
linkerd-identity-74d8df4b85-tqq8f 2/2 Running 0 66s 10.240.0.48 aks-linux-16165125-vmss000001 <none> <none>
linkerd-prometheus-699587cf8-k8ghg 2/2 Running 0 65s 10.240.0.41 aks-linux-16165125-vmss000001 <none> <none>
linkerd-proxy-injector-6556447f64-n29wr 2/2 Running 0 64s 10.240.0.32 aks-linux-16165125-vmss000000 <none> <none>
linkerd-sp-validator-56745cd567-v4x7h 2/2 Running 0 64s 10.240.0.6 aks-linux-16165125-vmss000000 <none> <none>
linkerd-tap-5cd9fc566-ct988 2/2 Running 0 64s 10.240.0.15 aks-linux-16165125-vmss000000 <none> <none>
linkerd-web-774c79b6d5-dhhwf 2/2 Running 0 65s 10.240.0.70 aks-linux-16165125-vmss000002 <none> <none>
Linkerd provides a command via the linkerd client binary to validate that the Linkerd control plane was successfully installed and configured.
linkerd check
You should see something like the following to indicate that your installation was successful:
kubernetes-api
--------------
√ can initialize the client
√ can query the Kubernetes API
kubernetes-version
------------------
√ is running the minimum Kubernetes API version
√ is running the minimum kubectl version
linkerd-config
--------------
√ control plane Namespace exists
√ control plane ClusterRoles exist
√ control plane ClusterRoleBindings exist
√ control plane ServiceAccounts exist
√ control plane CustomResourceDefinitions exist
√ control plane MutatingWebhookConfigurations exist
√ control plane ValidatingWebhookConfigurations exist
√ control plane PodSecurityPolicies exist
linkerd-existence
-----------------
√ 'linkerd-config' config map exists
√ heartbeat ServiceAccount exist
√ control plane replica sets are ready
√ no unschedulable pods
√ controller pod is running
√ can initialize the client
√ can query the control plane API
linkerd-api
-----------
√ control plane pods are ready
√ control plane self-check
√ [kubernetes] control plane can talk to Kubernetes
√ [prometheus] control plane can talk to Prometheus
√ no invalid service profiles
linkerd-version
---------------
√ can determine the latest version
√ cli is up-to-date
control-plane-version
---------------------
√ control plane is up-to-date
√ control plane and cli versions match
Status check results are √
Access the dashboard
Linkerd comes with a dashboard that provides insight into the service mesh and workloads. To access the dashboard, use the linkerd dashboard command. This command leverages kubectl port-forward to create a secure connection between your client machine and the relevant pods in your AKS cluster. It will then automatically open the dashboard in your default browser.
linkerd dashboard
The command will also create a port-forward and return a link for the Grafana dashboards.
Linkerd dashboard available at:
http://127.0.0.1:50750
Grafana dashboard available at:
http://127.0.0.1:50750/grafana
Opening Linkerd dashboard in the default browser
Uninstall Linkerd from AKS
Warning
Deleting Linkerd from a running system may result in traffic related issues between your services. Ensure that you have made provisions for your system to still operate correctly without Linkerd before proceeding.
First you'll need to remove the data plane proxies. Remove any Automatic Proxy Injection annotations from workload namespaces and roll out your workload deployments. Your workloads should no longer have any associated data plane components.
Finally, remove the control plane as follows:
linkerd install --ignore-cluster | kubectl delete -f -
Next steps
To explore more installation and configuration options for Linkerd, see the following official Linkerd guidance:
You can also follow additional scenarios using: