From a7ebcc4fb4bd9169684b6dfdf4ac5191fe6c8854 Mon Sep 17 00:00:00 2001 From: Patrick Dillon Date: Tue, 16 Jul 2019 15:59:45 -0400 Subject: [PATCH] Update docs for release mirrors. Minor corrections to comments and developer reference docs related to the oc adm release mirrors. --- docs/dev/alternative_release_image_sources.md | 47 ++++--------------- pkg/asset/manifests/imagesourcepolicy.go | 2 +- pkg/types/installconfig.go | 4 +- pkg/types/validation/installconfig.go | 4 +- pkg/types/validation/installconfig_test.go | 6 +-- 5 files changed, 18 insertions(+), 45 deletions(-) diff --git a/docs/dev/alternative_release_image_sources.md b/docs/dev/alternative_release_image_sources.md index 4f2331733b2..285ee092b2b 100644 --- a/docs/dev/alternative_release_image_sources.md +++ b/docs/dev/alternative_release_image_sources.md @@ -2,9 +2,10 @@ ## release-image content vs release-image source -`release-image` content is what operators get installed and what version of each operator (i.e. the container image) gets installed to the cluster. While, `release-image` source is **where** the `release-image` content gets pulled. +`release-image` **content** - which operators get installed to the cluster & which version/container image of each operator +`release-image` **source** - where `release-image` content gets pulled from -Currently the installer controls **both** the `release-image` content and the `release-image` source using the embedded release-image location or the `OPENSHIFT_INSTALL_RELEASE_IMAGE_OVERRIDE` env, but to allow users to use a release-image from their private registry (change the `release-image` source), but keep the `release-image` content identical to one vetted by OpenShift, the installer needs to allow specifying source separate from the content. +The installer controls *both* the `release-image` content and source using the embedded release-image location or the `OPENSHIFT_INSTALL_RELEASE_IMAGE_OVERRIDE` env. Users may also use a release-image from a private registry (change the `release-image` source), but keep the `release-image` content identical to one vetted by OpenShift. ## Controlling the content @@ -12,26 +13,22 @@ The content of the `release-image`, i.e. the digest, continues to be controlled ## Controlling the source -The installer allows the users to specify the sources for the release-image repository and the other repositories referenced in the release-image through the InstallConfig. +The installer allows the users to specify sources for the release-image repository and other repositories referenced in the release-image through the InstallConfig. ## Details -The design is based on the assumption that all flows of using multiple sources/repositories for the release-image originate from user's using the `oc adm release mirror` command to create those sources/repositories. +The design is based on the assumption that all flows of using multiple sources/repositories for the release-image originate with the `oc adm release mirror` command to create those sources/repositories. ## InstallConfig ```go type InstallConfig struct { - /// - - // ImageContentSources is the list of sources/repositories that can be used to pull the same content. + // ImageContentSources lists sources/repositories for the release-image content. // No two ImageContentSource in the list can include the same repository. Each ImageContentSource must be a disjoint set from the rest. ImageContentSources []ImageContentSource `json:"imageContentSources"` - - /// } -// ImageContentSource defines a list of sources/repositories that can be used to pull a content. +// ImageContentSource defines a list of sources/repositories that can be used to pull content. type ImageContentSource struct { Sources []string `json:"Sources"` } @@ -53,19 +50,7 @@ imageContentSources: If a list of `ImageContentSources` is specified, the installer configures the [RepositoryDigestMirrors][repository-digest-mirrors] for each `ImageContentSource`. -If the `install-config.yaml` provided by the user is: - -```yaml -... -imageContentSources: -- sources: - - local.registry.com/ocp/release-x.y - - q.io/ocp/release-x.y - - q.io/openshift/x.y -... -``` - -The `ImageContentSourcePolicy` object would look like: +Using the same `install-config.yaml` from above, the `ImageContentSourcePolicy` object would look like: ```yaml ... @@ -85,19 +70,7 @@ The release-image location that is propagated to the bootstrap node and the clus If a list of `ImageContentSources` is specified, the [Registries][registry-containers-registries-conf] will be configured to have each source be a mirror for another. -For example, - -If the `install-config.yaml` provided by the user is: - -```yaml -... -imageContentSources: -- sources: - - local.registry.com/ocp/release-x.y - - q.io/ocp/release-x.y - - q.io/openshift/x.y -... -``` +For example, our `install-config.yaml` will result in: ```toml [[registry]] @@ -142,7 +115,7 @@ location = "q.io/openshift/x.y" ### oc adm release mirror -The `release mirror` mirrors the a release-image and all other images referenced in the release-image to another repository and then provides user's details of setting up the `install-config.yaml` for the user. +The `release mirror` mirrors the release-image and all other images referenced in the release-image to another repository and then provides details for setting up the `install-config.yaml`. The output would look like: diff --git a/pkg/asset/manifests/imagesourcepolicy.go b/pkg/asset/manifests/imagesourcepolicy.go index 8990d3d1a6b..a3bb9e5ed1e 100644 --- a/pkg/asset/manifests/imagesourcepolicy.go +++ b/pkg/asset/manifests/imagesourcepolicy.go @@ -35,7 +35,7 @@ func (*ImageContentSourcePolicy) Dependencies() []asset.Asset { } } -// Generate generates the Proxy config and its CRD. +// Generate generates the ImageContentSourcePolicy config and its CRD. func (p *ImageContentSourcePolicy) Generate(dependencies asset.Parents) error { installconfig := &installconfig.InstallConfig{} dependencies.Get(installconfig) diff --git a/pkg/types/installconfig.go b/pkg/types/installconfig.go index a2727523706..c64fe6d1458 100644 --- a/pkg/types/installconfig.go +++ b/pkg/types/installconfig.go @@ -78,7 +78,7 @@ type InstallConfig struct { // +optional Proxy *Proxy `json:"proxy,omitempty"` - // ImageContentSources is the lists of sources/repositories that can be used to pull the same content. + // ImageContentSources lists sources/repositories for the release-image content. // No two ImageContentSource in the list can include the same repository. Each ImageContentSource must be a disjoint set from the rest. ImageContentSources []ImageContentSource `json:"imageContentSources,omitempty"` } @@ -216,7 +216,7 @@ type Proxy struct { NoProxy string `json:"noProxy,omitempty"` } -// ImageContentSource defines a list of sources/repositories that can be used to pull a content. +// ImageContentSource defines a list of sources/repositories that can be used to pull content. type ImageContentSource struct { Sources []string `json:"sources,omitempty"` } diff --git a/pkg/types/validation/installconfig.go b/pkg/types/validation/installconfig.go index 85007d769b5..69f82fc24b4 100644 --- a/pkg/types/validation/installconfig.go +++ b/pkg/types/validation/installconfig.go @@ -284,7 +284,7 @@ func validateImageContentSources(groups []types.ImageContentSource, fldPath *fie continue } if !dockerref.IsNameOnly(ref) { - allErrs = append(allErrs, field.Invalid(f.Index(sidx), source, "must be repository not a reference")) + allErrs = append(allErrs, field.Invalid(f.Index(sidx), source, "must be repository--not reference")) continue } } @@ -296,7 +296,7 @@ func validateImageContentSources(groups []types.ImageContentSource, fldPath *fie jset := sets.NewString(groups[j].Sources...) intset := iset.Intersection(jset) if intset.Len() != 0 { - allErrs = append(allErrs, field.Invalid(fldPath.Index(i), groups[i], fmt.Sprintf("Overlapping sources other ImageContentSources is not allowed, overlapping sources found with %s: %s", fldPath.Index(j).String(), intset.List()))) + allErrs = append(allErrs, field.Invalid(fldPath.Index(i), groups[i], fmt.Sprintf("all sources in ImageContentSources must be unique, overlapping sources found with %s: %s", fldPath.Index(j).String(), intset.List()))) } } } diff --git a/pkg/types/validation/installconfig_test.go b/pkg/types/validation/installconfig_test.go index ea68e4819b6..b61cf3434ab 100644 --- a/pkg/types/validation/installconfig_test.go +++ b/pkg/types/validation/installconfig_test.go @@ -550,7 +550,7 @@ func TestValidateInstallConfig(t *testing.T) { }} return c }(), - expectedError: `^imageContentSources\[0\].source\[0\]: Invalid value: "quay.io/ocp/release-x.y@sha256:397c867cc10bcc90cf05ae9b71dd3de6000535e27cb6c704d9f503879202582c": must be repository not a reference$`, + expectedError: `^imageContentSources\[0\].source\[0\]: Invalid value: "quay.io/ocp/release-x.y@sha256:397c867cc10bcc90cf05ae9b71dd3de6000535e27cb6c704d9f503879202582c": must be repository--not reference$`, }, { name: "release image source is not repository but reference by tag", @@ -561,7 +561,7 @@ func TestValidateInstallConfig(t *testing.T) { }} return c }(), - expectedError: `^imageContentSources\[0\].source\[0\]: Invalid value: "quay.io/ocp/release-x.y:latest": must be repository not a reference$`, + expectedError: `^imageContentSources\[0\].source\[0\]: Invalid value: "quay.io/ocp/release-x.y:latest": must be repository--not reference$`, }, { name: "valid release image source", @@ -584,7 +584,7 @@ func TestValidateInstallConfig(t *testing.T) { }} return c }(), - expectedError: `^imageContentSources\[0\]: Invalid value: types.ImageContentSource{Sources:\[\]string{"quay.io\/ocp\/release-x.y", "mirror.test\/ocp\/release-x.y"}}: Overlapping sources other ImageContentSources is not allowed, overlapping sources found with imageContentSources\[1\]: \[mirror.test\/ocp\/release-x.y\]$`, + expectedError: `^imageContentSources\[0\]: Invalid value: types.ImageContentSource{Sources:\[\]string{"quay.io\/ocp\/release-x.y", "mirror.test\/ocp\/release-x.y"}}: all sources in ImageContentSources must be unique, overlapping sources found with imageContentSources\[1\]: \[mirror.test\/ocp\/release-x.y\]$`, }, } for _, tc := range cases {