Bug 1830946 - [DOCS] "Using Samples Operator imagestreams with alternate or mirrored registries" doc needs to be reviewed
Summary: [DOCS] "Using Samples Operator imagestreams with alternate or mirrored regist...
Keywords:
Status: CLOSED EOL
Alias: None
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation
Version: 4.7
Hardware: Unspecified
OS: Unspecified
unspecified
medium
Target Milestone: ---
: ---
Assignee: Brandi Munilla
QA Contact: Xiaoli Tian
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2020-05-04 11:58 UTC by Pedro Amoedo
Modified: 2024-03-25 15:53 UTC (History)
4 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2022-09-09 14:34:46 UTC
Target Upstream Version:
Embargoed:


Attachments (Terms of Use)


Links
System ID Private Priority Status Summary Last Updated
Red Hat Knowledge Base (Solution) 5067531 0 None None None 2020-05-12 19:29:44 UTC

Description Pedro Amoedo 2020-05-04 11:58:50 UTC
Document URL: 

https://docs.openshift.com/container-platform/4.3/installing/install_config/installing-restricted-networks-preparations.html#installation-restricted-network-samples_installing-restricted-networks-preparations

Section Number and Name: 

Unknown

Describe the issue: 

Step 4 & 5 of the document section mention modifications (samplesRegistry, skippedImagestreams) in the object "configs.samples.operator.openshift.io" at "openshift-cluster-samples-operator" namespace that are not present by default, and do not provide any example of the modification nor any patch command.

Suggestions for improvement: 

Based on KCS#4975281[1], the object can be patched on the following manner:

[For Step4 (samplesRegistry)]

~~~
$ oc patch configs.samples.operator.openshift.io/cluster --type merge --patch '{"spec":{"samplesRegistry": "<my-mirror-repo-hostname>" }}'
~~~

[For Step5 (skippedImagestreams)]

~~~
$ oc patch configs.samples.operator.openshift.io/cluster --patch '{"spec":{"skippedImagestreams":["jenkins", "jenkins-agent-maven", "jenkins-agent-nodejs"]}}' --type=merge
~~~

So maybe, based on the patch command and the resulting object, the documentation should provide some examples of how to modify that manually with "oc edit" if needed.

Additional information: 

[1] - https://access.redhat.com/solutions/4975281

Comment 1 Pedro Amoedo 2020-05-07 11:27:24 UTC
Let me try to summarize the problems that I'm seeing when the customers try to follow this doc within disconnected environments:

1) How to extract the full list of imagestreams? the doc mentions the following command to go one by one:

~~~
$ oc get is <imagestream> -n openshift -o json | jq .spec.tags[].from.name | grep registry.redhat.io
~~~

But the proper thing should be extracting all imagestreams within openshift namespace, right?

2) For the mirroring procedure it mentions again only one image example:

~~~
$ oc image mirror registry.redhat.io/rhscl/ruby-25-rhel7:latest ${MIRROR_ADDR}/rhscl/ruby-25-rhel7:latest
~~~

But I have provided the CU with the following procedure instead, please corroborate:

~~~
$ for i in `cat imagelist.txt`; do oc get is $i -n openshift -o json | jq .spec.tags[].from.name | grep registry.redhat.io | sed -e 's/"//g' | cut -d"/" -f2- >> imageurl.txt; done
$ for i in `cat imageurl.txt`; do oc -a ${LOCAL_SECRET_JSON} image mirror registry.redhat.io/$i mirrorname.domain:5000/$i; done
~~~

NOTE: "-a ${LOCAL_SECRET_JSON}" is specific for this CU because they are not using default "~/.docker/config.json"

3) Regarding the samplesRegistry modification, it just says:

~~~
$ oc get configs.samples.operator.openshift.io -n openshift-cluster-samples-operator
~~~

But instead of that I think the proper command should be this one, right?:

~~~
$ oc patch configs.samples.operator.openshift.io/cluster --patch '{"spec":{"samplesRegistry": "<MIRROR_REGISTRY>" }}' --type=merge
~~~

4) It doesn't mention how to force the imagestreams re-import procedure when the operator is already degraded, I have found this KCS[1] that mentions the following procedure in order to achieve the reload but it should be a better manner right?

~~~
$ oc patch configs.samples.operator.openshift.io/cluster --type merge --patch '{"spec":{"managementState": "Removed" }}'
### wait a few seconds between commands ###
$ oc patch configs.samples.operator.openshift.io/cluster --type merge --patch '{"spec":{"managementState": "Managed" }}'
~~~

[1] - https://access.redhat.com/solutions/4975281

Best Regards,

Comment 2 Gabe Montero 2020-05-07 16:22:56 UTC
So @Pedro and I discussed some of this in slack.  I am now reiterating here.  There is also some additional complications we recently discovered I realize necessitate more updates.

1) from @Pedro

Not all imagestreams in the openshift namespace are managed by samples operator.  So the grep on "registry.redhat.io" sufficiently filters out those imagestreams which samples operator does *NOT* manage.

So I we are good there wrt the query.

Basically we are filtering out imagestreams whose source image comes from the install payload with 4.5, 4.4, 4.3

However, there are other complexities.

the Jenkins imagestreams, which is managed by the samples operator, is also in that camp.

However, we have special casing to not apply samplesRegistry to the jenkins related imagestreams.

That fix is in 4.5.  If you mirror the install payload, the import should work.

For 4.4, we have bug https://bugzilla.redhat.com/show_bug.cgi?id=1824280 still in POST waiting for cherrypick approval
For 4.3, we have bug https://bugzilla.redhat.com/show_bug.cgi?id=1814396 which is queued up behind the 4.4 bug

with this, you can have the install payload in one mirror and the registry.redhat.io images in another mirror 

For 4.2, we have to apply the samplesOverride to the jenkins imagestream, as the required image registry / apiserver image import code to avoid that is only in 4.3 and later.
As a result, you have to mirror any registry.redhat.io sample in the same mirror as the install payload if you want to mirror both jenkins and other samples that by default use registry.redhat.io.

2) from @Pedro

Yeah I'm NOT inclined to include more complicated bash, or proscribe even more bash in our docs for collecting image urls.  They should be able to construct their own bash.  Or 
support can assist those who are not bash inclined.

3) from @Pedro

Yeah our step 4) for updating only lists an `oc get` ... we just missed that one ... we should employ @Pedro's oc patch

4) from @Pedro

The update of the imagestream done by the samples operator when you change the samplesRegistry initiates the imagestream import.

And if it fails after the samplesRegistry change occurs, then the following applies:
1) starting with 4.2.z levels that contain https://github.com/openshift/cluster-samples-operator/commit/9ddd4133320d1f854d699aa221d3eac5ae9fa674#diff-c23b2b3c960ee8081dde3bf8086980e0 from Nov 2019, samples operator will retry on an approximate 15 minute interval
   4.3.0 GA has this feature
2) Before https://github.com/openshift/cluster-samples-operator/commit/9ddd4133320d1f854d699aa221d3eac5ae9fa674#diff-c23b2b3c960ee8081dde3bf8086980e0 in 4.2.0 and earlier 4.2.z it retried once after a failure and then stopped

@Brandi - some form of that detail or retrying imports should be in the main samples operator doc at https://docs.okd.io/latest/openshift_images/configuring-samples-operator.html and the analogous OCP versions

3) oc import-image is what manually re-imports any imagestream ... if a samples operator user did not want to wait for the retry on the sample imagestreams, they could use that ... I did not find much mention of that in the docs ... I only see https://docs.okd.io/latest/registry/registry-options.html for example

@Brandi - I could see adding a mention of oc import-image in the https://docs.okd.io/latest/openshift_images/image-streams-manage.html#images-imagestreams-import_image-streams-managing section .... as a separate section right after https://docs.okd.io/latest/openshift_images/image-streams-manage.html#images-imagestreams-import_image-streams-managing
and then the samples operator section on retry could reference that

The user should not have to initiate an import

Comment 7 Brandi Munilla 2022-09-09 14:34:46 UTC
OCP 4.7 is no longer on full support [1]. Marking this bug as CLOSED EOL.

If you have a customer case with a support exception or if you think this issue
still applies on 4.8+, please reopen and include those details or open a new Jira issue [2] with updated information. When reopening,
please set the Target Release to the appropriate version where needed.

[1]: https://access.redhat.com/support/policy/updates/openshift
[2]: https://issues.redhat.com/projects/OCPBUGS


Note You need to log in before you can comment on or make changes to this bug.