Release Process

These docs describe how to create a Submariner release.

Ordering

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

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.

Versions

Version numbers are required to be formatted following the schema norms where they are used.

  • Git: vx.y.z (example: v0.8.0)
  • Containers: x.y.z (example: 0.8.0)
  • Stable branches: release-x.y (example: release-0.8)
  • Milestone releases: Append -mN starting at 1 (example: v0.8.0-m1)
  • Release candidates: Append -rcN starting at 0 (example: v0.8.0-rc0)
  • Single-project testing release: Append -preN starting at 0 (example: v0.8.0-pre0)
  • Release errors: Append .N starting at 1 (example: v0.8.0-m1.1)

Create Release

The following sections are an ordered series of steps to create a Submariner relese.

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.

Final Releases: Add Release Notes

If you’re creating a release meant for general consumption, not a milestone or release candidate, release notes must also be created.

It’s best to start working with the broader community to create release notes well before the release. Create a PR to start the process, and work with contributors to get everything added and reviewed.

Stable Releases: Create Stable Branches

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.

  1. 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.

  2. 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
    
  3. 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.

Step 1: Create Shipyard Release

Navigate to the releases repository.

  1. 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.

  2. 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>
    
  3. Commit your changes, create a pull request, and have it reviewed.

  4. Verify:

  5. 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.

Step 2: Create Admiral Release

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.

  1. 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>
    
  2. Commit your changes, create a pull request, and have it reviewed.

  3. Verify:

  4. 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.

Step 3: Create cloud-prepare, Lighthouse, and Submariner Releases

Once the pull requests to pin the cloud-prepare, Lighthouse and Submariner projects to the new Admiral version are merged:

  1. 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>
    
  2. Commit your changes, create a pull request, and have it reviewed.

  3. Verify:

  4. Automation will create a pull request to pin submariner-operator to the released versions. Make sure that PRs is merged and the release job passes.

Step 4: Create Operator and Charts Releases

Once the pull request to pin submariner-operator has been merged, we can create the final release:

  1. Update the release YAML file status field to released. Add the submariner-operator and submariner-charts components with their latest commit ID hashes.

    -status: projects
    +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>
    
  2. Commit your changes, create a pull request, and have it reviewed.

  3. Verify:

  4. If 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.

Step 5: Verify Release

You can follow any of the quick start guides.

Step 6: Update OperatorHub.io

The operator-framework/community-operators Git repository is a source for sharing Kubernetes Operators with the broader community. This repository is split into two sections:

  • Operators for deployment to a vanilla Kubernetes environment (upstream-community-operators). These are shared with the Kubernetes community via OperatorHub.io.
  • Operators for deployment to OpenShift (community-operators)

We only need to update Submariner’s Operator on OperatorHub.io. OpenShift users will find Submariner’s Operator in the official Red Hat catalog.

  1. Clone the submariner-operator repository.

  2. Make sure you have operator-sdk v1 installed.

  3. Generate new package manifests:

    make packagemanifests VERSION=${new_version} FROM_VERSION=${previous_version} CHANNEL=${channel}
    

    Generated package manifests should be in /packagemanifests/${VERSION}/.

  4. Fork and clone the operator-framework/community-operators repository.

  5. Update the Kubernetes Operator:

    • Copy the generated package from Step 3 into upstream-community-operators/submariner
    • Copy the generated package definition /packagemanifests/submariner.package.yaml into upstream-community-operators/submariner/
    • Test the Operator by running: make operator.test OP_PATH=upstream-community-operators/submariner
    • Preview the Operator on OperatorHub.io
    • Once everything is fine, review this checklist and create a new PR on operator-framework/community-operators

Step 7: Announce Release

E-Mail

Once the release and release notes are published, make an announcement to both Submariner mailing lists.

See the v0.8.0 email example.

Twitter

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.