diff --git a/cspell.config.yaml b/cspell.config.yaml index fc734d3c..76005a8b 100644 --- a/cspell.config.yaml +++ b/cspell.config.yaml @@ -5,6 +5,10 @@ dictionaryDefinitions: - name: errno path: docs/dicts/errno.dict addWords: true + - name: misc + path: docs/dicts/misc.dict + addWords: true dictionaries: - s3gw - errno + - misc diff --git a/docs/decisions/0007-release-process.md b/docs/decisions/0007-release-process.md index 419b3d5e..716b9422 100644 --- a/docs/decisions/0007-release-process.md +++ b/docs/decisions/0007-release-process.md @@ -1,4 +1,16 @@ -# Context and Problem Statement +# Release Process + +## Note Before + +This document is superseded by three different ADRs, covering the same topics +and expanding them: [Release Methodology][adr_methodology], +[Release Steps][adr_steps], and [Release Testing][adr_testing]. + +[adr_methodology]: /docs/decisions/0015-release-methodology.md +[adr_steps]: /docs/decisions/0016-release-steps.md +[adr_testing]: /docs/decisions/0017-release-testing.md + +## Context and Problem Statement Releasing is an essential process for the `s3gw` process. Given the project is composed by various sub-projects, that need to be prepared, tested, and diff --git a/docs/decisions/0015-release-methodology.md b/docs/decisions/0015-release-methodology.md new file mode 100644 index 00000000..417b8edc --- /dev/null +++ b/docs/decisions/0015-release-methodology.md @@ -0,0 +1,180 @@ +# Release Methodology for the s3gw project + +## Context and Problem Statement + +Releasing is an essential process for the `s3gw` project. Given the project is +composed by various sub-projects, that need to be prepared, tested, and +eventually released, the Release Process is not trivial. + +This document defines and agrees on the Release Methodology for the `s3gw` +project, and results from splitting the [Release Process ADR][process_adr] in +three documents: methodology (this document), [Release Steps][steps_adr], and +[Release Testing][testing_adr]. + +This document supersedes the [Release Process ADR][process_adr]. + +## Definitions + +Throughout this document we will often refer to certain things or terms. Below +we define what they mean. + +- Version: the state of a given project, at a specific point in time. + +- Release Candidate: the tentative set of deliverables from the various `s3gw` + sub-projects' repositories at a certain version. It may become the final Release. + +- Release: the set of deliverables from the various `s3gw` sub-projects' + repositories at a certain version, published, and accompanied by a + Release Statement. + +- Release Statement: a document associated with a given Release, detailing the + version being released, and a Changelog. + +- Changelog: a list of significant changes that merit being communicated to + stakeholders in a human-consumable format. + +- Release Pipeline: the set of automated workflows triggered on a specific + moment, resulting in a set of containers or artifacts to be released. + +- Release Branch: the state of a given project's development branch at a given + point in time, as a separate named branch in said project's git repository. + +- Backport: the act of applying a patch to a Release Branch originated in a + more recent Release Branch or the development branch. + +- Quay: the current container registry of choice, found at [https://quay.io][quay_url]. + +## Architecture of a Release + +The `s3gw` project is composed by multiple sub-projects: + +- [`s3gw-ui`][1_1]: The User Interface for `s3gw`. +- [`s3gw-charts`][1_2]: Containing the Helm Chart to deploy `s3gw` in a Kubernetes + context. +- [`s3gw`][1_3]: Where most of our tooling and infrastructure scripts live. +- [`ceph`][1_4]: Where the core backend of `s3gw` lives. +- [`cosi-driver`][1_5]: The COSI driver for Kubernetes. + +Releasing `s3gw` is essentially a coordinated process with all the sub-projects, +which need to be prepared at different stages. + +For instance, while the `s3gw-ui`, and `ceph` sub-projects can be +prepared independently, the `s3gw-charts` sub-project requires all pieces to be +in place before the final Release is performed. This stems from the Helm Chart +we provide depending on the various containers being published to Quay; +otherwise, the chart being released would point to unavailable containers. + +### Versioning + +Each release follows [Semantic Versioning][1_6], with versions being in the format +`vX.Y.Z`. + +When dealing with the individual sub-projects' repositories, we use +`s3gw-vX.Y` for release branches and `s3gw-vX.Y.Z` for version tags. +The `s3gw-` prefix in the sub-projects is needed to avoid naming conflicts with +existing tags in the `ceph` repository. +It is particularly important to understand the difference between a release +branch and a version tag. + +A release branch represents the tree upon which the release `vX.Y` is based on, +and once created becomes immutable except for bug fixes (by backporting from the +main development branch). The version tags specify the point at which a given +release branch is released. A release branch may have multiple version tags +throughout the duration of its support lifecycle, as bug fixes are backported to +that particular release. + +### Branching + +A release represents a point in time of each sub-project's repositories. To keep +track of the state of a sub-project's state at that point in time, we rely on +branches. This allows us to bound the scope of a specific release, and makes +maintaining a release easier, especially when we need to release one or more +patch versions on top of the initial release version. + +``` + main s3gw-vX.Y branch + | | + G o + | | + F F' + | | + E o + | | + D E' + | .--' s3gw-vX.Y initial branch + |/ + C + | + B + | + A +``` + +The diagram above represents the branching out of version `vX.Y` from the main +branch for a given sub-project's repository. As one can see, version `X.Y.0` is +released based on the initial branched off history, containing patches `A`, `B`, +and `C`, plus a backport of patch `E`. Later on, version `X.Y.1` is released +containing an additional backport for patch `F`. Both these backports are +assumed to be bug fixes. We thus maintain a stable source of truth for version +`X.Y`, while being able to release versions of said branch at different points +in time. + +### Release Candidate + +Once we branch out the main branch to a release branch `s3gw-vX.Y`, we have a +given state with which we are comfortable but that still needs to be validated +prior to being released. This validation includes several automated and manual +tests, which are described in [Release Testing][testing_adr], but will require release +containers and artifacts to be built. These will be automatically built by our +infrastructure, but require nonetheless a tag to be associated with it. + +Given we can't simply create a version tag for something that hasn't been +validated, we will rely on release candidates instead. Much like a version tag, +a release candidate specifies that a given point in time of a particular release +branch is considered close enough to being released, and takes the form of a tag +in the format `s3gw-vX.Y.Z-rcN`, with `N` being the number of the release +candidate for version `X.Y.Z`, in ascending fashion. As an example, take the +diagram below. + +``` + main s3gw-vX.Y branch + | | + G o + | | + F F' + | | + E o + | | + | E' + D | + | o + | / + |/ + C + | + B + | + A +``` + +In this example we can see that, upon branching off from main, we create a +`s3gw-vX.Y.0-rc1` tag, which will trigger our infrastructure automation and +build the various artifacts needed for a release. In this case we must have +identified a problem, because we had to apply a backport `E'` to the release +branch. This would have led us to create a new release candidate +`s3gw-vX.Y.0-rc2`, which upon validation was deemed correct and released as +`s3gw-vX.Y.0`. Later on we must have found that a new bug fix was required, had +patch `F'` backported, and a new release candidate for version `X.Y.1` was +created, `s3gw-vX.Y.1-rc1`. Once this release candidate was properly validated, +version `vX.Y.1` was released. + +[process_adr]: /docs/decisions/0007-release-process.md +[steps_adr]: /docs/decisions/0016-release-steps.md +[testing_adr]: /docs/decisions/0017-release-testing.md +[quay_url]: https://quay.io +[1_1]: https://github.com/aquarist-labs/s3gw-ui/ +[1_2]: https://github.com/aquarist-labs/s3gw-charts/ +[1_3]: https://github.com/aquarist-labs/s3gw/ +[1_4]: https://github.com/aquarist-labs/ceph/ +[1_5]: https://github.com/aquarist-labs/s3gw-cosi-driver +[1_6]: https://semver.org/ diff --git a/docs/decisions/0016-release-steps.md b/docs/decisions/0016-release-steps.md new file mode 100644 index 00000000..81d983a0 --- /dev/null +++ b/docs/decisions/0016-release-steps.md @@ -0,0 +1,515 @@ +# Release Steps for the s3gw project + +## Context and Problem Statement + +Releasing is an essential process for the `s3gw` project. Given the project is +composed by various sub-projects, that need to be prepared, tested, and +eventually released, the Release Process is not trivial. + +This document defines and agrees on the steps required to release the `s3gw` +project, and results from splitting the [Release Process ADR][process_adr] in +three documents: [Release Methodology][methodology_adr], Release Steps (this +document), and [Release Testing][testing_adr]. + +This document supersedes the [Release Process ADR][process_adr]. + +## Note Before + +It is important to be familiar with the various concepts defined in the +[Release Methodology ADR][methodology_adr], and the release validation process +described in [Release Testing][testing_adr]. + +There are five repositories involved in the release process: + +- [`s3gw`][repo_s3gw]: Where most of our tooling and infrastructure scripts live. +- [`s3gw-ui`][repo_ui]: The User Interface for `s3gw`. +- [`s3gw-charts`][repo_charts]: Containing the Helm Chart to deploy `s3gw` in a + Kubernetes context. +- [`ceph`][repo_ceph]: Where the core backend of `s3gw` lives. +- [`cosi-driver`][repo_cosi]: The COSI driver for Kubernetes. + +Of these, we refer to `s3gw` as the project's repository, and the remaining four +to be sub-projects of the `s3gw` project. + +### [Note on the `s3gw-charts` repository](s3gw-charts-note) + +The Helm Chart requires the containers to be available for download from Quay +before it can be published. Therefore, we can't trigger the `s3gw-charts` +repository release workflow before the various containers have been built. + +In turn, the containers are only built during the `s3gw` repository's release +workflow. + +However, to ensure the consistency of the release branch (and its various +release versions), we must guarantee that the `charts` submodule in the `s3gw` +repository is pointing to a commit representing the Helm Chart at the specific +version we are releasing. + +This becomes a bit of a _chicken and egg_ problem: we need to have a commit in +the `s3gw-charts` repository we can point to from the `s3gw` repository, so we +can build the containers, but we also need the containers first before we can +trigger the release workflow in `s3gw-charts`. + +This is overcome by having the release workflow being triggered _on push_ to +branches following a specific format in the `s3gw-charts` repository, but using +a different branch to perform all required actions until then. + +Thanks to `git`'s nature, as long as the commit is _somewhere_ in the +repository, regardless of branch, it is a valid commit we can point to from the +`s3gw` repository's `charts` submodule. + +Therefore, we will be using branches in the format `s3gw-vX.Y` for preparatory +release actions, and a branch in the format `vX.Y` when it is time to trigger +the chart's release workflow. Keep this in mind while following the release +process steps. + +## Step-by-Step Release Process + +This section describes the release process, step by step. For a condensed +version of the release process, command by command, see the later section +[Manual Process](#manual-process). + +For example purposes, we assume we are releasing version `0.99.0`. + +1. For each sub-project repository, and for the `s3gw` repository, branch off + `main` to a new release branch. This can be achieved via the GitHub web + UI[^1], or by pushing the new branch to the repository via the CLI[^2]. + Release branch names follow the `s3gw-vX.Y` convention; i.e., `s3gw-v0.99`. + +2. Ensure all sub-project repositories are checked out at the `s3gw-v0.99` + branch. Assuming `upstream` as the source remote, and that the branching was + performed through the GitHub web UI (i.e., not manually through the CLI), + checking out looks like the following: + + ```shell + git checkout upstream/s3gw-v0.99 -b s3gw-v0.99 + ``` + +3. In the `s3gw-charts` repository, on branch `s3gw-v0.99`, update the Chart + version to `0.99.0`. The Chart file can be found in + `charts/s3gw/Chart.yaml`. + +4. Stage and commit the updated Chart. + + ```shell + git add charts/s3gw/Chart.yaml + git commit --signoff --gpg-sign -m "Release v0.99.0" + ``` + +5. For each sub-project, tag the release branch as a release candidate[^3]. Keep + in mind that when tagging, creating a signed and annotated tag[^4] is crucial. + + ```shell + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" s3gw-v0.99.0-rc1 + ``` + +6. For each sub-project, push the `s3gw-v0.99` branch, as well as the newly + created tag. + + ``` + git push upstream s3gw-v0.99 + git push upstream --tags s3gw-v0.99.0-rc1 + ``` + +7. In the `s3gw` repository's newly created release branch, update the various + sub-projects' state to reflect the now existing tags. This can be achieved in + by checking out the appropriate tag on each individual sub-project's + submodule directory. A commit will be necessary to persist the + changes. The following shows a trimmed example of what to do. + + ```shell + # in the root of the s3gw repo, branch s3gw-v0.99 + cd ceph/ + git remote update + git checkout origin/s3gw-v0.99.0-rc1 + cd .. + git add ceph/ + + # repeat for the several other sub-projects + ``` + +8. Write the release notes for `v0.99.0` into + `docs/release-notes/s3gw-v.99.0.md` and update the `latest` symlink in + `docs/release-notes` to point to the newly created file. + +9. Commit the changes required for the release candidate. + + ```shell + git commit --signoff --gpg-sign -m "Release Candidate 1 for v0.99.0" + ``` + +10. Tag the `s3gw` repository with the appropriate release candidate tag. + It is important, that this tag contains only the `vX.Y.Z` version. + + ```shell + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" v0.99.0-rc1 + ``` + +11. Push the release branch and tag. This will trigger the release pipeline, + creating the various release artifacts and a draft release. + + ```shell + git push upstream s3gw-v0.99 + git push upstream --tags v0.99.0-rc1 + ``` + +12. Once the containers have been created and pushed to Quay, it's time to start + validating the release candidate. Please refer to the + [Release Testing ADR][testing_adr] before continuing. + +13. If any patches needed to be backported at some point since the last release + candidate, please go back to `step 5.` and increase the release candidate + version by `1` (i.e., `-rc2`, `-rc3`, etc.). Even if a particular sub-project + repository has not been changed, it is still crucial to tag it with the new + release candidate version, for consistency across repositories. + +14. Assuming everything goes well, we can now go through `step 5.` but, instead + of tagging for a release candidate version, we will be tagging for the + release version. + + ```shell + git tag --annotate --sign -m "Release v0.99.0" v0.99.0 + git push upstream --tags v0.99.0 + ``` + + By pushing the branch with the release tag, we will trigger the release + workflow that will build the various release artifacts and publish the + containers on Quay. + +15. Once the final release containers have been built, it is time to deal with + the `s3gw-charts` repository and trigger the Helm Chart release (if you are + unfamiliar with the problematic, please refer to the + [this section](#s3gw-charts-note)). To do this, we simply push the contents + of our `s3gw-v0.99` branch to `v0.99`. + + ```shell + git push upstream s3gw-v0.99:v0.99 + ``` + +16. As soon as the Helm Chart has been published on [ArtifactHub][artifacthub], + we are ready to finalize the release. + + During the release workflow triggered in `step 14.`, a draft release was + created for `v0.99.0`. This can be found in the [releases page][releases] in + the `s3gw` GitHub repository web page. + + This release draft was built using the release notes file in the + `s3gw-v0.99` branch, and will be pre-populated. Editing may be required to + make it presentable. + + It can now be published. + +17. Check if there are release drafts for previous Release Candidates. If so, + remove them. + +18. It is now time to shout about the latest release from the rooftops. A + release announcement should be sent to the various communication channels + being used by the project. + + - rancher-users Slack channel `#s3gw` + - SUSE Slack channel `#discuss-s3gw` + - project mailing list at `s3gw@suse.com` + + The format for the release announcement can be found in the + [Release Announcement][#announcement] section. + +19. Finally, we need to synchronize the `main` branches of the `s3gw` and the + `s3gw-charts` repositories with their respective `s3gw-v0.99` branches, so + the individual `main` branches are up-to-date. This means cherry-picking the + individual release and release candidate commits into `main`. You will need + to check for the individual commits SHA1s yourself; you may ask for help + from the team if you are unsure what to do. A good rule of thumb is to + cherry-pick those commits that would make the `main` branches represent the + latest release. For instance, in the `s3gw` repository, this will likely + involve the commits updating the submodules and the one adding the release + notes for `v0.99.0`; on the `s3gw-charts` repository, it will mean the + commit updating the chart version to `0.99.0`. + +[^1]: + For example, for a `v0.99.0` release, for the `s3gw` + repository, go to the [Branches Page][branches] and click the `New branch` + button. + +[^2]: For example, for a `v0.99.0` release, `git branch --copy main s3gw-v0.99` +[^3]: + Please refer to [Git's Documentation][git_tags] for more information on + Tagging. + +[^4]: + Annotated tags keep information about creation time, author, a message, + are checksummed, and can be signed, being full fledged git objects. For a + release it is important to keep this information. A lightweight tag, on the + other hand, is often used for temporary purposes. + +## [Manual Process](manual-process) + +Assuming we are releasing version `0.99.0`, for every repository, first we need +to branch off `main` to a new branch `s3gw-v0.99.0`. We can do this via the +GitHub web UI or via the CLI. This document describes doing it via the CLI. + +1. Branch off `main` into `s3gw-v0.99.0` + + ```shell + cd /aquarist-labs/s3gw-ceph.git + git remote update upstream + git checkout upstream/main -b s3gw-v0.99.0 + + cd /aquarist-labs/s3gw-ui.git + git remote update upstream + git checkout upstream/main -b s3gw-v0.99.0 + + cd /aquarist-labs/s3gw-cosi-driver.git + git remote update upstream + git checkout upstream/s3gw -b s3gw-v0.99.0 + + cd /aquarist-labs/s3gw-charts.git + git remote update upstream + git checkout upstream/main -b s3gw-v0.99.0 + + cd /aquarist-labs/s3gw.git + git remote update upstream + git checkout upstream/main -b s3gw-v0.99.0 + ``` + +2. Update the Helm Chart version in + `/aquarist-labs/s3gw-charts.git/charts/s3gw/Chart.yaml` to `0.99.0` + +3. Stage and commit the updated Chart + + ```shell + cd /aquarist-labs/s3gw-charts.git + git add charts/s3gw/Chart.yaml + git commit --signoff --gpg-sign -m "Release v0.99.0" + ``` + +4. For each sub-project, tag the release branch as a release candidate, and push + to upstream + + ```shell + cd /aquarist-labs/s3gw-ceph.git + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" s3gw-v0.99.0-rc1 + git push upstream s3gw-v0.99 + git push upstream --tags s3gw-v0.99.0-rc1 + + cd /aquarist-labs/s3gw-ui.git + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" s3gw-v0.99.0-rc1 + git push upstream s3gw-v0.99 + git push upstream --tags s3gw-v0.99.0-rc1 + + cd /aquarist-labs/s3gw-cosi-driver.git + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" s3gw-v0.99.0-rc1 + git push upstream s3gw-v0.99 + git push upstream --tags s3gw-v0.99.0-rc1 + + cd /aquarist-labs/s3gw-charts.git + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" s3gw-v0.99.0-rc1 + git push upstream s3gw-v0.99 + git push upstream --tags s3gw-v0.99.0-rc1 + ``` + +5. In the `s3gw` repository, update the submodules in the `s3gw-v0.99` branch to + match the tags that were created. + + ```shell + cd /aquarist-labs/s3gw.git + + cd ceph/ + git remote update origin + git checkout s3gw-v0.99.0-rc1 + cd .. + git add ceph/ + + cd ui/ + git remote update origin + git checkout s3gw-v0.99.0-rc1 + cd .. + git add ui/ + + cd cosi-driver/ + git remote update origin + git checkout s3gw-v0.99.0-rc1 + cd .. + git add cosi-driver/ + + cd charts/ + git remote update origin + git checkout s3gw-v0.99.0-rc1 + cd .. + git add charts/ + ``` + +6. Write the release notes for `v0.99.0` (e.g., `/tmp/s3gw-v0.99.0.md`) + + ```shell + cd /aquarist-labs/s3gw.git/docs/release-notes + cp /tmp/s3gw-v0.99.0.md s3gw-v0.99.0.md + ln -fs s3gw-v0.99.0.md latest + git add s3gw-v0.99.0.md + git add latest + ``` + +7. Commit changes required for the release candidate, and tag the commit. Note + that the tag format for the `s3gw` repository is in the `vX.Y.Z` format + instead of `s3gw-vX.Y.Z` as for the remaining repositories + + ```shell + cd /aquarist-labs/s3gw.git + git commit --signoff --gpg-sign -m "Release Candidate 1 for v0.99.0" + git tag --annotate --sign -m "Release Candidate 1 for v0.99.0" v0.99.0-rc1 + ``` + +8. Push the release branch and the tag + + ```shell + cd /aquarist-labs/s3gw.git + git push upstream s3gw-v0.99.0 + git push upstream --tags v0.99.0-rc1 + ``` + +9. Once the release workflow finishes, and the containers are available in + [s3gw's Quay][quay_s3gw], we can start testing the release candidate. Please + refer to the [Release Testing ADR][testing_adr] for more information + +10. If there is a need for further release candidates, go back to `step 4.`, and + proceed as needed. Otherwise, we can trigger the final release build + + ```shell + cd /aquarist-labs/s3gw.git + git tag --annotate --sign -m "Release v0.99.0" v0.99.0 + git push upstream --tags v0.99.0 + ``` + +11. Once the final release containers have been built, we can then trigger the + release workflow for the charts repository + + ```shell + cd /aquarist-labs/s3gw-charts.git + git push upstream s3gw-v0.99:v0.99 + ``` + +12. As soon as the Helm Chart has been published on [Artifact Hub][artifacthub], + we can finalize the release. The next step is to publish the release draft + that was generated, which can be found in the [releases page][releases]. + There may be drafts for the release candidates as well - delete them + +13. Announce the release on the various communication channels. Please refer to + the [Release Announcement][#announcement] section for more information. + +14. Finally, we just synchronize the `main` branches of the `s3gw` and the + `s3gw-charts` repositories with their respective `s3gw-v0.99` branches, so + the individual `main` branches are up-to-date. This means cherry-picking the + individual release and release candidate commits into `main`. You will need + to check for the individual commits SHA1s yourself; you may ask for help + from the team if you are unsure what to do + + ```shell + cd /aquarist-labs/s3gw.git + git checkout upstream/main -b merge_v0.99_into_main + git cherry-pick -x --no-signoff [...] + git push upstream merge_v0.99_into_main + + cd /aquarist-labs/s3gw-charts.git + git checkout upstream/main -b merge_v0.99_into_main + git cherry-pick -x --no-signoff [...] + git push upstream merge_v0.99_into_main + ``` + + And then open a Pull Request on each branch, from their respective + `merge_v0.99_into_main` branches to `main`, and ask for a review. + +## [Release Announcement](announcement) + +### via Slack + +Announce the release of the s3gw in the following Slack channels: + +- SUSE workspace: #discuss-s3gw +- Rancher Users workspace: #s3gw + +``` + It's my pleasure to announce the release of :s3gw: S3 Gateway v0.99.0 :tada: + + This release once again includes a couple of exciting changes, most notably: + + - Refactoring of amazing things :male-mechanic: + - Various UI fixes and improvements :star2: + - Various chart improvements :helm-intensifies: + - More awesomeness :awesome: + + Breaking Changes: + + - The on-disk format of the metadata store has changed. Volumes previously + used with an older version of s3gw are not guaranteed to work with this + and following versions. + + Get the container images from: + + - quay.io/s3gw/s3gw:v0.99.0 + - quay.io/s3gw/s3gw-ui:v0.99.0 + or just use the :helm: chart +``` + +### via Email + +Announce the release via our s3gw mailing list by sending an email to the list: + +``` +To: s3gw@suse.com + +Subject: Release v0.99.0 + + It's my pleasure to announce the release of S3 Gateway v0.99.0 + + This release once again includes a couple of exciting changes, most notably: + + - Refactoring of the amazing things + - Various UI fixes and improvements + - Various chart improvements + - More awesomeness + + Breaking Changes: + + - The on-disk format of the metadata store has changed. Volumes previously + used with an older version of s3gw are not guaranteed to work with this + and following versions. + + Sources for the release are available here[1] + Get the container images from: + + - quay.io/s3gw/s3gw:v0.99.0 + - quay.io/s3gw/s3gw-ui:v0.99.0 + + or just use the helm chart[2] + + [1] https://github.com/aquarist-labs/s3gw/releases/tag/v0.99.0 + [2] https://artifacthub.io/packages/helm/s3gw/s3gw +``` + +### [Sanity Checks](sanity-checks) + +- [ ] `s3gw` container has been published on Quay for `vX.Y.Z`. +- [ ] `s3gw-ui` container has been published on Quay for `vX.Y.Z`. +- [ ] both containers are appropriately tagged with `vX.Y.Z` on Quay. +- [ ] both containers are tagged with `latest` on Quay. +- [ ] `latest` version containers are the same as the `vX.Y.Z` containers on + Quay. +- [ ] Helm Chart has been properly updated for `vX.Y.Z`. +- [ ] Helm Chart for `vX.Y.Z` is visible on [ArtifactHub][10]. This can take + about 20 minutes. +- [ ] The release notes are in place, both on the `s3gw` repository's `main` + branch and on the `s3gw-vX.Y` branch. + +[process_adr]: /docs/decisions/0007-release-process.md +[methodology_adr]: /docs/decisions/0015-release-methodology.md +[testing_adr]: /docs/decisions/0017-release-testing.md +[quay_url]: https://quay.io +[repo_ui]: https://github.com/aquarist-labs/s3gw-ui/ +[repo_charts]: https://github.com/aquarist-labs/s3gw-charts/ +[repo_s3gw]: https://github.com/aquarist-labs/s3gw/ +[repo_ceph]: https://github.com/aquarist-labs/ceph/ +[repo_cosi]: https://github.com/aquarist-labs/s3gw-cosi-driver +[artifacthub]: https://artifacthub.io/packages/helm/s3gw/s3gw +[releases]: https://github.com/aquarist-labs/s3gw/releases +[branches]: https://github.com/aquarist-labs/s3gw/branches +[git_tags]: https://git-scm.com/book/en/v2/Git-Basics-Tagging +[s3gw_quay]: https://quay.io/organization/s3gw diff --git a/docs/decisions/0017-release-testing.md b/docs/decisions/0017-release-testing.md new file mode 100644 index 00000000..dac7f1f4 --- /dev/null +++ b/docs/decisions/0017-release-testing.md @@ -0,0 +1,71 @@ +# Testing a release + +## Context and Problem Statement + +Releasing is an essential process for the `s3gw` project. Given the project is +composed by various sub-projects, that need to be prepared, tested, and +eventually released, the Release Process is not trivial. + +This document defines and agrees on the steps required to test the `s3gw` +project, and results from splitting the [Release Process ADR][process_adr] in +three documents: [Release Methodology][methodology_adr], +[Release Steps][release_adr] and Release Testing (this document). + +This document supersedes the [Release Process ADR][process_adr]. + +## Note Before + +This document requires expansion. The whole team is encouraged to enhance this +document with further testing scenarios. + +## Validate deployment via Helm Chart + +1. Ensure a kubernetes distribution with Longhorn and cert-manager installed is available. E.g., + for `k3s`, + + ```shell + curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.24.7+k3s1 sh -s - --write-kubeconfig-mode 644 + sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config + sudo chown my-user:users ~/.kube/config + export KUBECONFIG=~/.kube/config + + kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.3.2/deploy/prerequisite/longhorn-iscsi-installation.yaml + kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.3.2/deploy/longhorn.yaml + + kubectl create namespace cert-manager + helm repo add jetstack https://charts.jetstack.io + helm repo update + helm install cert-manager --namespace cert-manager jetstack/cert-manager \ + --set installCRDs=true \ + --set extraArgs[0]=--enable-certificate-owner-ref=true + ``` + +2. Follow the Helm chart installation procedure from the `s3gw` + [documentation][helm_install_docs] + +3. Verify the pods are coming up nicely + + ```shell + kubectl get pods -n s3gw + + > NAME READY STATUS RESTARTS AGE + > s3gw-ui-77b7cdf987-c5lvj 1/1 Running 0 33s + > s3gw-5659dbb456-a4fcg 1/1 Running 0 33s + ``` + +4. Check whether the `s3gw-ui` is reachable at the address specified in the + `values.yaml` provided during `helm install`. + +5. Check whether the you can perform actions through the UI, like creating + buckets, uploading objects, listing buckets, etc. + +6. Check whether the `s3gw` service is reachable, test with `s3cmd` or `s3`. + +7. If at any point there's an indication that something is not working right, or + you find a crash, please file an [issue on GitHub][new_issue]. + +[process_adr]: /docs/decisions/0007-release-process.md +[methodology_adr]: /docs/decisions/0015-release-methodology.md +[release_adr]: /docs/decisions/0016-release-steps.md +[helm_install_docs]: https://s3gw-docs.readthedocs.io/en/latest/helm-charts/ +[new_issue]: https://github.com/aquarist-labs/s3gw/issues/new/choose diff --git a/docs/dicts/misc.dict b/docs/dicts/misc.dict new file mode 100644 index 00000000..bc83aeab --- /dev/null +++ b/docs/dicts/misc.dict @@ -0,0 +1 @@ +tada diff --git a/docs/dicts/s3gw.dict b/docs/dicts/s3gw.dict index a126e397..9129a4b8 100644 --- a/docs/dicts/s3gw.dict +++ b/docs/dicts/s3gw.dict @@ -63,3 +63,6 @@ open-iscsi letsencrypt certmanager errno +signoff +kubeconfig +KUBECONFIG