Skip to content

RELEASING.md

Latest commit

 

History

History
151 lines (117 loc) · 8.03 KB

RELEASING.md

File metadata and controls

151 lines (117 loc) · 8.03 KB

Releasing Access Operator

This document describes how to release a new version of the Access Operator.

Regular releases

Create release branch

Before releasing a new major or minor version of Access Operator, the release branch has to be created. The release branch should be named as release-<Major>.<Minor>.x. For example for release 1.2.0, the branch should be named release-1.2.x. The release branch is normally created from the main branch. This is normally done locally and the branch is just pushed into the GitHub repository.

When releasing a new patch version, the release branch should already exist. You just need to cherry-pick bug fixes or add them through PRs.

Prepare the release

For any new release - major, minor or patch - we need to prepare the release. The release preparation includes updating the installation files for the new version or changing the version of the Maven project.

  1. Move to the release branch and run make clean
  2. Run the command RELEASE_VERSION=<NewRealeaseVersion> make release. For example, for release 1.2.0, you would run RELEASE_VERSION=1.2.0 make release.
    • For RELEASE_VERSION always use the GA version here (e.g. 1.2.0) and not the RC version (e.g 1.2.0-rc1).
    • This will automatically update several pom.xml files and all files in packaging/, install/, example/ and helm-charts/ folders.
  3. Update the checksums for released files in .checksums in the release branch.
    • Use the Make commands make checksum_helm, make checksum_install, and make checksum_examples to generate the new checksums.
    • Update the checksums in the .checksums file in the root directory of the GitHub repository.

Review and commit the changes done by the make command and push them into the repository (do not add the newly created top level tar.gz and zip archives named like strimzi-* into Git).

The build workflow should automatically start for any new commit pushed into the release branch.

Running the release workflow

Wait until the build workflow is (successfully) finished for the last commit in the release branch. The regular workflow will build the release ZIP / TAR.GZ files as well as the documentation and store them as artifacts. Note the GitHub Actions Run ID from the URL (e.g., https://github.com/strimzi/kafka-access-operator/actions/runs/1234567890 - the Run ID is 1234567890).

Then run the release workflow manually from the GitHub Actions UI:

  1. Go to the Actions tab in the GitHub repository
  2. Select the Release workflow from the left sidebar
  3. Click Run workflow button
  4. Fill in the required parameters:
    • Release Version: for example 1.2.0
    • Build suffixed images: check this to create suffixed images (e.g., 1.2.0-0)
    • Release Suffix: for example 0 (used only if suffixed images are enabled - identifies different builds done for example due to base image CVEs)
    • GitHub Actions Run ID of the source build: the Run ID from the build workflow (from the URL as noted above)

The release workflow will push the images to the registry and publish the Java artifacts to Maven Central.

Note for RCs:

Release candidates are built with the same release workflow as the final releases. When starting the workflow, use the RC name as the release version. For example 1.2.0-rc1 or 1.2.0-rc2. For release workflows, you should skip the suffixed build since it is not needed.

Generating GPG key for signing the artifacts

When the artifacts are published, they are also signed using a GPG key. The workflow uses default GPG keys generated by a maintainer. To use your own key, complete the following steps:

  1. Generate a GPG key (gpg --full-generate-key), or use the key that you already use for signing commits in GitHub, for example.
  2. The command prompts you for a password. This password is important because you will use it for the GPG_PASSPHRASE variable.
  3. Use gpg --list-keys to find your key ID, and store it for the next step.
  4. After you generate the key and obtain its ID, publish it to the public keyserver: 
    gpg --keyserver keyserver.ubuntu.com --send-keys <YOUR_KEY_ID>
    This step is IMPORTANT. Without it, the release workflow will fail on signing the artifacts.
  5. Export the key and encode it using Base64. Then copy the encoded key and use it for the GPG_SIGNING_KEY variable: 
    gpg --export-secret-keys <YOUR_KEY_ID> | base64 > private.key
    The contents of private.key need to be copied and pasted into the GPG_SIGNING_KEY.

The release workflow will push the images to the registry. It will also prepare in artifacts the ZIP and TAR.GZ archives with the installation files and the Helm Chart. You will need these later to attach them to the GitHub release.

Smoke tests

After the release pipeline is finished, it is always a good idea to do some smoke tests of the images to double-check they were pushed correctly. Also check the helm chart using the helm show command, e.g.:

helm show chart oci://quay.io/strimzi-helm/strimzi-access-operator:1.2.0

Creating the release

After the release workflow is finished, the release has to be created:

  1. Tag the right commit from the release branch with the release name (e.g. git tag 1.2.0) and push it to GitHub.
  2. Go to Maven Central > Publish to publish the release artifacts.
  3. On GitHub, create the release and attach the ZIP / TAR.GZ artifacts from the build workflow artifacts.

Post release (only for GA, not for RCs)

In the Access Operator repo create a PR into main to update:

  • The install directory.
  • The helm-charts directory.
  • The examples directory.
  • The checksums in the checksums file.
  • The version to the next SNAPSHOT version.
    • To do this run the next_version make target: NEXT_VERSION=1.3.0-SNAPSHOT make next_version
    • This updates the pom.xml files and the release.version file.

In the Strimzi cluster opertor repo create a PR into main to update:

  • The packaging/install/access-operator directory.
  • The packaging/examples/kafka-access directory.
  • The access-operator.version property in the pom.xml file.
  • The CHANGELOG.md to state that the Strimzi Access Operator files have been updated to a new version.

Announcements

Announce the release on following channels:

  • Mailing lists
  • Slack
  • Social accounts (if the release is significant enough)

Rebuilding container images for base image CVEs

In case of a CVE in the base container image, we might need to rebuild the Access Operator container image. This can be done using the CVE Container Rebuild workflow. This workflow will take previously built binaries from GHCR and use them to build a new container image. It will push the container image to the container registry with the suffixed tag (e.g. 1.2.0-2). Afterwards, it will wait for manual approval in the cve-validation environment. This gives additional time to manually test the new container image. After the manual approval, the image will be also pushed under the tag without suffix (e.g. 1.2.0).

The suffix can be specified when starting the rebuild workflow. You should always check what was the previous suffix and increment it. That way, the older images will be still available in the container registry under their own suffixes. Only the latest rebuild will be available under the un-suffixed tag.

To run the CVE rebuild workflow:

  1. Go to the Actions tab in the GitHub repository
  2. Select the CVE Container Rebuild workflow from the left sidebar
  3. Click Run workflow button
  4. Fill in the required parameters:
    • Release Version: for example 1.2.0
    • Release Suffix: for example 2 (used to create the suffixed images such as strimzi/strimzi-access-operator:1.2.0-2 to identify different builds done for different CVEs)
    • GitHub Actions Run ID of the source build: the Run ID from the original build workflow that created the binaries

This process should be used only for CVEs in the base images. Any CVEs in our code or in the Java dependencies require new patch (or minor) release.