This document contains instructions for releasing Linkerd2.
Determine the commit SHA of the linkerd2-proxy
repo to be included in the
release. If
proxy-version
is already at the desired SHA, skip to step 2.
If updating to linkerd-proxy
HEAD, note the commit SHA at
latest.txt (Look for
linkerd2-proxy-<linkerd2-proxy-sha>.tar.gz
).
Create a new branch in the linkerd2
repo, username/proxy-version-bump
.
Then run:
bin/git-commit-proxy-version <linkerd2-proxy-sha>
The script will update the .proxy-version
file. Submit a PR to obtain reviews
and approval.
If the linkerd2/proxy-init
project has a new release (which is rare), the
following updates are needed:
-
go.mod
github.com/linkerd/linkerd2-proxy-init v1.2.0
-
pkg/version/version.go
(this also implies changes in unit test fixtures)var ProxyInitVersion = "v1.2.0"
-
charts/linkerd-control-plane/values.yaml
Upgrade the version in
global.proxyInit.image.version
Create a new branch in the linkerd2
repo,
username/proxy-init-version-bump
.
Open a pull request that includes the changes.
This step only applies to minor stable releases (e.g. 2.9.1
).
If it doesn't exist yet, create and push a branch in the linkerd2
repo where
all the minor releases for a given major release will reside:
git checkout -b release/2.9
git push -u origin release/2.9
The branch in the following step should be based off of this one.
Create a branch in the linkerd2
repo, username/edge-X.X.X
(replace with
your name and the actual release number, optionally replace edge
with
stable
).
This step only applies to minor stable releases (e.g. 2.9.1
).
Locate all the commits in the git log that happened since the last stable release, that you'd like to include in the current minor stable release, and cherry-pick each one into the current branch using their corresponding SHAs:
git cherry-pick ae34bcc2
git cherry-pick b34effab
git cherry-pick 223bd232
...
Each step might result in conflicts that you'll need to address.
All the Helm charts (linkerd-crds, linkerd-control-plane, linkerd2-cni,
linkerd-multicluster, linkerd-jaeger and linkerd-viz) have a version
entry
with a semver format major.minor.patch[-edge]
that needs to be updated
according to the rules below.
Note that the appVersion
entry (for those charts that have it) is handled
automatically by CI.
Also keep in mind chart version changes require updating the charts README
files (through bin/helm-docs
) and golden files (through go test ./... -update
).
Example:
Stable release:
1.9.0
Subsequent edges:
1.10.0-edge
1.10.1-edge
Stable maintenance release:
1.9.1
Subsequent edges:
1.10.2-edge
1.10.3-edge
Stable release:
1.11.0
Subsequent edges:
1.12.0-edge
1.12.1-edge
When making the first edge release right after a stable one, bump the minor and reset the patch. This leaves room for eventual maintenance stable release versions.
MOST COMMON CASE: If making an edge release after another edge release, just bump the patch.
In any case remember to keep the -edge
suffix.
When making a new stable release off of main
(new major 2.x.0
release):
- reset patch
- If there are breaking changes, most notably changes to the structure of
values.yaml
: bump major and reset minor - If the changes are non-breaking: bump minor (with respect to previous edge)
- remove the
-edge
suffix
When making a stable maintenance release off of a release/stable-2.x
branch
(new 2.x.y
release), just bump the minor.
In any case remember to remove the -edge
suffix.
Almost all the charts are always updated, at least because the docker image
versions referred in their templates change with each release. One exception is
linkerd-crds
, which doesn't contain image references. So this chart only
requires bumping its version
if there were changes in its templates files.
On this branch, add the release notes for this version in CHANGES.md
.
Please include links/references to publicly reported bugs which are fixed by this release. The fix needs to be referenced whenever it is introduced into the corresponding release channel (edge or stable).
Note: To see all of the changes since the previous release, run the command
below in the linkerd2
repo. If the last release was a stable release, be
sure to use stable-Y.Y.Y
instead of edge-Y.Y.Y
.
git log edge-Y.Y.Y..HEAD
And this command in the linkerd2-proxy
repo:
git log release/vX.X.X..release/vY.Y.Y
Where release/vX.X.X
is the version of the proxy from the last release
and release/vY.Y.Y
is the version of the proxy for this release, e.g.:
git log release/v2.102.0..release/v2.103.0
If you're preparing a minor release, make sure the PR's merge target is the
releases branch you created above (e.g. releases/stable-2.9
). For the other
cases the target should just be main
.
This PR needs an approval from a "code owner." Feel free to ping one of the code owners if you've gotten feedback and approvals from other team members.
To facilitate testing (particularly for stable releases) you might want to publish the docker images in your private repo.
First tag the release:
git tag stable-2.9.1
Do not push this tag just yet, to avoid triggering the actual public release.
Make sure you're logged into your Github docker registry:
echo "$GH_PAT" | docker login ghcr.io -u $GH_USERNAME --password-stdin
Where $GH_USERNAME
is your Github username and $GH_PAT
is a personal access
token with enough permissions for creating Github packages.
Then this will build the images and also push them to your personal Github docker registry (note this implies you've already set docker buildx in your machine, if not follow these instructions):
DOCKER_REGISTRY=ghcr.io/$GH_USERNAME DOCKER_MULTIARCH=1 DOCKER_PUSH=1 bin/docker-build
If this is the first time you push those images into your personal registry,
you'll need to go to https://github.com/$GH_USERNAME?tab=packages
and access
the settings for each image in order to make them public.
After having successfully pushed those images, delete the tag so you can create it again and push it for good as explained in the following step.
Now testers can pull the CLI binaries through this:
DOCKER_REGISTRY=ghcr.io/$GH_USERNAME bin/docker-pull-binaries stable-2.9.1
which will dump them under the target/release
directory.
Besides using those particular binaries to install Linkerd, they'll also need to
point to your registry using the --registry
flag. Currently that flag doesn't
apply to add-ons, so you need to also recur to the --config
flag. Currently
that only applies to Grafana:
$ cat linkerd-overrides.yml
grafana:
enabled: true
image:
name: ghcr.io/alpeb/grafana
$ target/release/linkerd2-cli-stable-2.9.1-darwin install --registry ghcr.io/$GH_USERNAME --config ~/tmp/linkerd-overrides.yml
After the review has passed and the branches from step 2 and 4 have been merged, follow the instructions below to properly create and push the release tag from the appropriate branch.
Note: The release script will create a GPG-signed tag, so users must have GPG signing setup in their local git config.
If performing an edge release then issue these commands. The appropriate tag will be automatically calculated:
git checkout main
git pull
./bin/create-release-tag edge
If performing a stable release then issue these commands instead (in this case you need to explicitly pass the version to be released):
git checkout main
git pull
./bin/create-release-tag stable x.x.x
In both cases follow the instructions on screen for pushing the tag upstream.
That will kick off a CI Release workflow run that will:
- Build and push the docker images for the tag that was created
- Run the k3d integration tests in the Github actions VMs themselves
- Run a k3d integration test on a separate ARM64 host
- Create a release in Github, and upload the CLI binaries with their checksums
- Dispatch an event caught by the website repo that triggers a website rebuild which will update the edge/stable versions in the website
- Retrieve the installation script from run.linkerd.io and verify it installs the current version being released
- Deploy the updated helm charts
You can locate the CI run here.
Go to the release page in Github and check that the notes are properly formatted and the files are there. Download the file for your system along with its checksum, verify the checksum matches, and do a basic sanity check:
linkerd version
linkerd install | kubectl apply -f -
linkerd check
linkerd viz install | kubectl apply -f -
linkerd viz check
linkerd dashboard
- Install linkerd onto your cluster, and run a few CLI commands
- Open the dashboard and click around
- Click through to Grafana
- When finished with this step, you may want to delete your
alias
to prevent confusion later
Send an email to [email protected], [email protected], and [email protected], announcing the release.
Subscribe to these mailing lists if you aren't on them:
Make sure to include the install instructions (adjust depending if it's an edge or a stable release):
To install the CLI for this edge release, run:
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh
And please check the upgrade instructions for detailed steps on how to upgrade your cluster using either the CLI or Helm.
Aftewards, include the full release notes. Liberally apply emoji. ⭐
Ensure that you send a brief summary of the release in Linkerd Slack's #announcement channel.
When doing a stable-X.X.X
be sure to also include an announcement page for
the Linkerd2 dashboard "Community" sidebar button.
In the website repo:
- Run
hugo new --contentDir linkerd.io/content/dashboard/ YYYYMMDD.md
- Open the newly created file in your favorite editor and change the
title
to match the announcement email title. - Remove the
draft: true
section in the file and then add a brief summary of the stable release. - cd to the directory
linkerd.io
. - Run
hugo serve
in the directory to test your changes. - Verify your change by navigating to
http://localhost:1313/dashboard
. Make sure that the announcement appears at the top of the page. - Once you are satisfied with your changes, Post the PR for review. Once merged, the change should deploy automatically.