This document details the K3S kubernetes patch release process.
# Before You Begin
You’ll be primarily using git and go. Git can be installed via the local package manager. Make sure Go is installed and configured correctly, utilizing a “gopath”. This can be set via an environment variable called GOPATH. eg. export GOPATH=”${HOME}/go”, typically.
## Clone and Setup Remotes
Clone from upstream then add k3s-io fork and your personal fork.
# Rebase k3s customizations from the previous release, minus the merge commit (~1),
# onto the new upstream tag. This will leave you on a detached head that will be
# tagged in the following step.
git rebase --onto ${NEW_K8S} ${OLD_K8S} ${OLD_K3S_VER}~1
# Kubernetes is specific with the Go version used per release. We use alpine and docker to specify the Go version with which we build the project.
# This command is not backwards compatible and requires versions of yq greater than 4.0, as the query syntax has changed throughout the history of the project.
You now have a collection of tagged kubernetes modules in your worktree. By updating go.mod in k3s to point at these modules we will then be prepared to open a PR for review.
sed -Ei "\|github.com/k3s-io/kubernetes| s|${OLD_K3S_VER}|${NEW_K3S_VER}|" go.mod
sed -Ei "s/k8s.io\/kubernetes v\S+/k8s.io\/kubernetes ${NEW_K8S}/" go.mod
sed -Ei "s/${OLD_K8S_CLIENT}/${NEW_K8S_CLIENT}/g" go.mod
# since drone perform the builds and tests for the updated tags we no longer need to run make locally.
# We now update the go.sum by running go mod tidy:
go mod tidy
git add go.mod go.sum
git commit --all --signoff -m "Update to ${NEW_K8S}"
git push --set-upstream origin ${NEW_K3S_VER}
```
Create a commit with all the changes, and push this upstream.
Create a PR to merge your branch into the corresponding release branch, and wait for CI to run tests on the PR. Make sure to create the PR against the associated release branch for this update.
Once CI passes and you receive two approvals, you may now squash-merge the PR and then tag an RC after the merge to master CI run completes.
# Create a Release Candidate
Releases are kicked off and created by tagging a new tag.
To create a new release in Github UI perform the following:
1. Set title and tag according to the release version you're working on. E.g. v1.22.5-rc1+k3s1.
The k3s-upgrade repository bundles a k3s binary and script that allows a user to upgrade to a new k3s release. This process is normally automated, however this can fail. If the automation does fail, do the following:
Go to the [k3s-upgrade repository](https://github.com/k3s-io/k3s-upgrade) and manually create a new tag for the release. This will kick off a build of the image.
1. Draft a new release
2. Enter the tag (e.g. v1.22.5-rc1+k3s1).
3. Check k3s and k3s-upgrade images Exist
This process will take some time but upon completion, the images will be listed here.
The k3s images will be published [here](https://hub.docker.com/r/rancher/k3s).
The upgrade images will be published [here](https://hub.docker.com/r/rancher/k3s-upgrade).
Verifying Component Release Versions
With each release, k3s publishes release notes that include a table of the components and their versions.
# Update Rancher KDM
This step is specific to Rancher and serves to update Rancher's [Kontainer Driver Metadata](https://github.com/rancher/kontainer-driver-metadata/).
Create a PR in the latest https://github.com/rancher/kontainer-driver-metadata/ dev branch to update the kubernetes versions in channels.yaml.
The PR should consist of two commits.
Change channels.yaml to update the kubernetes versions.
Run go generate. Commit the changes this caused to data/data.json. Title this second commit "go generate".
NOTE: If this is a ew minor release of kubernetes, then a new entry will need to be created in `channels.yaml`. Ensure to set the min/max versions accordingly. If you are not certain what they should be, reach out to the team for input on this as it will depend on what Rancher will be supporting.
NOTE: As of v1.21.4 and above, every new release minor or patch requires a new entry be created in `channels.yaml`. It is possible to build off the server, agent, and chart arguments defined in other entries.
For example, v1.21.4 has server args defined below. The versions pertaining to the release in progress will match the corresponding patch versions established at the beginning of this document:
```yaml
- version: v1.21.4+k3s2
minChannelServerVersion: v2.6.0-alpha1
maxChannelServerVersion: v2.6.99
...
serverArgs: &serverArgs-v1
tls-san:
type: array
A later version can point to those arguments with no change:
```
```yaml
- version: v1.21.5+k3s1
minChannelServerVersion: v2.6.0-alpha1
maxChannelServerVersion: v2.6.99
serverArgs: *serverArgs-v1
```
If you are unsure of the new minor versions min/max constraints you can ask the Project manager and/or QA.
The system-agent-installer-k3s repository is used with Rancher v2prov system. Any K3s version set in Rancher KDM must be published here as well (RCs and full releases).
[Go to the repo](https://github.com/rancher/system-agent-installer-k3s) and manually create a new release and tag it with the corresponding version numbers. This will kick off a build of the image.
Build progress can be tracked here.
# Update Channel Server
Once the release is verified, the channel server config needs to be updated to reflect the new version for “stable”. [channel.yaml can be found at the root of the K3s repo.](https://github.com/k3s-io/k3s/blob/master/channel.yaml)
When updating the channel server a single-line change will need to be performed.
Release Captains responsible for this change will need to update the following stanza to reflect the new stable version of kubernetes relative to the release in progress.
```
# Example channels config
channels:
- name: stable
latest: <new-k8s-version>+k3s1 # Replace this semver with the version corresponding to the release
