Skip to content

RELEASE.md

Latest commit

 

History

History
178 lines (142 loc) · 8.89 KB

RELEASE.md

File metadata and controls

178 lines (142 loc) · 8.89 KB

Release Process

This details how releases of Gateway API are delivered. This process is exercised by a Release Manager.

Overview

The Gateway API project is an API project that has the following two components:

  • Kubernetes Custom Resource Definitions (CRDs)
  • Corresponding Go API in the form of sigs.k8s.io/gateway-api Go package

This repository is the home for both of the above components.

Versioning strategy

The versioning strategy for this project is covered in detail in the release documentation.

Releasing a monthly version

Starting point

Make sure all the changes that should be part of the monthly release are merged into main.

Tagging the monthly release

Start by tagging the main branch with a tag of the form monthly-YYYY.MM (for example, monthly-2025.11). Push this to GitHub. Later, CI will handle the rest of the release process -- for now, you'll do it by hand.

Building the monthly YAMLs

make build-monthly-yaml

This will use the current date to generate a tag of the form monthly-YYYY.MM (for example, monthly-2025.11), then generate the install YAMLs for the monthly release in release/$TAG-install.yaml. If desired, you can override the tag by setting TAG in your environment before running the command.

Generating the monthly CRD YAML makes changes in the config/crd/experimental/ directory. These changes should not be committed, so make build-monthly-yaml will ask if you want it to use git restore to clean up. Since these are derived objects, typically you would answer "Y" to this question. To prevent the prompt and silently clean up, set MONTHLY_NONINTERACTIVE=true in your environment before running the command.

Once you've generated the monthly YAML, you can create a GitHub release and attach the release/$TAG-install.yaml file to it as an artifact. Mark this release as a prerelease; DO NOT mark it as the latest release.

Writing the Release Changelog

When you create a GitHub release, Git will automatically generate a changelog from the commit messages since the previous release. If there aren't any significant changes in a given monthly, it's OK to just use that autogenerated changelog.

In many cases, though, it can be helpful to write a changelog that's more human-readable. Given the $TAG used for this monthly release as well as the $PREV_TAG used for the previous monthly release, you can get a more complete set of commit messages with:

git log --stat ${PREV_TAG}..${TAG} -- config/crd/experimental

and a full set of diffs with:

git diff ${PREV_TAG}..${TAG} -- config/crd/experimental

This will give you a more complete picture of the changes that went into the monthly release, which you can then summarize in the GitHub release notes. (You won't commit these notes back to the repository: they will only be saved in the GitHub release itself.)

Releasing a new standard-channel version

Writing a Changelog

To simplify release notes generation, we recommend using the Kubernetes release notes generator:

go install k8s.io/release/cmd/release-notes@latest
export GITHUB_TOKEN=your_token_here
release-notes --start-sha EXAMPLE_COMMIT --end-sha EXAMPLE_COMMIT --branch main --repo gateway-api --org kubernetes-sigs

This output will likely need to be reorganized and cleaned up a bit, but it provides a good starting point. Once you're satisfied with the changelog, create a PR. This must go through the regular PR review process and get merged into the main branch. Approval of the PR indicates community consensus for a new release.

Release Steps

The following steps must be done by one of the Gateway API maintainers:

For a PATCH release:

  • Create a new branch in your fork named something like <githubuser>/release-x.x.x. Use the new branch in the upcoming steps.
  • Use git to cherry-pick all relevant PRs into your branch.
  • Update pkg/consts/consts.go with the new semver tag and any updates to the API review URL.
  • Update regex spec.validations.expression in config/crd/standard/gateway.networking.k8s.io_vap_safeupgrades.yaml to match older versions. (Look for a regex like v1.[0-3]., and replace the 3 with the new minor version number -1).
  • Run the following command BASE_REF=vmajor.minor.patch make generate which will update generated docs with the correct version info. (Note that you can't test with these YAMLs yet as they contain references to elements which wont exist until the tag is cut and image is promoted to production registry.)
  • Create a pull request of the <githubuser>/release-x.x.x branch into the release-x.x branch upstream (which should already exist since this is a patch release). Add a hold on this PR waiting for at least one maintainer/codeowner to provide a lgtm.
  • Verify the CI tests pass and merge the PR into release-x.x.
  • Create a tag using the HEAD of the release-x.x branch. This can be done using the git CLI or GitHub's release page.
  • Run the make build-install-yaml command which will generate install files in the release/ directory. Attach these files to the GitHub release.
  • Update the README.md and site-src/guides/index.md files to point links and examples to the new release.

For a MAJOR or MINOR release:

  • Cut a release-major.minor branch that we can tag things in as needed.
  • Check out the release-major.minor release branch locally.
  • Update pkg/consts/consts.go with the new semver tag and any updates to the API review URL.
  • Update regex spec.validations.expression in config/crd/standard/gateway.networking.k8s.io_vap_safeupgrades.yaml to match older versions.
  • Run the following command BASE_REF=vmajor.minor.patch make generate which will update generated docs with the correct version info. (Note that you can't test with these YAMLs yet as they contain references to elements which wont exist until the tag is cut and image is promoted to production registry.)
  • Verify the CI tests pass before continuing.
  • Create a tag using the HEAD of the release-x.x branch. This can be done using the git CLI or GitHub's release page.
  • Run the make build-install-yaml command which will generate install files in the release/ directory. Attach these files to the GitHub release.
  • Update the README.md and site-src/guides/index.md files to point links and examples to the new release.
  • Update the implementation table path (nav.Implementations.Comparison) in the nav of mkdocs.yml to point to the latest release file (for example Implementation Comparison points to implementation-table-v1.2.0.md). Add the now past version under Past Version Comparisons, and edit the text blurb in mkdocs-generate-conformance.py to also reflect the added past version.
  • Update hack/mkdocs/generate.sh and add the new release-x.x to the array of releases.

For an RC release:

  • Update pkg/consts/consts.go with the new semver tag (like v1.2.0-rc1) and any updates to the API review URL.
  • Run the following command make generate which will update generated docs with the correct version info. (Note that you can't test with these YAMLs yet as they contain references to elements which wont exist until the tag is cut and image is promoted to production registry.)
  • Include the changelog update in this PR.
  • Merge the update PR.
  • Tag the release using the commit on main where the changelog update merged. This can be done using the git CLI or GitHub's release page.
  • Run the make build-install-yaml command which will generate install files in the release/ directory.
  • Attach these files to the GitHub release.

Promoting images to production registry

Gateway API follows the standard kubernetes image promotion process described here.

  1. Once the tag has been cut and the image is available in the staging registry, identify the SHA-256 image digest of the image that you want to promote.
  2. Modify the k8s-staging-gateway-api/images.yaml file under kubernetes/k8s.io repository and add the image digest along with the new tag under the correct component.
    1. Currently, the following images are included: admission-server, echo-server
  3. Create a PR with the above changes.
  4. Image will get promoted by automated prow jobs once the PR merges