From 8a9979a16967993c37134fa4547c643c5f5ca00a Mon Sep 17 00:00:00 2001 From: Dave O'Connor Date: Tue, 23 Nov 2021 10:31:00 -0500 Subject: [PATCH 1/6] Add initial OMR upgrade proposal --- enhancements/omr-upgrade.md | 223 ++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 enhancements/omr-upgrade.md diff --git a/enhancements/omr-upgrade.md b/enhancements/omr-upgrade.md new file mode 100644 index 0000000..d3bee14 --- /dev/null +++ b/enhancements/omr-upgrade.md @@ -0,0 +1,223 @@ +--- +title: OpenShift Mirror Registry Upgrades +authors: + - "@HammerMeetNail" +reviewers: + - TBD +approvers: + - TBD +creation-date: 2021-11-23 +last-updated: 2021-11-23 +status: provisional +--- + +# Title + +This is the title of the enhancement. Keep it simple and descriptive. A good +title can help communicate what the enhancement is and should be considered as +part of any review. + +The title should be lowercased and spaces/punctuation should be replaced with +`-`. + +To get started with this template: +1. **Pick a domain.** Find the appropriate domain to discuss your enhancement. +1. **Make a copy of this template.** Copy this template into the directory for + the domain. +1. **Fill out the "overview" sections.** This includes the Summary and + Motivation sections. These should be easy and explain why the community + should desire this enhancement. +1. **Create a PR.** Assign it to folks with expertise in that domain to help + sponsor the process. +1. **Merge at each milestone.** Merge when the design is able to transition to a + new status (provisional, implementable, implemented, etc.). View anything + marked as `provisional` as an idea worth exploring in the future, but not + accepted as ready to execute. Anything marked as `implementable` should + clearly communicate how an enhancement is coded up and delivered. If an + enhancement describes a new deployment topology or platform, include a + logical description for the deployment, and how it handles the unique aspects + of the platform. Aim for single topic PRs to keep discussions focused. If you + disagree with what is already in a document, open a new PR with suggested + changes. + +The `Metadata` section above is intended to support the creation of tooling +around the enhancement process. + +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [ ] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA + +## Open Questions [optional] + +This is where to call out areas of the design that require closure before deciding +to implement the design. For instance, + > 1. This requires exposing previously private resources which contain sensitive + information. Can we do this? + +## Summary + +The `Summary` section is incredibly important for producing high quality +user-focused documentation such as release notes or a development roadmap. It +should be possible to collect this information before implementation begins in +order to avoid requiring implementors to split their attention between writing +release notes and implementing the feature itself. + +A good summary is probably at least a paragraph in length. + +## Motivation + +This section is for explicitly listing the motivation, goals and non-goals of +this proposal. Describe why the change is important and the benefits to users. + +### Goals + +List the specific goals of the proposal. How will we know that this has succeeded? + +### Non-Goals + +What is out of scope for this proposal? Listing non-goals helps to focus discussion +and make progress. + +## Proposal + +This is where we get down to the nitty gritty of what the proposal actually is. + +### User Stories [optional] + +Detail the things that people will be able to do if this is implemented. +Include as much detail as possible so that people can understand the "how" of +the system. The goal here is to make this feel real for users without getting +bogged down. + +#### Story 1 + +#### Story 2 + +### Implementation Details/Notes/Constraints [optional] + +What are the caveats to the implementation? What are some important details that +didn't come across above. Go in to as much detail as necessary here. This might +be a good place to talk about core concepts and how they releate. + +### Risks and Mitigations + +What are the risks of this proposal and how do we mitigate. Think broadly. For +example, consider both security and how this will impact the larger Operator Framework +ecosystem. + +How will security be reviewed and by whom? How will UX be reviewed and by whom? + +Consider including folks that also work outside your immediate sub-project. + +## Design Details + +### Test Plan + +**Note:** *Section not required until targeted at a release.* + +Consider the following in developing a test plan for this enhancement: +- Will there be e2e and integration tests, in addition to unit tests? +- How will it be tested in isolation vs with other components? + +No need to outline all of the test cases, just the general strategy. Anything +that would count as tricky in the implementation and anything particularly +challenging to test should be called out. + +All code is expected to have adequate tests (eventually with coverage +expectations). + +### Graduation Criteria + +**Note:** *Section not required until targeted at a release.* + +Define graduation milestones. + +These may be defined in terms of API maturity, or as something else. Initial proposal +should keep this high-level with a focus on what signals will be looked at to +determine graduation. + +Consider the following in developing the graduation criteria for this +enhancement: +- Maturity levels - `Dev Preview`, `Tech Preview`, `GA` +- Deprecation + +Clearly define what graduation means. + +#### Examples + +These are generalized examples to consider, in addition to the aforementioned +[maturity levels][maturity-levels]. + +##### Dev Preview -> Tech Preview + +- Ability to utilize the enhancement end to end +- End user documentation, relative API stability +- Sufficient test coverage +- Gather feedback from users rather than just developers + +##### Tech Preview -> GA + +- More testing (upgrade, downgrade, scale) +- Sufficient time for feedback +- Available by default + +**For non-optional features moving to GA, the graduation criteria must include +end to end tests.** + +##### Removing a deprecated feature + +- Announce deprecation and support policy of the existing feature +- Deprecate the feature + +### Upgrade / Downgrade Strategy + +If applicable, how will the component be upgraded and downgraded? Make sure this +is in the test plan. + +Consider the following in developing an upgrade/downgrade strategy for this +enhancement: +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to keep previous behavior? +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to make use of the enhancement? + +### Version Skew Strategy + +How will the component handle version skew with other components? +What are the guarantees? Make sure this is in the test plan. + +Consider the following in developing a version skew strategy for this +enhancement: +- During an upgrade, we will always have skew among components, how will this impact your work? +- Does this enhancement involve coordinating behavior in the control plane and + in the kubelet? How does an n-2 kubelet without this feature available behave + when this feature is used? +- Will any other components on the node change? For example, changes to CSI, CRI + or CNI may require updating that component before the kubelet. + +## Implementation History + +Major milestones in the life cycle of a proposal should be tracked in `Implementation +History`. + +## Drawbacks + +The idea is to find the best form of an argument why this enhancement should _not_ be implemented. + +## Alternatives + +Similar to the `Drawbacks` section the `Alternatives` section is used to +highlight and record other possible approaches to delivering the value proposed +by an enhancement. + +## Infrastructure Needed [optional] + +Use this section if you need things from the project. Examples include a new +subproject, repos requested, github details, and/or testing infrastructure. + +Listing these here allows the community to get the process for these resources +started right away. + From 5fc53d657aa2524c2818c91e25b6919d71c1608d Mon Sep 17 00:00:00 2001 From: Sunandadadi Date: Mon, 13 Dec 2021 10:38:57 -0500 Subject: [PATCH 2/6] Proposal for Quota Reporting and Management (#12) --- enhancements/quota-management.md | 110 +++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 enhancements/quota-management.md diff --git a/enhancements/quota-management.md b/enhancements/quota-management.md new file mode 100644 index 0000000..cda8eba --- /dev/null +++ b/enhancements/quota-management.md @@ -0,0 +1,110 @@ +--- +title: Quota Management and Enforcement on Quay +authors: + - "@kwestpha" + - "@sleesinc" + - "@sdadi" +reviewers: + - "@kwestpha" + - "@sleesinc" + - "@sdadi" +approvers: + - "@kwestpha" + - "@sleesinc" + - "@sdadi" +creation-date: 2021-12-03 +last-updated: 2021-12-03 +status: implementable +--- + +# quota-management-and-enforcement + +Currently, Quay users have very little control to contain unbounded growth of storage consumption of the registry. +This proposal is to report storage consumption and contain registry growth based on the configured storage quota limits. + +## Release Signoff Checklist + +- [x] Enhancement is `implementable` +- [x] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA + +## Open Questions + + > 1. Do we have any here? + +## Summary + +There are no limitations on a Quay organization in terms of their storage consumption. This is a three-phase proposal that +aims to contain and provide a smart solution to tackle storage related problems for Quay customers. +In the first phase i.e, Quota Reporting: a super admin can see the storage consumption of all of their organizations, and a user can see the storage consumption of their organization. +In the second phase i.e, Quota Management: a superuser can define soft and hard checks for Quay users. +A soft check implies that the Quay user will be notified if the storage consumption of an organization reaches the configured threshold. +A hard check implies that the Quay user will not be allowed to push to the registry once the storage consumption reaches the set limit. +In the third phase, a quay admin can configure auto pruning of the images based on when they were last used to free up quota. + +## Motivation + +Users can create new organizations and repositories in their home organizations without any practical storage limitation. +On-prem Quay customers are subject to capacity limits of their environment, specifically backend storage consumption. +No knowledge about their storage consumption makes it hard for a service owner of a Quay registry to define SLAs and maintain a budget. + +### Goals + +* A Quay superuser can see the overall storage consumption of the entire registry i.e., an overview of all organizations depicting the aggregate storage consumption of images in an organization. +* The storage consumption per repository and organization (for super user) will be exposed on an endpoint (Like: /api/v1/repository///limits) to see their current consumption. +* A Quay user can define soft quota limit on an organization that will trigger a warning when the set limit has reached. +* A Quay user can configure alerts that will allow Quay to send notifications when set storage threshold has reached. +* A Quay user can define hard quota limit on an organization which will not allow them to push any more images when set threshold has reached. + +### Non-Goals + +* We will not be implementing shared layer calculation i.e., if a user pushes two different versions of an image and there are some common layers between the two, +the storage consumption is calculated independently for each of the common layers. + +## Design Details + +Initial work is to add Quota Reporting on organizations i.e., providing Quay users with their storage consumption data on a Quay organization. +In the next steps, we will add Quota Enforcements i.e., soft and hard checks that notify or restrict Quay users from pushing images to registry. + +The expected design flow is depicted as below: +![](https://user-images.githubusercontent.com/11522230/145486007-c88b980c-114a-44bc-a7e0-aa13a266cc79.png) +NOTE: The boxes with the black border show the current flow, and the boxes with the green border show what needs to be implemented to support this feature. Design credits: @kwestpha + +The table RepositorySize (to be created) stores the storage consumption(in bytes) of a Quay repository within an organization. The sum of all repository sizes for an organization, +defines the current storage size of a Quay organization. +When an image push is initialized, the user's organization storage is validated to check if it is beyond the configured Quota limits. +If yes, for a soft check, user is notified and, for a hard check, the push is stopped. If storage consumption is within configured Quota limits, +the push happens as expected. + +Images are uploaded to the Quay registry as chunks. Each of these chunk upload triggers, the next flow. +The size of each image chunk is stored a temporary table, blobupload that has a foreign key reference to the Repository table. +This size of every chunk upload is added to the current repository size that calculates a temporary repository size. This temporary size is validated to be +within the configured Quota limits. If this temporary size reaches beyond the configured Quota limit, an exception is raised. + +Images manifest deletion follows the same flow as on Quay where the link between associated tags and the manifest are deleted. One addition to this, +is, after the manifest is deleted, the repository size is recalculated and updated in the RepositorySize table. +This is depicted below: +![](https://user-images.githubusercontent.com/11522230/145113938-7a8e3fcf-693a-488e-a711-bcf116e04446.png) + +### Constraints + +A few caveats with doing the calculations on push vs a background worker is that existing images will not have any usage data. +This means that a backfill for all existing repositories will be required before the feature is enabled. +This also means that this calculation becomes part of a push's critical path, otherwise the usage data could possibly drift. + +### Risks and Mitigations + +* We want to avoid creating a bottleneck in the push flow for quay that could impact usability of the product. +* We need to avoid increasing database pressure that could create a bottleneck and impact the usability of the product. +* We need to ensure that the design of the feature does not impact users that do not choose to use this product feature. + +### Test Plan + +* Implement Quota Reporting on organization level. +* Implement Quota Management for soft and hard checks on an organization level. +* TBD: Implement Auto Pruning + +### Implementation History + +* 2021-12-03 Initial proposal From 19adb79e5c4423bb9e441f080277cd54ed4b27eb Mon Sep 17 00:00:00 2001 From: Sunandadadi Date: Tue, 21 Dec 2021 13:38:19 -0500 Subject: [PATCH 3/6] Proposal for Quay as a Proxy Cache (#13) --- enhancements/proxy-cache.md | 128 ++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 enhancements/proxy-cache.md diff --git a/enhancements/proxy-cache.md b/enhancements/proxy-cache.md new file mode 100644 index 0000000..f575587 --- /dev/null +++ b/enhancements/proxy-cache.md @@ -0,0 +1,128 @@ +--- +title: Quay as a Proxy Cache +authors: + - "@fmissi" + - "@sleesinc" + - "@sdadi" +reviewers: + - "@fmissi" + - "@sleesinc" + - "@sdadi" +approvers: + - "@fmissi" + - "@sleesinc" + - "@sdadi" +creation-date: 2021-12-10 +last-updated: 2021-12-10 +status: implementable +--- + +# Quay as a cache proxy for upstream registries + +Container development has become widely popular. Customers today rely on container images from upstream registries(like docker, gcp) to get desired services up and running. +Registries now have rate limitation and throttling on the number of times users can pull from these registries. +This proposal is to enable Quay to act as a pull through cache where, once pulled images are only pulled again when upstream images have been updated. + +## Release Signoff Checklist + +- [x] Enhancement is `implementable` +- [x] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA + +## Open Questions + + > 1. Will the check against the upstream registry count against an upstream rate limit? + > 2. Currently, How can we track when an image was last used (to implement eviction based on LRU images)? + > 3. How will time machine work on images that are past its staleness period? + +## Summary + +Dependencies on container images has increased tremendously with the adoption of container driven development. With the introduction of rate limits +on popular container registries, Quay will act as a proxy cache to circumvent pull rate limitation from upstream registries. Adding a cache will also +accelerate pull performance as images are pulled from cache rather than upstream dependencies. Cached images are updated only when the upstream +image digest differs from cached image. + +### Goals + +* A Quay user can define and configure(credentials, staleness period) via config file/app, a repository in Quay that acts a cache for a specific upstream registry. +* A Quay super can leverage storage quota of an organization to limit cache size. This means when cache size reaches its quota limit, + images from cache are evicted based on LRU. +* A proxy cache organization will transparently cache and stream images to client. The images in the proxy cache organization should + support the default expected behaviour (like security scanner, time machine, etc) as other images on Quay. +* Given the sensitive nature of accessing potentially untrusted upstream registry all cache pulls needs to be logged (audit log). +* A Quay user can flush the cache to eliminate excess storage consumption. +* Robot accounts can be created in the cache organization as usual, their RBAC can be managed for all existing cached repositories at a given point in time. +* Provide metrics to track cache activity and efficiency (hit rate, size, evictions). + +### Non-Goals + +* In the first phase, configuring a cache proxy organization, caching upstreaming images, and quota management on cached repositories is the target. + Other goals will be implemented subsequently based on the work of this proposal. +* Cached images are read-only, which means that images cannot be pushed into Proxy Cache Organization. + +## Design Details + +The expected pull overview is depicted as below: +![](https://user-images.githubusercontent.com/11522230/145866763-58f44c94-839b-4edb-a95b-b9c3648cf187.png) +Design credits: @fmissi + +A user initiates a pulls of an image(say a `postgres:14` image) from an upstream repository on Quay. The repository is checked to see if the image is present. +1. If the image does not exist, a fresh pull is initiated. + * The user is authenticated into the upstream registry. Authetication is not a requirement. For public repositories, docker hub supports anonymous pulls. + But, for private repositories, user should be authenticated. + * The layers of `postgres:14` are pulled. + * The pulled layers are saved to cache and served to the user in parallel. + * This is depicted as below: + ![](https://user-images.githubusercontent.com/11522230/145871778-da01585a-7b1b-4c98-903f-809c214578da.png) + Design credits: @fmissi + +2. If the image exists in cache: + * A user can rely on Quay's cache to stay coherent with the upstream source so that I transparently get newer images from the cache + when tags have been overwritten in the upstream registry immediately or after a certain period of time. + * If the upstream image and cached version of the image are same: + * No layers are pulled from the upstream repository and the cached image is served to the user. + + * If the upstream image and cached version of the image are different: + * The user is authenticated into the upstream registry and only the changed layers of `postgres:14` are pulled. + * The new layers are updated in cache and served to the user in parallel. + * This is depicted as below: + ![](https://user-images.githubusercontent.com/11522230/145872216-31350e08-6746-4e34-aebf-e59a7bf6b372.png) + Design credits: @fmissi + +3. If user initiates a pull when the upstream registry which is down: + * If the pull happens with the configured staleness period, the image stored in cache is served. + * If the pull happens after the configured staleness period, the error is propagated to the user. + * This is depicted as below: + ![](https://user-images.githubusercontent.com/11522230/145878373-c23d094b-709d-4859-b875-013ea33e34f7.png) + Design credits: @fmissi + +A quay admin can leverage the configurable size limit of an organization to limit cache size so the backend storage consumption remains predictable +by discarding images from the cache according to least recently used frequency. +This is depicted as below: +![](https://user-images.githubusercontent.com/11522230/145884935-df19297f-96b5-4c1c-9cdc-e199e04df176.png) +Design credits: @sdadi + +A user initiates a pulls of an image(say a `postgres:14` image) from an upstream repository on Quay. If the storage consumption of the organization +is beyond the configured size limit, images in the namespace are removed based on least recently used, to make space for `postgres:14` to be cached. + +### Constraints + +* If size limit is configured in a proxy cache organization, and say an org is set to a max size of 500mb and the image the user wants to pull is 700mb. + In such a case, the image pulled will be cached and will overflow beyond the configured limit. + +### Risks and Mitigations + +* The cached images should have all properties that images on a Quay repository would have. +* When the client wants to pull a new image, Quay should reuse already cached layers and download from the upstream repository only new ones. + +### Implementation Plan + +* Pull a fresh image and check that layers are saved to cache. +* Pull an outdated image and check that only changed layers are saved to cache. +* Implement configuring of a proxy cache organization. +* Implement quota(configurable size limit) management (blocked by [quota mangement feature](https://issues.redhat.com/browse/PROJQUAY-302)) + +### Implementation History + +* 2021-12-13 Initial proposal From d43b216bd5e7957f55d19b171580c7d6b7d2d27c Mon Sep 17 00:00:00 2001 From: Jonathan King Date: Mon, 17 Jan 2022 08:43:06 -0500 Subject: [PATCH 4/6] volume: Volume Size Override Proposal (PROJQUAY-1090) (#10) - Volume Size Override Proposal --- enhancements/volume-overrides.md | 190 +++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 enhancements/volume-overrides.md diff --git a/enhancements/volume-overrides.md b/enhancements/volume-overrides.md new file mode 100644 index 0000000..1a39e1d --- /dev/null +++ b/enhancements/volume-overrides.md @@ -0,0 +1,190 @@ +--- +title: Neat-Enhancement-Idea +authors: + - "@jonathankingfc" +reviewers: + - "@flavianmissi" +approvers: + - TBD +creation-date: 2021-11-01 +last-updated: 2021-11-01 +status: provisional +--- + +# volume-size-overrides + +At the moment, Quay operator users have no ability to override the size of the PVCs for managed Postgres and Clair (Postgres) components. They are, however, able to customize the volume size for ObjectStorage when setting up Noobaa. This proposal would allow users to set volume sizes for all three of these components from the CR. + +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [ ] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA + +## Open Questions [optional] + +This is where to call out areas of the design that require closure before deciding +to implement the design. For instance, + +> 1. Where should the configuration options be presented to the end user? In the CR? Or should they be applying a patch? + +## Summary + +The Quay Operator should give users the option to override the volume size for objectstorage, postgres, and clair (postgres) components. Currently, users are able to choose the PVC size for objectstorage during noobaa setup, but this should be done automatically with a default unless overriden in the same fashion as for the postgres and clair components. + +## Motivation + +Users of the Quay Operator have reported that they sometimes require larger storage than 50GB in the Postgres and Clair components. + +### Goals + +- Creating a zero-config `QuayRegistry` on OpenShift will be use default PVC sizes for the ObjectStorage, Clair, and Postgres components +- Creating a `QuayRegistry` with volumeSizeOverride fields under the ObjectStorage, Clair, or Postgres managed components will override the default size + +### Non-Goals + +- Volume Size Overrides for unmanaged components + +## Proposal + +This is where we get down to the nitty gritty of what the proposal actually is. + +### User Stories [optional] + +Detail the things that people will be able to do if this is implemented. +Include as much detail as possible so that people can understand the "how" of +the system. The goal here is to make this feel real for users without getting +bogged down. + +#### Story 1 + +#### Story 2 + +### Implementation Details/Notes/Constraints [optional] + +What are the caveats to the implementation? What are some important details that +didn't come across above. Go in to as much detail as necessary here. This might +be a good place to talk about core concepts and how they releate. + +### Risks and Mitigations + +What are the risks of this proposal and how do we mitigate. Think broadly. For +example, consider both security and how this will impact the larger Operator Framework +ecosystem. + +How will security be reviewed and by whom? How will UX be reviewed and by whom? + +Consider including folks that also work outside your immediate sub-project. + +## Design Details + +### Test Plan + +**Note:** _Section not required until targeted at a release._ + +Consider the following in developing a test plan for this enhancement: + +- Will there be e2e and integration tests, in addition to unit tests? +- How will it be tested in isolation vs with other components? + +No need to outline all of the test cases, just the general strategy. Anything +that would count as tricky in the implementation and anything particularly +challenging to test should be called out. + +All code is expected to have adequate tests (eventually with coverage +expectations). + +### Graduation Criteria + +**Note:** _Section not required until targeted at a release._ + +Define graduation milestones. + +These may be defined in terms of API maturity, or as something else. Initial proposal +should keep this high-level with a focus on what signals will be looked at to +determine graduation. + +Consider the following in developing the graduation criteria for this +enhancement: + +- Maturity levels - `Dev Preview`, `Tech Preview`, `GA` +- Deprecation + +Clearly define what graduation means. + +#### Examples + +These are generalized examples to consider, in addition to the aforementioned +[maturity levels][maturity-levels]. + +##### Dev Preview -> Tech Preview + +- Ability to utilize the enhancement end to end +- End user documentation, relative API stability +- Sufficient test coverage +- Gather feedback from users rather than just developers + +##### Tech Preview -> GA + +- More testing (upgrade, downgrade, scale) +- Sufficient time for feedback +- Available by default + +**For non-optional features moving to GA, the graduation criteria must include +end to end tests.** + +##### Removing a deprecated feature + +- Announce deprecation and support policy of the existing feature +- Deprecate the feature + +### Upgrade / Downgrade Strategy + +If applicable, how will the component be upgraded and downgraded? Make sure this +is in the test plan. + +Consider the following in developing an upgrade/downgrade strategy for this +enhancement: + +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to keep previous behavior? +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to make use of the enhancement? + +### Version Skew Strategy + +How will the component handle version skew with other components? +What are the guarantees? Make sure this is in the test plan. + +Consider the following in developing a version skew strategy for this +enhancement: + +- During an upgrade, we will always have skew among components, how will this impact your work? +- Does this enhancement involve coordinating behavior in the control plane and + in the kubelet? How does an n-2 kubelet without this feature available behave + when this feature is used? +- Will any other components on the node change? For example, changes to CSI, CRI + or CNI may require updating that component before the kubelet. + +## Implementation History + +Major milestones in the life cycle of a proposal should be tracked in `Implementation History`. + +## Drawbacks + +The idea is to find the best form of an argument why this enhancement should _not_ be implemented. + +## Alternatives + +Similar to the `Drawbacks` section the `Alternatives` section is used to +highlight and record other possible approaches to delivering the value proposed +by an enhancement. + +## Infrastructure Needed [optional] + +Use this section if you need things from the project. Examples include a new +subproject, repos requested, github details, and/or testing infrastructure. + +Listing these here allows the community to get the process for these resources +started right away. From eeb1d4314a988f1027aca96cced9b189a5f233e0 Mon Sep 17 00:00:00 2001 From: Dave O'Connor Date: Tue, 23 Nov 2021 10:31:00 -0500 Subject: [PATCH 5/6] Add initial OMR upgrade proposal --- enhancements/omr-upgrade.md | 223 ++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 enhancements/omr-upgrade.md diff --git a/enhancements/omr-upgrade.md b/enhancements/omr-upgrade.md new file mode 100644 index 0000000..d3bee14 --- /dev/null +++ b/enhancements/omr-upgrade.md @@ -0,0 +1,223 @@ +--- +title: OpenShift Mirror Registry Upgrades +authors: + - "@HammerMeetNail" +reviewers: + - TBD +approvers: + - TBD +creation-date: 2021-11-23 +last-updated: 2021-11-23 +status: provisional +--- + +# Title + +This is the title of the enhancement. Keep it simple and descriptive. A good +title can help communicate what the enhancement is and should be considered as +part of any review. + +The title should be lowercased and spaces/punctuation should be replaced with +`-`. + +To get started with this template: +1. **Pick a domain.** Find the appropriate domain to discuss your enhancement. +1. **Make a copy of this template.** Copy this template into the directory for + the domain. +1. **Fill out the "overview" sections.** This includes the Summary and + Motivation sections. These should be easy and explain why the community + should desire this enhancement. +1. **Create a PR.** Assign it to folks with expertise in that domain to help + sponsor the process. +1. **Merge at each milestone.** Merge when the design is able to transition to a + new status (provisional, implementable, implemented, etc.). View anything + marked as `provisional` as an idea worth exploring in the future, but not + accepted as ready to execute. Anything marked as `implementable` should + clearly communicate how an enhancement is coded up and delivered. If an + enhancement describes a new deployment topology or platform, include a + logical description for the deployment, and how it handles the unique aspects + of the platform. Aim for single topic PRs to keep discussions focused. If you + disagree with what is already in a document, open a new PR with suggested + changes. + +The `Metadata` section above is intended to support the creation of tooling +around the enhancement process. + +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [ ] Design details are appropriately documented from clear requirements +- [ ] Test plan is defined +- [ ] Graduation criteria for dev preview, tech preview, GA + +## Open Questions [optional] + +This is where to call out areas of the design that require closure before deciding +to implement the design. For instance, + > 1. This requires exposing previously private resources which contain sensitive + information. Can we do this? + +## Summary + +The `Summary` section is incredibly important for producing high quality +user-focused documentation such as release notes or a development roadmap. It +should be possible to collect this information before implementation begins in +order to avoid requiring implementors to split their attention between writing +release notes and implementing the feature itself. + +A good summary is probably at least a paragraph in length. + +## Motivation + +This section is for explicitly listing the motivation, goals and non-goals of +this proposal. Describe why the change is important and the benefits to users. + +### Goals + +List the specific goals of the proposal. How will we know that this has succeeded? + +### Non-Goals + +What is out of scope for this proposal? Listing non-goals helps to focus discussion +and make progress. + +## Proposal + +This is where we get down to the nitty gritty of what the proposal actually is. + +### User Stories [optional] + +Detail the things that people will be able to do if this is implemented. +Include as much detail as possible so that people can understand the "how" of +the system. The goal here is to make this feel real for users without getting +bogged down. + +#### Story 1 + +#### Story 2 + +### Implementation Details/Notes/Constraints [optional] + +What are the caveats to the implementation? What are some important details that +didn't come across above. Go in to as much detail as necessary here. This might +be a good place to talk about core concepts and how they releate. + +### Risks and Mitigations + +What are the risks of this proposal and how do we mitigate. Think broadly. For +example, consider both security and how this will impact the larger Operator Framework +ecosystem. + +How will security be reviewed and by whom? How will UX be reviewed and by whom? + +Consider including folks that also work outside your immediate sub-project. + +## Design Details + +### Test Plan + +**Note:** *Section not required until targeted at a release.* + +Consider the following in developing a test plan for this enhancement: +- Will there be e2e and integration tests, in addition to unit tests? +- How will it be tested in isolation vs with other components? + +No need to outline all of the test cases, just the general strategy. Anything +that would count as tricky in the implementation and anything particularly +challenging to test should be called out. + +All code is expected to have adequate tests (eventually with coverage +expectations). + +### Graduation Criteria + +**Note:** *Section not required until targeted at a release.* + +Define graduation milestones. + +These may be defined in terms of API maturity, or as something else. Initial proposal +should keep this high-level with a focus on what signals will be looked at to +determine graduation. + +Consider the following in developing the graduation criteria for this +enhancement: +- Maturity levels - `Dev Preview`, `Tech Preview`, `GA` +- Deprecation + +Clearly define what graduation means. + +#### Examples + +These are generalized examples to consider, in addition to the aforementioned +[maturity levels][maturity-levels]. + +##### Dev Preview -> Tech Preview + +- Ability to utilize the enhancement end to end +- End user documentation, relative API stability +- Sufficient test coverage +- Gather feedback from users rather than just developers + +##### Tech Preview -> GA + +- More testing (upgrade, downgrade, scale) +- Sufficient time for feedback +- Available by default + +**For non-optional features moving to GA, the graduation criteria must include +end to end tests.** + +##### Removing a deprecated feature + +- Announce deprecation and support policy of the existing feature +- Deprecate the feature + +### Upgrade / Downgrade Strategy + +If applicable, how will the component be upgraded and downgraded? Make sure this +is in the test plan. + +Consider the following in developing an upgrade/downgrade strategy for this +enhancement: +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to keep previous behavior? +- What changes (in invocations, configurations, API use, etc.) is an existing + cluster required to make on upgrade in order to make use of the enhancement? + +### Version Skew Strategy + +How will the component handle version skew with other components? +What are the guarantees? Make sure this is in the test plan. + +Consider the following in developing a version skew strategy for this +enhancement: +- During an upgrade, we will always have skew among components, how will this impact your work? +- Does this enhancement involve coordinating behavior in the control plane and + in the kubelet? How does an n-2 kubelet without this feature available behave + when this feature is used? +- Will any other components on the node change? For example, changes to CSI, CRI + or CNI may require updating that component before the kubelet. + +## Implementation History + +Major milestones in the life cycle of a proposal should be tracked in `Implementation +History`. + +## Drawbacks + +The idea is to find the best form of an argument why this enhancement should _not_ be implemented. + +## Alternatives + +Similar to the `Drawbacks` section the `Alternatives` section is used to +highlight and record other possible approaches to delivering the value proposed +by an enhancement. + +## Infrastructure Needed [optional] + +Use this section if you need things from the project. Examples include a new +subproject, repos requested, github details, and/or testing infrastructure. + +Listing these here allows the community to get the process for these resources +started right away. + From d7d7020b6bbed7da4d808afad875fee8e8b35897 Mon Sep 17 00:00:00 2001 From: Dave O'Connor <1656866+HammerMeetNail@users.noreply.github.com> Date: Thu, 20 Jan 2022 17:19:03 -0500 Subject: [PATCH 6/6] Update to mirror registry proposal --- ...-upgrade.md => mirror-registry-upgrade.md} | 72 +++++-------------- 1 file changed, 16 insertions(+), 56 deletions(-) rename enhancements/{omr-upgrade.md => mirror-registry-upgrade.md} (65%) diff --git a/enhancements/omr-upgrade.md b/enhancements/mirror-registry-upgrade.md similarity index 65% rename from enhancements/omr-upgrade.md rename to enhancements/mirror-registry-upgrade.md index d3bee14..00bd845 100644 --- a/enhancements/omr-upgrade.md +++ b/enhancements/mirror-registry-upgrade.md @@ -1,47 +1,18 @@ --- -title: OpenShift Mirror Registry Upgrades +title: Mirror Registry Upgrade authors: - "@HammerMeetNail" reviewers: - - TBD + - "@joking" approvers: - - TBD -creation-date: 2021-11-23 -last-updated: 2021-11-23 + - "@joking" +creation-date: 2022-01-20 +last-updated: 2022-01-20 status: provisional --- -# Title - -This is the title of the enhancement. Keep it simple and descriptive. A good -title can help communicate what the enhancement is and should be considered as -part of any review. - -The title should be lowercased and spaces/punctuation should be replaced with -`-`. - -To get started with this template: -1. **Pick a domain.** Find the appropriate domain to discuss your enhancement. -1. **Make a copy of this template.** Copy this template into the directory for - the domain. -1. **Fill out the "overview" sections.** This includes the Summary and - Motivation sections. These should be easy and explain why the community - should desire this enhancement. -1. **Create a PR.** Assign it to folks with expertise in that domain to help - sponsor the process. -1. **Merge at each milestone.** Merge when the design is able to transition to a - new status (provisional, implementable, implemented, etc.). View anything - marked as `provisional` as an idea worth exploring in the future, but not - accepted as ready to execute. Anything marked as `implementable` should - clearly communicate how an enhancement is coded up and delivered. If an - enhancement describes a new deployment topology or platform, include a - logical description for the deployment, and how it handles the unique aspects - of the platform. Aim for single topic PRs to keep discussions focused. If you - disagree with what is already in a document, open a new PR with suggested - changes. - -The `Metadata` section above is intended to support the creation of tooling -around the enhancement process. +# mirror-registry-upgrade +The mirror registry for Red Hat OpenShift is meant to be a long live registry that lives on a single RHEL host. It supports mirror for the last three version of OCP and must be able to handle upgrades gracefully. This proposal details how mirror registry will be able to upgrade to new versions, e.g., 1.0 -> 1.1.0. ## Release Signoff Checklist @@ -52,34 +23,23 @@ around the enhancement process. ## Open Questions [optional] -This is where to call out areas of the design that require closure before deciding -to implement the design. For instance, - > 1. This requires exposing previously private resources which contain sensitive - information. Can we do this? + > 1. When should an upgrade occur? + > 2. How should we handle certificate renewal? + > 3. Should we add a new command for upgrade of should install command trigger upgrade? + > 4. What would a self upgrading mirror registry look like in a disconnected environment? ## Summary - -The `Summary` section is incredibly important for producing high quality -user-focused documentation such as release notes or a development roadmap. It -should be possible to collect this information before implementation begins in -order to avoid requiring implementors to split their attention between writing -release notes and implementing the feature itself. - -A good summary is probably at least a paragraph in length. - -## Motivation - -This section is for explicitly listing the motivation, goals and non-goals of -this proposal. Describe why the change is important and the benefits to users. +The mirror registry will need to be upgraded whenever a new y-stream release of `Quay` or `OCP` occurs. It should be upgraded whenever a z-stream release occurs for `Quay`, `Postgres`, or `Redis`. Certificates will be renewed at time of upgrade, which should occur at least once per year. Existing installation will be detected and no additional information should be required for upgrade. Upgrades will be idempotent. ### Goals -List the specific goals of the proposal. How will we know that this has succeeded? +* Users should be able to upgrade to newer versions of mirror registry with ease +* Existing mirror registry installations should be detected and settings inherited +* Autogenerated certificates should be renewed on upgrade ### Non-Goals -What is out of scope for this proposal? Listing non-goals helps to focus discussion -and make progress. +* Upgrades to host level dependencies such as `podman` ## Proposal