diff --git a/design/20240518.push-to-multiple-registries.md b/design/20240518.push-to-multiple-registries.md new file mode 100644 index 000000000..260502551 --- /dev/null +++ b/design/20240518.push-to-multiple-registries.md @@ -0,0 +1,289 @@ + + +# Push image artifacts to multiple repositories + + + +- [Release Signoff Checklist](#release-signoff-checklist) +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Stories (Optional)](#user-stories-optional) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Graduation Criteria](#graduation-criteria) + - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) + - [Supported Versions](#supported-versions) +- [Production Readiness](#production-readiness) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) + + +## Release Signoff Checklist + +This checklist contains actions which must be completed before a PR implementing this design can be merged. + + +- [ ] This design doc has been discussed and approved +- [ ] Test plan has been agreed upon and the tests implemented +- [ ] Feature gate status has been agreed upon (whether the new functionality will be placed behind a feature gate or not) +- [ ] Graduation criteria is in place if required (if the new functionality is placed behind a feature gate, how will it graduate between stages) +- [ ] User-facing documentation has been PR-ed against the release branch in [cert-manager/website] + + +## Summary + + +The cert-manager project, along with its sub-projects, currently utilizes the quay.io/jetstack registry for pushing OCI (Open Container Initiative) artifacts. This originates from the project's beginnings under Jetstack. However, to reflect the project's growth and establish a more neutral and independent identity, this proposal recommends adding a new OCI artifact registry location without the Jetstack branding. + +## Motivation + + +The primary motivation for this enhancement is to reinforce the independence and neutrality of the cert-manager project. Originally developed by Jetstack, cert-manager currently pushes OCI artifacts to the quay.io/jetstack registry. As the project has grown and evolved into a community-driven initiative, it is essential to establish a neutral artifact repository that better represents the project's diverse and independent nature. + +### Goals + + +- Decouple the cert-manager project from Jetstack’s branding to highlight its status as a community-driven project. +- Ensure all project documentation reflects the new registry to guide users appropriately without disrupting existing workflows. +- Continue pushing artifacts to the current quay.io/jetstack registry to avoid breaking changes for existing users while transitioning to the new registry. + +### Non-Goals + + +- This proposal does not aim to immediately deprecate the quay.io/jetstack registry but to introduce an additional registry. +- No changes to the functionality or features of cert-manager are included in this proposal. + +## Proposal + + + +### User Stories (Optional) + + + +#### Story 1 + +*As a* new user of cert-manager, *I want to* find clear documentation that directs me to the appropriate registry for downloading OCI artifacts, *so that* I can easily set up and use cert-manager in my environment without confusion about which registry to use. + +Details: + +- The updated documentation prominently lists the new neutral registry URL. +- The documentation includes notes that the artifacts are also available in the quay.io/jetstack registry for backward compatibility. + +#### Story 2 + +*As an* existing user of cert-manager, *I want to* continue receiving updates from the quay.io/jetstack registry while gradually transitioning to the new registry, *so that* my current setup remains functional without immediate changes, giving me time to update my configurations. + +Details: + +- Artifacts continue to be pushed to both the quay.io/jetstack and the new registry. +- A clear migration guide is provided, explaining how to switch to the new registry at a convenient time. + +### Notes/Constraints/Caveats (Optional) + + + +### Risks and Mitigations + + + +*Risk:* The new registry might introduce security vulnerabilities, such as unauthorized access to artifacts. + +*Mitigation:* +- Existing CI/CD will be used to publish images, this is proven and secure. +- The new registry should have the same access control restrictions as the current quay.io/jetstack registry - ensuring that only maintainers have write access. + +## Design Details + + +To implement the transition to a new OCI artifact registry, our existing CI/CD pipeline will be updated to push artifacts to both the existing quay.io/jetstack registry and the new registry. This dual-publishing approach ensures continuity and minimizes disruption for current users. We are considering multiple options for the new registry, with "ghcr.io/cert-manager" (GitHub Container Registry) and "quay.io/cert-manager" being the primary candidates. The final registry will be chosen based on community feedback on this proposal. Regardless of the registry, we will also need to update the CI pipeline to authenticate with the new registry, ensuring secure and seamless artifact uploads. + +Within projects using makefile modules we may need to make changes to the [OCI publish module](https://github.com/cert-manager/makefile-modules/tree/main/modules/oci-publish) to handle cases where we need different auth for different registries. After this, the pushing to multiple destinations is already supported by this module and would be a simple change to the config of each repos. + +A new E2E tests run should be performed by our nightly automation that runs the E2E suite against the new registry, to ensure that everything is working as expected. + +Once the images are being dual published, the official documentation and Helm chart will be updated to reflect the new repository. + +### Test Plan + + +By using existing automation that runs the E2E test suite each night we can add automated tests that will pull from the new registry. This tests multiple versions so is a good baseline that the image can be pulled. + +### Graduation Criteria + + +Since this proposal has no code changes, it does not have any feature flags. However its graduation should be managed. To accomplish this we should do the following: + +Alpha/Beta: +- Start publishing images to the new registry - we document the new registry but do not push it as the new default + +GA: +- Update the official Helm charts to use the new registry +- Update documentation to reflect that the new registry is the preferred one + +The criteria for graduation will be a based off maintainer confidence in the new registry, informed by the E2E test runs using the new registries and any feedback from early adopters. + +### Upgrade / Downgrade Strategy + + +Once we are happy to make this GA the Helm chart will be updated to use the new registry, this will mean that for users using the official Helm chart the change will be automatic. For other users nothing will break by them using the old registry, so they can update their deployment at their own convenience. Furthermore a user could choose to set the registry back to quay.io/jetstack in their Helm configuration if they so choose. + +### Supported Versions + + +N/A + +## Production Readiness + +N/A + +### How can this feature be enabled / disabled for an existing cert-manager installation? + + +N/A + +### Does this feature depend on any specific services running in the cluster? + + +N/A + +### Will enabling / using this feature result in new API calls (i.e to Kubernetes apiserver or external services)? + +N/A + +### Will enabling / using this feature result in increasing size or count of the existing API objects? + + +N/A + +### Will enabling / using this feature result in significant increase of resource usage? (CPU, RAM...) + + +N/A + +## Drawbacks + + +This proposal does not remove or break any functionality for users. For maintainers, pushing to multiple repositories would make gathering pull metrics more complex. + +## Alternatives + + +There are many competing container registries, the two currently in contention (ghcr and quay) were selected because we already have access and availability to push there. They also offer their services for free for open source projects such as ours. \ No newline at end of file