linkerd2 Documentation

1. Project Overview & Quickstart (linkerd/linkerd2) Copy Chapter

File: README.md Copy Chapter

Linkerd

:balloon: Welcome to Linkerd! :wave:

Linkerd is an ultralight, security-first service mesh for Kubernetes. Linkerd
adds critical security, observability, and reliability features to your
Kubernetes stack with no code change required.

Linkerd is a Cloud Native Computing Foundation (CNCF) project.

Repo layout Copy Chapter

This is the primary repo for the Linkerd 2.x line of development.

The complete list of Linkerd repos is:

• linkerd2: Main Linkerd 2.x repo, including control plane and CLI
• linkerd2-proxy: Linkerd 2.x data plane proxy
• linkerd2-proxy-api: Linkerd 2.x gRPC API bindings
• linkerd: Linkerd 1.x
• website: linkerd.io website (including docs for 1.x and
  2.x)

Quickstart and documentation Copy Chapter

You can run Linkerd on any modern Kubernetes cluster in a matter of seconds.
See the Linkerd Getting Started Guide for how.

For more comprehensive documentation, start with the Linkerd
docs. (The doc source code is available in the
website repo.)

Working in this repo Copy Chapter

BUILD.md includes general information on how to work in this repo.

We :heart: pull requests! See CONTRIBUTING.md for info on
contributing changes.

Get involved Copy Chapter

• Join Linkerd's user mailing list, developer mailing
  list, and announcements mailing list.
• Follow @Linkerd on Twitter.
• Join the Linkerd Slack.

Steering Committee meetings Copy Chapter

We host regular online meetings for the Linkerd Steering Committee. All are
welcome to attend, but audio and video participation is limited to Steering
Committee members and maintainers. These meetings are currently scheduled on an
ad-hoc basis and announced on the linkerd-users mailing list.

• Zoom link
• Minutes from previous meetings
• Recordings from previous meetings

Code of Conduct Copy Chapter

This project is for everyone. We ask that our users and contributors take a few
minutes to review our Code of Conduct.

Security Copy Chapter

See SECURITY.md for our security policy, including how to report
vulnerabilities.

Linkerd undergoes periodic third-party security audits and we
publish the results here.

License Copy Chapter

Copyright 2025 the Linkerd Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
these files except in compliance with the License. You may obtain a copy of the
License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.

File: grafana/README.md Copy Chapter

Using Grafana with Linkerd

You can install Grafana in various ways, like using the Grafana official Helm
chart, or the
Grafana Operator. Hosted
solutions are also available, like Grafana
Cloud.

The file grafana/values.yaml provides a default Helm config for the Grafana
official Helm
chart, which
pulls the Linkerd dashboards published at
https://grafana.com/orgs/linkerd/dashboards.

You can install the chart like this:

helm repo add grafana https://grafana.github.io/helm-charts
helm install grafana -n grafana --create-namespace grafana/grafana \
  -f https://raw.githubusercontent.com/linkerd/linkerd2/main/grafana/values.yaml

Please make sure to update the entries in grafana/values.yaml before using the
file; in particular:

• auth and log settings under grafana.ini
• datasources.datasources.yaml.datasources[0].url should point to your
  Prometheus service

The other installation methods can easily import those same dashboards using
their IDs, as listed in grafana/values.yaml.

In order to have the Linkerd Viz Dashboard show the Grafana icon there where
relevant, and have it link to the appropriate Grafana dashboard, make sure you
have a proper location set up in the grafana.url setting in Linkerd Viz's
values.yaml.

Granting access Copy Chapter

As of linkerd stable-2.13.0 (or edge-23.1.1), the access to Linkerd Viz'
Prometheus instance has been restricted through the prometheus-admin
AuthorizationPolicy, granting access only to the metrics-api ServiceAccount.
In order to grant access to Grafana, you need to add an AuthorizationPolicy
pointing to its ServiceAccount. You can apply
authzpolicy-grafana.yaml which grants
permission for the grafana ServiceAccount.

Note to developers Copy Chapter

The grafana/dashboards directory contains the same dashboard definitions
published under https://grafana.com/orgs/linkerd. Please keep them in sync when
making any changes. After logging into grafana.com (using the linkerd account),
the dashboards can be managed under Org Settings -> My Dashboards.

File: policy-test/README.md Copy Chapter

Policy controller tests

The policy-test crate includes integration tests for the policy controller.

Running locally Copy Chapter

:; just policy-test

Running in CI Copy Chapter

See the workflow.

2. Official Technical Reference & Guides (linkerd/website) Copy Chapter

[linkerd.io](linkerd.io) Copy Chapter

Source code for the linkerd.io website.

View the linkerd.io README
to learn about general development instructions.

[run.linkerd.io](run.linkerd.io) Copy Chapter

Install scripts for linkerd as well as demo applications such as
emojivoto.

[versioncheck.linkerd.io](versioncheck.linkerd.io) Copy Chapter

Location for existing installations to check and see if they're up to date or
not.

To build and serve against the latest Linkerd2 release:

make serve-versioncheck.linkerd.io

[api.linkerd.io](api.linkerd.io) Copy Chapter

API docs for linkerd1.

Note: this does not deploy by default as part of make publish. It needs to be
released separately.

See slate documentation ./build will grab whatever's on
main from slate-linkerd and add it to the public dir.

Creating a new release Copy Section

1. Run ./release-next-version <release-tag> <new version> in
   https://github.com/BuoyantIO/slate-linkerd/blob/master/BUOYANT-README.md

2. Then check locally

   bash Copy

   make serve-api.linkerd.io

3. Finally push to production

   bash Copy

   make deploy-api.linkerd.io

   • NB: If you're running macOS 10.14+ with ruby installed by XCode, you
     may have to set the SDKROOT
     in order to install json 1.8.3 which is a middleman dependency.

Publishing Copy Chapter

1. Make sure your gcloud tooling is up to date:

   bash Copy

   gcloud components update
   gcloud auth login

2. Do a dry run and make sure everything works:

   bash Copy

   make publish DRY_RUN=true

3. Update the website:

   bash Copy

   make publish

Notes Copy Section

• This does not update api.linkerd.io, see the section for that specifically to
  update it.

• There is no caching in front of run.linkerd.io and versioncheck.linkerd.io.
  You should see updates there immediately.

• There is caching for non-html pages in front of linkerd.io. If you're updating
  a non-html page for linkerd.io, it might be worth flushing the cache
  (cloudflare) and waiting awhile.

If you have to create a new bucket Copy Chapter

You probably won't have to do this, but if you do, don't forget to do this
stuff too to set up the bucket for public serving:

gsutil defacl ch -u AllUsers:R gs://bucketname
gsutil web set -m index.html -e 404.html gs://bucketname

Verifying cache updates Copy Chapter

Turn off all caching on all files:

gsutil -m setmeta -r -h "Cache-Control: no-cache, no-store, must-revalidate" gs://linkerd.io/

Turn caching back on:

gsutil -m setmeta -r -h "Cache-Control:" gs://linkerd.io/

Enable access logs (should only need to be run once) Copy Chapter

gsutil logging set on -b gs://linkerd2-access-logs -o AccessLog gs://linkerd.io

Get access logs Copy Chapter

# note: this will download ALL logs. probably not what you want.
gsutil -m rsync gs://linkerd2-access-logs logs/

Set CORS policy (should only need to be run once) Copy Chapter

gsutil cors set versioncheck.linkerd.io.cors.json gs://versioncheck.linkerd.io