Generic Release Process

This process applies to all releases other than feature releases, this includes:

• Stable releases

If you intent to release a new feature release, see the Feature Release Process section instead.

Note

The following commands have been validated when ran in the VM used in the Cilium development process. See Development Setup for detailed instructions about setting up said VM.

GitHub template process

1. File a new release issue on GitHub, updating the title to reflect the version that will be released.
2. Follow the steps in the issue template to prepare the release.

Reference steps for the template

1. Ensure that the necessary backports have been completed and merged. See Backporting process.

   1. Update GitHub project and create vX.Y.Z+1 project if applicable.
   2. Update PRs / issues that were added to the vX.Y.Z project, but didn’t make it into this release into the vX.Y.Z+1 project.

2. Create a new project named “X.Y.Z+1” to automatically track the backports for that particular release. Direct Link:

3. Checkout the desired stable branch and pull it:

   git checkout v1.0; git pull

4. Run the release preparation script:

   contrib/release/start-release.sh

   Note

   Check to see if the AUTHORS file has any formatting errors (for instance, indentation mismatches) as well as duplicate contributor names, and correct them accordingly.

5. Set the right version for the CustomResourceDefinitionSchemaVersion in the pkg/k8s/client by following these instructions:

   Run ./Documentation/check-crd-compat-table.sh vX.Y

6. Add all modified files using git add and create a commit with the title Prepare for release v1.0.3.

7. Prepare a pull request for the changes:

   contrib/release/submit-release.sh

8. Follow standard procedures to get the aforementioned PR merged into the desired stable branch. See Submitting a pull request for more information about this process.

9. Checkout out the stable branch and pull your merged changes:

   git checkout v1.0; git pull

10. Create and push release tags to GitHub:

    contrib/release/tag-release.sh

    Note

    There are two tags that correspond to the same release because GitHub recommends using vx.y.z for release version formatting, and ReadTheDocs, which hosts the Cilium documentation, requires the version to be in format x.y.z For more information about how ReadTheDocs does versioning, you can read their Versions Documentation.

11. Approve the release from the Release Image build UI.

12. Once the release images are pushed, pull the image digests and prepare a PR with the official release image digests:

    contrib/release/post-release.sh <URL of workflow run from the release link above>

    This will leave a file with the format digest-vX.Y.Z.txt in the local directory which can be used to prepare the release in the next step.

13. Prepare Helm changes for the release using the Cilium Helm Charts Repository and push the changes into that repository (not the main cilium repository):

    ./prepare_artifacts.sh /path/to/cilium/repository/checked/out/to/release/commit
    git push

14. Prepare Helm changes for the dev version of the branch using the Cilium Helm Charts Repository for the vX.Y helm charts, and push the changes into that repository (not the main cilium repository):

    In the cilium/cilium repository:

    1. git checkout vx.y -b vx.z-dev
    2. Change the VERSION file to x.y-dev
    3. Run make -C install/kubernetes

    In the cilium/charts repository:

    ./prepare_artifacts.sh /path/to/cilium/repository/checked/out/to/release/commit
    git push

    After pushing you can revert all the changes made in the local branch x.y-dev from cilium/cilium.

15. Wait for the Cilium Helm Charts Workflow to successfully deploy a cluster using the new Helm charts.

16. Publish a GitHub release:

    Following the steps above, the release draft will already be prepared. Preview the description and then publish the release.

    1. Copy the official docker manifests for the release from the previous step into the end of the Github release announcement.

17. Announce the release in the #general channel on Slack. Sample text:

    :cilium-new: **Announcement:** Cilium vX.Y.Z has been released :tada:
    <If security release or major bugfix, short summary of fix here>
    For more details, see the release notes:
    https://github.com/cilium/cilium/releases/tag/vX.Y.Z

18. Create a new git branch based on the master branch to update README.rst:

    $ git checkout -b pr/bump-readme-vX.Y.Z origin/master
    $ contrib/release/bump-readme.sh
    $ # (Commit changes & submit PR)

19. Bump the version of Cilium used in the Cilium upgrade tests to use the new release

    Please reach out on the #development channel on Slack for assistance with this task.

20. Update the stable tags for cilium, cilium-operator, cilium-operator-aws, cilium-operator-azure, cilium-operator-generic, cilium-docker-plugin, hubble-relay and clustermesh-apiserver on DockerHub, for the latest version of Cilium. For example, if the latest version is 1.8, then for all patch releases on the 1.8 line, this step should be performed. Once 1.9 is out for example, then this is no longer required for 1.8 or earlier releases.

    contrib/release/bump-docker-stable.sh X.Y.Z

21. Check if all docker images are available before announcing the release:

    make -C install/kubernetes/ check-docker-images

22. Update the following external tools and guides to point to the released Cilium version. This step is only required on a new minor release like going from 1.8 to 1.9.

    • kubeadm
    • kops
    • kubespray