These docs describe how to create a Submariner release.
Submariner’s projects have a dependency hierarchy among their Go libraries and container images, which drives their release order.
The Go dependency hierarchy is:
shipyard <- admiral <- [submariner, lighthouse, cloud-prepare] <- submariner-operator <- subctl
The container image dependency hierarchy is:
subctl binary <- shipyard-dapper-base image <- [admiral, cloud-prepare, submariner, lighthouse, submariner-operator]
Projects in brackets are siblings and do not depend on each other. Dependencies of siblings require all siblings to have aligned versions.
Version numbers are required to be formatted following the schema norms where they are used.
vx.y.z (example: v0.8.0)x.y.z (example: 0.8.0)release-x.y (example: release-0.8)-mN starting at 1 (example: v0.8.0-m1)-rcN starting at 0 (example: v0.8.0-rc0)-preN starting at 0 (example: v0.8.0-pre0).N starting at 1 (example: v0.8.0-m1.1)The following sections are an ordered series of steps to create a Submariner release.
The release process is mostly automated and uses a YAML file created in the releases repository that describes the release. This file is updated for each step in the release process.
Once the changes for a step are reviewed and merged, a CI job will run to create the release(s) for the step and create the required pull requests in preparation for the next step to be reviewed and merged. Once all these pull requests have been merged, you can continue onto the next step.
For most projects, after a release is created, another job will be initiated to build release artifacts and publish to Quay. This will take several minutes. You can monitor the progress from the project’s main page. In the branches/tags pull-down above the file list heading, select the tag for the new version. A small yellow circle icon should be present to the right of the file list heading which indicates a job is in progress. You can click it to see details. There may be several checks for the job listed but the important one is “Release Images”. When complete, the indicator icon will change to either a green check mark on success or a red X on failure. A failure likely means the artifacts were not published to Quay, in which case select the failed check, inspect the logs, correct the issue and re-run the job.
If you’re creating a release meant for general consumption, not a milestone or release candidate, release notes must also be created.
It is expected that release notes for any given release will accumulate on the corresponding release-notes-... branch. Once
the release is ready, a new branch should be pulled from this release note branch, named merge-release-notes-... with the full version
(e.g. merge-release-notes-0.15.2); a PR can then be opened on devel using this branch. In most cases conflicts will need to be
resolved before the branch can be merged.
The release notes are maintained in reverse chronological order. Each version should have its release date added in the release note merge PR.
Our GitHub configuration requires a rebase before merging PRs, which means we need to use git rebase instead of git merge.
See the 0.16.0 PR for an example. If additional changes need to be added,
they should be added to the release notes branch first. If the initial PR is still pending, they can then be rebased onto the PR’s branch.
If the initial PR has been merged, they can be rebased onto devel and submitted with an additional PR.
Verify that all dependencies are up to date before branch cutting at the first release candidate. See the CI Maintenance docs for details about versions that must be manually maintained.
Before starting the release process, check the corresponding release issue for dependent PRs or issues; these are PRs which are supposed to be reviewed, and issues which are supposed to be addressed, before the release starts.
Most of the release can be done in a series of mostly-automated steps. After each step, a Pull Request is sent with the correct YAML
content for the release, this needs to be reviewed. Once the pull request is merged, the release process will continue automatically
and the next step can be initiated shortly after making sure the release jobs on the releases and any participating repositories are done.
Starting with 0.13, when creating a release for a stable version (release-<major>.<minor>),
the make release commands must be run on a branch based off the associated stable release branch.
The GITHUB_TOKEN environment variable in the shell you’re using for the automation must be set to a
Personal Access Token you create.
The token needs at least public_repo scope for the automated release to work.
export GITHUB_TOKEN=<token>
To run the automated release, simply clone the releases repository and execute:
make release VERSION="0.8.0"
Make sure to specify the proper version you’re intending to release (e.g. for rc0 specify VERSION="0.8.0-rc0").
By default, the action will try to push to the GitHub account used in the origin remote.
If you want to use a specific GitHub account, set GITHUB_ACTOR to the desired account, e.g.
make release VERSION="0.8.0" GITHUB_ACTOR="octocat"
You can run the process without pushing the PR automatically (obviating the need to set GITHUB_TOKEN).
To do so, run the make command with dryrun=true.
The command runs, gathers the data for the release, updates the release YAML and pushes it for review. Once the review process is done, merge the PR. Pull requests will then be created for all dependent projects to update them to the new version. The automation will leave a comment with a list of the version-bump PRs for dependent project in the release PR that was just merged. Make sure all those PRs are merged and their release jobs pass (see the Actions tab of the repository on GitHub) then proceed to the next release phase by running the same command again.
On an rc0 release, stable branches are created for the release across all repositories (including releases).
After the first invocation, the command needs to be run on branches based on the correct stable branch (release-<major>.<minor>).
Once there isn’t anything else to do, the command will inform you. At this point, continue manually with any steps not automated yet, starting with Verify Release.
These instructions are here as a backup in case the automated creation process has problems, and to serve as a guide.
If you’re creating a stable release, you need to create a stable branch for backports in each repository. Milestone releases don’t receive backports and therefore don’t need branches.
The release automation process can create stable branches for you. To do so, navigate to the releases repository.
Create a new file in the releases directory (you can copy the example.yaml file). For our example, we’ll name it v0.8.0.yaml.
Fill in the version/name/branch fields for the release, following the naming scheme below. The status field must be set to
branch for this phase.
version: v0.8.0
name: 0.8.0
branch: release-0.8
status: branch
Commit your changes, create a pull request, and have it reviewed.
Once the pull request is merged, it will trigger a CI job to create the stable branches and pin them to Shipyard on that stable branch.
Navigate to the releases repository.
Create a new file in the releases directory (you can copy the example.yaml file). For our example, we’ll name it v0.8.0.yaml.
Fill in the general fields for the release with the status field set to shipyard. Also add the shipyard component with
the hash of the desired or latest commit ID on which to base the release. To obtain the latest, first navigate to
the Shipyard project. The heading above the file list shows the latest
commit on the devel branch including the first 7 hex digits of the commit ID hash.
If this is not a final release, set the pre-release field to true (that is uncomment the pre-release line below).
This includes release candidates. This is important so it is not labeled as the Latest release in GitHub.
When releasing on a stable branch, make sure to specify the branch as outlined below. Otherwise, omit it.
version: v0.8.0
name: 0.8.0
#pre-release: true
branch: release-0.8
status: shipyard
components:
shipyard: <hash goes here>
Commit your changes, create a pull request, and have it reviewed.
Verify:
releases/release job passed.submariner/shipyard-dapper-base image is on Quay.Pull requests will be created for projects that consume Shipyard to update them to the new version in preparation for the subsequent steps. The automation will leave a comment with a list of them. Make sure all those PRs are merged and their release jobs pass.
Once the pull request to pin Admiral to the new Shipyard version is merged, we can proceed to updating the release YAML file to create an Admiral release.
Edit the release yaml file (v0.8.0.yaml). Update the status field to admiral and add the admiral component with
the latest commit ID hash:
-status: shipyard
+status: admiral
components:
shipyard: <hash goes here>
+ admiral: <hash goes here>
Commit your changes, create a pull request, and have it reviewed.
Verify:
Pull requests will be created for projects that consume Admiral to update them to the new version in preparation for the subsequent steps. The automation will leave a comment with a list of them. Make sure all those PRs are merged and their release jobs pass.
Once the pull requests to pin the cloud-prepare, Lighthouse and Submariner projects to the new Admiral version are merged:
Update the release YAML file status field to projects and add the submariner, cloud-prepare and lighthouse components with
their latest commit ID hashes:
-status: admiral
+status: projects
components:
shipyard: <hash goes here>
admiral: <hash goes here>
+ cloud-prepare: <hash goes here>
+ lighthouse: <hash goes here>
+ submariner: <hash goes here>
Commit your changes, create a pull request, and have it reviewed.
Verify:
releases/release job passed.cloud-prepare release was created.submariner/submariner-gateway image is on Quay.submariner/submariner-route-agent image is on Quay.submariner/submariner-globalnet image is on Quay.submariner/submariner-networkplugin-syncer image
is on Quay.submariner/lighthouse-agent image is on Quay.submariner/lighthouse-coredns image is on Quay.Automation will create a pull request to pin submariner-operator to the released versions. Make sure that the PR is merged and the release
job passes.
Once the pull request to pin submariner-operator has been merged, we can create the submariner-operator and submariner-charts releases:
Update the release YAML file status field to installers. Add the submariner-operator and submariner-charts components with their
latest commit ID hashes.
-status: projects
+status: installers
components:
shipyard: <hash goes here>
admiral: <hash goes here>
cloud-prepare: <hash goes here>
lighthouse: <hash goes here>
submariner: <hash goes here>
+ submariner-charts: <hash goes here>
+ submariner-operator: <hash goes here>
Commit your changes, create a pull request, and have it reviewed.
Verify:
submariner-operator release was created.submariner/submariner-operator image is on Quay.Once the submariner-operator and submariner-charts releases are complete, we can create the final release:
Update the release YAML file status field to released. Add the subctl component with its latest commit ID hash.
-status: installers
+status: released
components:
shipyard: <hash goes here>
admiral: <hash goes here>
cloud-prepare: <hash goes here>
lighthouse: <hash goes here>
submariner: <hash goes here>
submariner-charts: <hash goes here>
submariner-operator: <hash goes here>
+ subctl: <hash goes here>
Commit your changes, create a pull request, and have it reviewed.
Verify:
releases/release job passed.subctl artifacts were releasedIf the release wasn’t marked as a pre-release, the releases/release job will also create pull requests in each consuming project to
unpin the Shipyard Dapper base image version, that is set it back to devel. For ongoing development we want each project to
automatically pick up the latest changes to the base image.
You can follow any of the quick start guides.
The k8s-operatorhub/community-operators Git repository is a source for sharing Kubernetes Operators with the broader community via OperatorHub.io. OpenShift users will find Submariner’s Operator in the official Red Hat catalog.
Clone the submariner-operator repository.
Make sure you have operator-sdk v1 installed.
Generate new package manifests:
make packagemanifests VERSION=${new_version} FROM_VERSION=${previous_version} CHANNEL=${channel}
For example:
make packagemanifests VERSION=0.11.1 FROM_VERSION=0.11.0 CHANNEL=alpha-0.11
Generated package manifests should be in /packagemanifests/${VERSION}/.
Fork and clone the k8s-operatorhub/community-operators repository.
Update the Kubernetes Operator:
Copy the generated package from Step 3 into operators/submariner.
Copy the generated package definition /packagemanifests/submariner.package.yaml into operators/submariner/.
Test the Operator by running:
OPP_AUTO_PACKAGEMANIFEST_CLUSTER_VERSION_LABEL=1 OPP_PRODUCTION_TYPE=k8s \
curl -sL https://raw.githubusercontent.com/redhat-openshift-ecosystem/community-operators-pipeline/ci/latest/ci/scripts/opp.sh | bash \
-s -- all operators/submariner/${VERSION}
Preview the Operator on OperatorHub.io
Once everything is fine, review this checklist and create a new PR on k8s-operatorhub/community-operators.
For more details check the full documentation.
Once the release and release notes are published, make an announcement to both Submariner mailing lists.
See the v0.8.0 email example.
Synthesize the release notes and summarize the key points in a Tweet. Link to the release notes for details.
See the v0.8.0 Tweet example.