Buoyant’s Linkerd Production Runbook
A guide to running a service mesh in production

Last update: Sep 7, 2022 / Linkerd 2.12.0

Before going to production

Before you can be ready to deploy Linkerd to production, there are some things you should do to prepare.

Join the community

If you’re serious about operating Linkerd in production, you should join the open source community channels around it. This is important for staying aware of important updates and announcements, and for learning from other users who are doing the same thing.

We recommend you join:

You can also join:

All Linkerd development happens on GitHub. That’s also the best place to submit bug reports and pull requests. Please also star the repo to inflate our vanity metric.

Understand how to get help

If you need help with Linkerd, you have a couple of channels available to you. Our recommendations are:

Of course, open source support is provided by the community on a best-effort basis. And don’t forget to help others—this is often the best way to give back!

(Note that if you are a Linkerd commercial support customer of Buoyant, you also have other, dedicated support channels available. Please consult the support onboarding instructions you received.)

Understand how to report a security disclosures

In the unlikely event that you discover a security vulnerability in Linkerd, please email the private cncf-linkerd-maintainers@lists.cncf.io list. We’ll send a confirmation email to acknowledge your report, and we’ll send an additional email when we’ve identified the issue positively or negatively.

To receive notifications of vulnerabilities and critical updates, please subscribe to the linkerd-announce mailing list.

Understand where to get Linkerd

Linkerd is 100% open source, and the open source project contains everything you need to run Linkerd at scale and in production. Linkerd’s code is hosted in the GitHub repo. You may choose to build your own binaries or images from this code, or simply to use one of the published releases.

Open source releases are published in a split fashion: GitHub hosts the CLI binaries, and GitHub Container Registry hosts the container images. These are the canonical binaries and images for Linkerd.

Understand Linkerd’s versioning scheme

The 2.x branch of Linkerd follows two versioning schemes: one for stable releases and one for “edge” releases.

Stable releases

Linkerd stable releases follows a modified form of semantic versioning. Linkerd version numbers are of the form stable-2.<major>.[<minor>[.<patch>]]. Breaking changes (typically, configuration incompatibilities) and significant changes to functionality are denoted by changes in major version. Non-breaking changes and minor feature improvements are denoted by changes in minor version. Occasionally, we will release critical bugfixes to stable releases by incrementing the patch version.

For example:

  • 2.11.1 -> 2.12.0: major improvements, possible breaking changes
  • 2.11.1 -> 2.11.2: improvements or bugfixes, no breaking changes

Edge releases

Linkerd 2.x is also published in “edge” releases, typically on a weekly cadence. In contrast to stable releases, Linkerd edge releases follow a flat versioning scheme, of the form edge-<year>.<month>.<number>. Edge releases are provided to the community as a way of getting early access to feature work, and may introduce breaking changes at any point. Sometimes, edge releases are designated informally as a “release candidate” for the upcoming stable release; this designation also provides no guarantees about feature compatibility.

For example:

  • edge-22.4.5: the fifth edge release published in April 2022
  • edge-22.9.1: the first edge release published in September 2022

Understand feature denotations

Sometimes, Linkerd features are denoted as experimental in the documentation. This designation means that, while we feel confident in the viability of the feature, it hasn’t seen enough production use for us to recommend it unreservedly. Caution should be exercised before using an experimental feature in a production environment. The documentation for each experimental feature will describe why it has been classified this way; for example, “this feature has not been tested on all major cloud providers”.

Sometimes, Linkerd features as denoted as deprecated. This means that, while currently supported, we expect to remove the corresponding configuration in an upcoming release.

Rarely, we may denote features as not for production in the documentation. These features may be useful for debugging and getting started, but have known issues when applied to production. The documentation for each not for production feature will describe why it has been classified this way; for example, “this feature has known scaling issues above 10 services”.

Understand which environments are supported

The only requirement for Linkerd is a modern, functioning Kubernetes cluster. Regardless of whether the cluster is on-premises or in the cloud, and regardless of Kubernetes distribution or provider, if it’s running Kubernetes, generally speaking, Linkerd should work. (Of course, Linkerd does require specific capabilities and features of the Kubernetes cluster in order to function. See Preparing your environment for more on this topic.)

Understand which versions of Kubernetes are supported

Generally speaking, Linkerd follows the published policy for “supported” Kubernetes releases: effectively, the three most recent minor Kubernetes versions are supported. Of course, earlier Kubernetes versions may still work.