## 1. Project Overview & Quickstart (linkerd/linkerd2) ## File: README.md # Linkerd ![Linkerd][logo] [](https://bestpractices.coreinfrastructure.org/projects/4629) [![GitHub Actions Status][github-actions-badge]][github-actions] [](LICENSE) [![Go Report Card][go-report-card-badge]][go-report-card] [![Go Reference][go-doc-badge]][go-doc] [![Slack Status][slack-badge]][slack] :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][cncf]) project. ## Repo layout This is the primary repo for the Linkerd 2.x line of development. The complete list of Linkerd repos is: * [linkerd2][linkerd2]: Main Linkerd 2.x repo, including control plane and CLI * [linkerd2-proxy][proxy]: Linkerd 2.x data plane proxy * [linkerd2-proxy-api][proxy-api]: Linkerd 2.x gRPC API bindings * [linkerd][linkerd1]: Linkerd 1.x * [website][linkerd-website]: linkerd.io website (including docs for 1.x and 2.x) ## Quickstart and documentation You can run Linkerd on any modern Kubernetes cluster in a matter of seconds. See the [Linkerd Getting Started Guide][getting-started] for how. For more comprehensive documentation, start with the [Linkerd docs][linkerd-docs]. (The doc source code is available in the [website][linkerd-website] repo.) ## Working in this repo [`BUILD.md`](BUILD.md) includes general information on how to work in this repo. We :heart: pull requests! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for info on contributing changes. ## Get involved * Join Linkerd's [user mailing list][linkerd-users], [developer mailing list][linkerd-dev], and [announcements mailing list][linkerd-announce]. * Follow [@Linkerd][twitter] on Twitter. * Join the [Linkerd Slack][slack]. ## Steering Committee meetings 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][linkerd-users] mailing list. * [Zoom link](https://zoom.us/my/cncflinkerd) * [Minutes from previous meetings](https://docs.google.com/document/d/1GDNM5eosiyjVDo6YHXBMsvlpyzUldgg-XLMNzf7I404/edit) * [Recordings from previous meetings](https://www.youtube.com/playlist?list=PLI9FkLPXDscBHP91Ud3lyJScI4ZCjRG6F) ## Code of Conduct This project is for everyone. We ask that our users and contributors take a few minutes to review our [Code of Conduct][CoC]. ## Security See [SECURITY.md](SECURITY.md) for our security policy, including how to report vulnerabilities. Linkerd undergoes periodic third-party security audits and we [publish the results here](https://github.com/linkerd/linkerd2/tree/main/audits). ## License 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. [github-actions]: https://github.com/linkerd/linkerd2/actions [github-actions-badge]: https://github.com/linkerd/linkerd2/actions/workflows/actions.yml/badge.svg [cncf]: https://www.cncf.io/ [CoC]: https://github.com/linkerd/linkerd/wiki/Linkerd-code-of-conduct [getting-started]: https://linkerd.io/2/getting-started/ [go-report-card]: https://goreportcard.com/report/github.com/linkerd/linkerd2 [go-report-card-badge]: https://goreportcard.com/badge/github.com/linkerd/linkerd2 [go-doc-badge]: https://pkg.go.dev/badge/github.com/linkerd/linkerd2.svg [go-doc]: https://pkg.go.dev/github.com/linkerd/linkerd2 [linkerd1]: https://github.com/linkerd/linkerd [linkerd2]: https://github.com/linkerd/linkerd2 [linkerd-announce]: https://lists.cncf.io/g/cncf-linkerd-announce [linkerd-dev]: https://lists.cncf.io/g/cncf-linkerd-dev [linkerd-docs]: https://linkerd.io/2/overview/ [linkerd-users]: https://lists.cncf.io/g/cncf-linkerd-users [linkerd-website]: https://github.com/linkerd/website [logo]: https://user-images.githubusercontent.com/9226/33582867-3e646e02-d90c-11e7-85a2-2e238737e859.png [proxy]: https://github.com/linkerd/linkerd2-proxy [proxy-api]: https://github.com/linkerd/linkerd2-proxy-api [slack-badge]: http://slack.linkerd.io/badge.svg [slack]: http://slack.linkerd.io [twitter]: https://twitter.com/linkerd --- ## File: grafana/README.md # Using Grafana with Linkerd You can install Grafana in various ways, like using the [Grafana official Helm chart](https://github.com/grafana/helm-charts/tree/main/charts/grafana), or the [Grafana Operator](https://github.com/grafana-operator/grafana-operator). Hosted solutions are also available, like [Grafana Cloud](https://grafana.com/products/cloud/). The file `grafana/values.yaml` provides a default Helm config for the [Grafana official Helm chart](https://github.com/grafana/helm-charts/tree/main/charts/grafana), which pulls the Linkerd dashboards published at . You can install the chart like this: ```shell 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 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](grafana/authzpolicy-grafana.yaml) which grants permission for the `grafana` ServiceAccount. ## Note to developers The `grafana/dashboards` directory contains the same dashboard definitions published under . 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 # Policy controller tests The `policy-test` crate includes integration tests for the policy controller. ## Running locally ```sh :; just policy-test ``` ## Running in CI See the [workflow](.github/workflows/policy_controller.yml). ## 2. Official Technical Reference & Guides (linkerd/website) ## [linkerd.io](linkerd.io) Source code for the linkerd.io website. [View the linkerd.io README](https://github.com/linkerd/website/blob/main/linkerd.io/README.md/) to learn about general development instructions. ## [run.linkerd.io](run.linkerd.io) Install scripts for linkerd as well as demo applications such as [emojivoto](https://github.com/BuoyantIO/emojivoto). ## [versioncheck.linkerd.io](versioncheck.linkerd.io) 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: ```bash make serve-versioncheck.linkerd.io ``` ## [api.linkerd.io](api.linkerd.io) 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](slate-linkerd) `./build` will grab whatever's on main from slate-linkerd and add it to the public dir. ### Creating a new release 1. Run `./release-next-version ` in [https://github.com/BuoyantIO/slate-linkerd/blob/master/BUOYANT-README.md](github.com/BuoyantIO/slate-linkerd) 1. Then check locally ```bash make serve-api.linkerd.io ``` 1. Finally push to production ```bash 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](https://github.com/castwide/vscode-solargraph/issues/78#issuecomment-552675511) in order to install `json 1.8.3` which is a `middleman` dependency. ## Publishing 1. Make sure your gcloud tooling is up to date: ```bash gcloud components update gcloud auth login ``` 1. Do a dry run and make sure everything works: ```bash make publish DRY_RUN=true ``` 1. Update the website: ```bash make publish ``` ### Notes * 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 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: ```bash gsutil defacl ch -u AllUsers:R gs://bucketname gsutil web set -m index.html -e 404.html gs://bucketname ``` ## Verifying cache updates Turn off all caching on all files: ```bash gsutil -m setmeta -r -h "Cache-Control: no-cache, no-store, must-revalidate" gs://linkerd.io/ ``` Turn caching back on: ```bash gsutil -m setmeta -r -h "Cache-Control:" gs://linkerd.io/ ``` ## Enable access logs (should only need to be run once) ```bash gsutil logging set on -b gs://linkerd2-access-logs -o AccessLog gs://linkerd.io ``` ## Get access logs ```bash # 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) ```bash gsutil cors set versioncheck.linkerd.io.cors.json gs://versioncheck.linkerd.io ```