Release Process

This section describes how to create a Submariner product release. It is assumed that you are familiar with the various Submariner projects and their repositories and are familiar with Git and GitHub.

Project dependencies

The Submariner projects have a dependency hierarchy with respect to their Go libraries and Docker images. Therefore the releases for each individual project must be created in a specific order.

The Go dependency hierarchy flow is as follows:

shipyard <- admiral <- [submariner, lighthouse] <- submariner-operator

Note that the submariner and lighthouse projects are siblings and thus do not depend on one another. Also the submariner-operator components expect that lighthouse and submariner are aligned on the same exact version.

The Docker image dependency hierarchy flow is as follows:

subctl binary <- shipyard dapper base image <- [admiral, submariner, lighthouse, submariner-operator]

The Dapper base image that is provided by shipyard for building and E2E tests in all of the other projects pulls in the subctl binary.

Release versions

The vx.x.x version format is used for the git projects while x.x.x is used for Docker images.

The typical workflow is to first create release candidate(s) for testing before creating the final release. The suggested naming convention is to append -rcN to the final version, for example v0.8.0-rc0, v0.8.0-rc1 etc.

Sometimes you may want to create a specific project release for testing prior to creating a release candidate. In this case, the suggested naming convention is to append -preN.

Create Submariner product release

The following sections outline the steps to be taken in order to create a full Submariner product release. As an example, we’ll use version v0.8.0.

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.

Step 1: Create release for the shipyard project

Navigate to the releases repository and fork it.

  1. Create a new branch for the intended release.

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

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

    version: v0.8.0
    name: 0.8.0
    #pre-release: true
    status: shipyard
    components:
      shipyard: <hash goes here>
    
  4. Create a link for the file to make it the target release. This file is used by the CI jobs.

    ln -s v0.8.0.yaml target
    
  5. Commit the new files, create a new pull request, and have it reviewed and merged.

Once the pull request is merged, it will trigger a CI job to create a shipyard release and build the Dapper base image. In addition, it creates pull requests in the projects that consume shipyard to pin them to the new version in preparation for the subsequent steps.

On successful completion, the generated image version (0.8.0) should be available on Quay here:

https://quay.io/repository/submariner/shipyard-dapper-base?tab=tags

Step 2: Create release for the admiral project

Once the pull request to pin the admiral project to the new shipyard version is merged, we can proceed to updating the release YAML file to create an admiral release.

  1. On your releases repository fork, you can either reuse the previous branch or create a new one. For the former, be sure to first rebase the branch on the latest upstream.

  2. 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>
    
  3. Commit the modified file, create a new pull request, and have it reviewed and merged.

Once the pull request is merged, it will trigger a CI job to create an admiral release and pull requests in the consuming projects to pin them to the new version in preparation for the subsequent steps.

Step 3: Create releases for the lighthouse and submariner projects

Once the pull requests to pin the lighthouse and submariner projects to the new admiral version are merged:

  1. On your releases repository fork, either reuse the previous branch or create a new one.

  2. Edit the release yaml file (v0.8.0.yaml). Update the status field to projects and add the submariner and lighthouse components with their latest commit ID hashes:

    -status: admiral
    +status: projects
     components:
       shipyard: <hash goes here>
       admiral: <hash goes here>
    +  lighthouse: <hash goes here>
    +  submariner: <hash goes here>
    
  3. Commit the modified file, create a new pull request, and have it reviewed and merged.

Once the pull request is merged, it will trigger a CI job to create lighthouse and submariner releases and a pull request to pin the consuming submariner-operator project to the new version.

On successful completion, the new image versions (0.8.0) should be available on Quay.

For submariner:

https://quay.io/repository/submariner/submariner?tab=tags
https://quay.io/repository/submariner/submariner-route-agent?tab=tags
https://quay.io/repository/submariner/submariner-globalnet?tab=tags
https://quay.io/repository/submariner/submariner-networkplugin-syncer?tab=tags

For lighthouse:

https://quay.io/repository/submariner/lighthouse-agent?tab=tags
https://quay.io/repository/submariner/lighthouse-coredns?tab=tags

Step 4: Create the product release

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

  1. On your releases repository fork, either reuse the previous branch or create a new one.

  2. Edit the release yaml file (v0.8.0.yaml). Update the status field to released and 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>
       lighthouse: <hash goes here>
       submariner: <hash goes here>
    +  submariner-charts: <hash goes here>
    +  submariner-operator: <hash goes here>
    
  3. Commit the modified file, create a new pull request, and have it reviewed and merged.

Once the pull request is merged, it will trigger a CI job to generate and tag the submariner-operator image which should be made available on Quay here:

https://quay.io/repository/submariner/submariner-operator?tab=tags

The final product release will be created on the releases repository with a job triggered to publish the subctl binaries for the various platforms. These should be listed under the Assets section for the new release. If not then the job failed so correct the issue and re-run the job.

If the release wasn’t marked as a pre-release, the 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: Add release notes

If this is a final release, add a section for it on this website’s release notes page.

  1. Clone the submariner-website project.

  2. Open src/content/releases/_index.en.md and make changes.

  3. Commit the changes, create a pull request, and have it reviewed and merged.

Alternatively you can edit the file and create a pull request directly on GitHub here

Step 6: Verify the release

You can follow any of the quick start guides.

Step 7: Update the Submariner Operator on OperatorHub.io

The community-operators Git repository is the 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)

Here we are going to update the Submariner Operator on OperatorHub.io. OpenShift users will find the Operator in the official Red Hat catalog.

To publish the Submariner Operator to the community, perform the following steps:

  1. Clone the submariner-operator project

  2. Make sure you have operator-sdk v1 installed on your machine otherwise follow this guide

  3. Generate new package manifests by running the command:

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

    the generated package output should be located in /packagemanifests/${VERSION}/

  4. Fork and clone community-operators project.

  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 the command: 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 community-operators

Step 8: Announce the release

Via E-Mail

Via Twitter