forked from openshift/enhancements
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make oc aware of ImageContentSourcePolicy
- Loading branch information
Showing
1 changed file
with
109 additions
and
0 deletions.
There are no files selected for viewing
109 changes: 109 additions & 0 deletions
109
enhancements/oc/image-content-source-policy-awareness.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| --- | ||
| title: image-content-source-policy-awareness | ||
| authors: | ||
| - "@sallyom" | ||
| reviewers: | ||
| - "@smarterclayton" | ||
| - "@soltysh" | ||
| - "@wking" | ||
| approvers: | ||
| - "@smarterclayton" | ||
| creation-date: 2020-05-19 | ||
| last-updated: 2020-05-19 | ||
| status: provisional | ||
| --- | ||
|
|
||
| # ImageContentSourcePolicy (ICSP) Awareness | ||
|
|
||
| ICSP allows OpenShift (CVO, CRI-O) to check down a list of possible mirrors to find an image with the matching digest it is | ||
| looking for. `oc` should do the same. | ||
|
|
||
| There have been several bugs opened around the experience of a | ||
| user in a disconnected environment using `oc adm release` commands. If | ||
| using a mirrored image and the mirrored source registry is connected, | ||
| the following commands do not succeed when in a disconnected environment: | ||
|
|
||
| ```console | ||
| $ oc adm release extract --tools registry.example.com/repo/name:tag | ||
| $ oc adm release mirror registry.example.com/repo/name:tag --to someregistry/repo/name | ||
| $ oc adm must-gather | ||
| ``` | ||
|
|
||
| This is because the mirrored image tags (the individual component images from a payload) | ||
| retain references to the mirrored registry, usually something like | ||
| `quay.io/openshift-release-dev/ocp-v4.0-art-dev`. | ||
|
|
||
| There needs to be logic in `oc` to look for `ImageContentSourcePolicy` from a cluster. | ||
| `oc` should look for `ICSP` in the cluster/current context if connected and if user has permission to | ||
| access ICSPs. `oc` should gather information about RepositoryDigestMirrors from ICSP and use that | ||
| when extracting or mirroring images, or when running must-gather. If no ICSP found or if ICSP image doesn't | ||
| exist, then use the user-given image. If that image is not accessible, then fall back to the current flow of | ||
| using the image-reference from the user-given image. | ||
|
|
||
| Current bugs regarding this Issue: | ||
| * https://bugzilla.redhat.com/show_bug.cgi?id=1823839 | ||
| * https://bugzilla.redhat.com/show_bug.cgi?id=1823143 and also for 4.3, 4.5, 4.6 | ||
|
|
||
|
|
||
| ## 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 | ||
| - [ ] User-facing documentation is created in [openshift-docs](https://github.com/openshift/openshift-docs/) | ||
|
|
||
| ## Open Questions | ||
|
|
||
| * Should new flags be introduced OR should oc try each scenario until it succeeds in finding the registry/repo/name:digest? | ||
| * NO FLAGS: | ||
| 1. Try ImageContentSources from cluster -> if oc can access ICSP and cluster, get images from ICSP, check if an image exists, if so use it | ||
| 2. Try user-given registry/repo/name -> check if registry/repo/name:digest exists, if so use it | ||
| 3. (The current flow): If the above fall through, try the image-reference from user-given image - use it - may or may not succeed | ||
| if disconnected or not authorized to access image-reference registry | ||
| * FLAGS: | ||
| * *--icsp-to* will define where to write an ICSP file to. If unset, `oc adm release mirror` will write to current directory. | ||
| * *--icsp-file* will define where to get ICSP from a file. If set, `oc adm release extract|mirror` will use this ICSP data. | ||
| * FLAGS DECIDED AGAINST: | ||
| * boolean `--use-icsp` and if true, check for cluster and/or icsp file? This is problematic, because even if a user is currently connected to a cluster, | ||
| it doesn't mean they want to use information from that cluster with an `oc adm release ...` command. | ||
| So here, we'd need a different `--cluster-icsp` boolean and `--icsp-file` string flag. The flags are adding up here, and that is not desireable. | ||
| * string `--image-content-source aregistry/arepo/arelease`. I don't like this, because it would be redundant for a user to run something like this: | ||
| `oc adm release extract --command oc myreg:5000/myrepo/release:tag --image-content-source myreg:5000/myrepo/release`. | ||
| * Instead, a boolean `--set-prefix` would allow a user to specify "I want to use the prefix of the release image I have specified, | ||
| rather than any underlying image reference." | ||
| * This proposal is for the `FLAGS`, that `oc` will try ICSP, user-given image, then fall back on underlying image-reference from user-given image. | ||
| * See `User Stories` below for examples. | ||
|
|
||
| ## Summary | ||
|
|
||
| ICSP allows OpenShift (CVO, CRI-O) to check down a list of possible mirrors to find an image with the matching digest it is | ||
| looking for. `oc` should do the same. If no ICSP found, then try user-given image. If that doesn't succeed, then use underlying | ||
| image-reference from user-given image. | ||
|
|
||
| ## Proposal | ||
|
|
||
| * `oc adm release mirror` writes an ICSP file to the current directory or wherever you specify | ||
| * Add logic to `oc adm release` to become aware of ICSP in cluster | ||
| * Add logic to `oc adm release` to use the ICSP to complete extracts, mirroring, must-gather | ||
|
|
||
| ## User Stories | ||
|
|
||
| A user runs: | ||
| 1. `oc adm must-gather` | ||
| * `oc` will look for ICSP from cluster (no flag necessary here, since this cmd is always run while connected to a cluster) and will use the mirror from ICSP to launch the must-gather pod. If no ICSP found, will look in `-n openshift` for must-gather imagestream. | ||
| 2. `oc adm release extract --tools registry.example.com/repo/release:tag` | ||
| * `oc` will look for ICSP and if found, will extract from the ICSP mirror (aregistry/arepo/release:tag-toolsha) rather than from the image reference that the user will not | ||
| have access to if in disconnected environment. If ICSP not found, will extract from the user-given registry.example.com/repo/tool:digest. | ||
| If neither of these succeed, will proceed to use the image-reference from the user-given image. The extract will succeed if user has access and permission to the | ||
| underlying image registry/repo/name. | ||
| 2. `oc adm release extract --icsp-file /path/to/icsp.yaml --tools anightly/release:tag` | ||
| * `oc` will try to use data from the icsp file, it will extract from the ICSP mirror (aregistry/arepo/release:tag-toolsha) rather than from the image reference. | ||
| It will not try other sources, if the --icsp-file flag is provided. | ||
| 3. `oc adm release mirror --icsp-to /path/to/file aregistry/arepo/release:tag --to anotherreg/arepo/release` | ||
| * `oc` will write an ICSP file to a configured path (same directory as the signature file), or to provided path via an --icsp-to (or similar) flag. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| Added logic in `oc adm release mirror|info|extract` to replace the `registry/repo/name` of a referenced image with a user-given image. This | ||
| worked, but was a hack. ICSP awareness needs to be added. |