Maintenance Guide

This is the maintenance guide for TopoLVM.

How to Upgrade Supported Kubernetes Version

TopoLVM depends on some Kubernetes repositories like k8s.io/client-go and should support 3 consecutive Kubernets versions at a time. Here is the guide for how to upgrade the supported versions. Issues and PRs related to the last upgrade task also help you understand how to upgrade the supported versions, so checking them together with this guide is recommended when you do this task.

Upgrade Procedure

Please write down to the Github issue of this task what kinds of changes we find in the release note and what we are going to do and NOT going to do to address the changes. The format is up to you, but this is very important to keep track of what changes are made in this task, so please do not forget to do it.

Basically, we should pay attention to breaking changes and security fixes first. If we find some interesting features added in new versions, please consider if we are going to use them or not and make a GitHub issue to incorporate them after the upgrading task is done.

Kubernetes

Choose the next version and check the release note. e.g. 1.17, 1.18, 1.19 -> 1.18, 1.19, 1.20

Edit the following files.

• docs/advanced-setup.md
• README.md
• versions.mk
• .github/workflows/e2e-k8s-incluster-lvmd.yaml
• .github/workflows/e2e-k8s-workflow.yaml
• test/e2e/README.md

We should also update go.mod. According to the Kubebuilder documentation, we should use versions compatible with Kubebuilder, so refer to the samples in the latest Kubebuilder testdata directory (e.g., https://github.com/kubernetes-sigs/kubebuilder/blob/v4.1.1/testdata/project-v4/go.mod#L8-L11 and https://github.com/kubernetes-sigs/kubebuilder/blob/v4.1.1/testdata/project-v4/Makefile#L162) to see which versions should be used.

First, update k8s.io/* libraries. Please note that Kubernetes v1 corresponds with v0 for the release tags. For example, v1.17.2 corresponds with the v0.17.2 tag.

$ VERSION=<upgrading Kubernetes release version>
$ go get k8s.io/api@v${VERSION} k8s.io/apimachinery@v${VERSION} k8s.io/client-go@v${VERSION} k8s.io/mount-utils@v${VERSION}

Next, update controller-runtime by the following command. Before updating it, please read the controller-runtime's release note. If there are breaking changes, we should decide how to manage these changes.

$ VERSION=<upgrading controller-runtime version>
$ go get sigs.k8s.io/controller-runtime@v${VERSION}

Then, update controller-tools. Before updating it, please read the controller-tools's release note. If there are breaking changes, we should decide how to manage these changes.

$ VERSION=<upgrading controller-tools version>
$ go get sigs.k8s.io/controller-tools@v${VERSION}

At last, make it tidy.

$ go mod tidy

Regenerate manifests using new controller-tools.

$ make setup
$ make generate

These are minimal changes for the Kubernetes upgrade, but if there are some breaking changes found in the release notes, you have to handle them as well in this step.

Go

Choose the version compatible with Kubebuilder (e.g., https://github.com/kubernetes-sigs/kubebuilder/blob/v4.1.1/testdata/project-v4/go.mod#L3).

Edit the following files.

• go.mod
• Dockerfile

CSI Sidecars

TopoLVM does not use all the sidecars listed here. Have a look at csi-sidecars.mk first and understand what sidecars are actually being used. The checklist that triggers the update operation does not include liveness probe and node driver registrar, but they will also be updated.

Check the release pages of the sidecars under kubernetes-csi one by one and choose the latest version for each sidecar which satisfies both "Minimal Kubernetes version" and "Supported CSI spec versions".

DO NOT follow the "Status and Releases" tables in this page and the README.md files in the sidecar repositories because they are sometimes not updated properly.

Edit versions.mk to change sidecars' version.

Read the change logs which are linked from the release pages. Confirm diffs of RBAC between published files in upstream and following ones, and update it if required. For example, see https://github.com/kubernetes-csi/external-provisioner/blob/master/deploy/kubernetes/rbac.yaml.

• charts/topolvm/templates/controller/clusterroles.yaml
• charts/topolvm/templates/controller/roles.yaml

If the external-snapshotter sidecar is updated, you also update go.mod and source code accordingly.

cert-manager

As for cert-manager, we have a policy to use LTS release. Check the current LTS release and update the cert-manager version if necessary.

To update the cert-manager version, change the version in charts/topolvm/Chart.yaml. Then, run a following command.

$ bin/helm dependency update charts/topolvm

Please also update the version in the following files.

• versions.mk
• docs/getting-started.md

Depending Tools

The depending tools versions are specified in versions.mk.

The following tools do not depend on other software, use latest versions.

• helm
• helm-docs
• protoc

The following tools depend on kubernetes, use appropriate version associating to minimal supported kubernetes version by TopoLVM.

• kind
• minikube

Update cri-dockerd to a version specified in CRI_DOCKERD_VERSION in the minikube Dockerfile or newer.

Depending Modules

Read kubernetes go.mod, and update the prometheus/* and grpc modules.

Update Upstream Information

Visit the upstream web page to check current TopoLVM information. If some information is old, create PR to update the information

Update Ubuntu and Debian

If the support term for using Ubuntu is about to expire, update the versions. The Debian version in the Dockerfile should also be updated. The target version can be found in the updated Ubuntu image at /etc/debian_version.

Note that we use the oldest supported Ubuntu LTS version for as long as possible to ensure compatibility between the host kernel and the mkfs tools in the image. See also docs/limitations.md.

Final Check

git grep <dropped kubernetes version e.g. 1.18>, git grep image:, git grep -i VERSION and looking versions.mk might help us avoid overlooking necessary changes. Please update the versions in the code and docs with great care.

How to Upgrade Supported CSI Version

Read the release note and check all the changes from the current version to the latest.

Basically, CSI spec should NOT be upgraded aggressively.

Upgrade the CSI version only if new features we should cover are introduced in newer versions, or the Kubernetes versions TopoLVM is going to support does not support the current CSI version.

For updating CSI spec, update the version of github.com/container-storage-interface/spec in go.mod. When updating CSI spec, please also upgrade the version of github.com/kubernetes-csi/csi-test.