Sure thing.  There are definitely some nuances here.

The jenkins imagestreams (jenkins core, as well as the maven/nodejs agents) are special because since the image is produced by the openshift dev organization, it is part of the install payload, and tied to the openshift release lifecycle.

This is discussed in https://docs.openshift.com/container-platform/4.2/openshift_images/configuring-samples-operator.html#samples-operator-overview_configuring-samples-operator

As a result, it is not going to have an images spec that lines up with what is provided at registry.redhat.io.

The registry.redhat.io looks like 

registry.redhat.io/openshift4/ose-jenkins-agent-maven:v4.2.11-201912100122

And depending on where you install from, the image payload spec will look something like

<registry you installed from>/ocp/4.2.....:@sha56:....

The replacement of the registry alone via the samplesOperator samplesRegistry setting is not sufficient to construct a valid pull spec.

In fact, prior to 4.2, we did not allow the samplesRegistry setting to affect the jenkins related imagestreams, but with the introduction of disconnected/restricted network install support, this was lifted.

The customer can see some of the details there at https://docs.openshift.com/container-platform/4.2/installing/installing_restricted_networks/installing-restricted-networks-preparations.html#installation-restricted-network-samples_installing-restricted-networks-preparations

So moving forward:
a) increasing the scope of the samplesRegistry override to optionally override not just the registry, but repository / entire image pull spec, is already a registered requirement
b) you can still use `oc tag --source=docker <docker pull spec> <imagestream ref>` to override any samples imagestream post install / upgrade
c) fyi setting registry.redhat.io as the samples registry override in general is a useless exercise since aside from jenkins, all the samples are already from registry.redhat.io
d) while it is under the restricted network docs, it really is more generic ... if you want the samples to come from non default registries, you have to inject the sample imagestreams into that registry, where the repository/imageref matches what is in the imagestream, and only the registry needs replacing (where you use b) if needed)
e) and if you choose to not inject some of the samples, you need to add them to the skip list

4.1 includes the original configuration. After upgrading to 4.2, the same configuration prevents the Jenkins image from being pulled. Nowhere does this seem to be documented, and the upgrade process doesn’t update the configuration to prevent breakage.

Is this a fair summary?

Sorry, rereading the initial description, it wasn't made clear that this configuration was left over from a 4.1 installation, which was the context in which the ticket was filed with support.

FYI -- a 4.1 cluster includes the setting. To get Jenkins to pull on a 4.2 cluster, I had to remove it. I'd filed the support ticket to alert them to the issue and workaround.

But overall it seems problematic that clusters upgraded from 4.1 -> 4.2 would no longer be able to pull the Jenkins operator without manual intervention, and even less optimal that it doesn't seem to be documented anywhere.

We would call setting the samplesRegistry to registry.redhat.io unnecessary and a misconfiguration.

I'm fine with reopening this as a docs bug to clarify that in general, along with a 4.1 upgrade note.

Brandi - Some more samples docs clarification appear to be needed around setting samplesRegistry to registry.redhat.io in correlation with the jenkins imagestreams in general across 4.x.

Also, a 4.1 -> 4.2 upgrade release note telling folks to turn that off if that have done so seems warranted.

It might be unnecessary and a misconfiguration but I believe it's what 4.1 did out of the box. (I did try to confirm this using `openshift-install create manifests` with a 4.1.9 installer, but the samples-operator config wasn't included in the output.)

We did toggle managementState, but it would be surprising if we'd ever had a reason to touch the samplesRegistry setting.

4.1 did not set samplesRegistry to registry.redhat.io out of the box.

Here is the code that creates the default entry out of the box:
https://github.com/openshift/cluster-samples-operator/blob/release-4.1/pkg/stub/handler.go#L285-L303

@Gabe I opened the following PR to start calling out the information on Jenkins images in the Samples Operator documentation. It's a first pass, and I still need to address the registry setting and release notes. 

https://github.com/openshift/openshift-docs/pull/20124

We've added context and a warning, but are avoiding adding the `oc tag --source=docker ...` procedure to avoid potential complications. 

The PR is ready for QE review. 

https://github.com/openshift/openshift-docs/pull/20124

@Brandi A typo need fix, add comment in PR.
Other lgtm

@XiuJuan thank you! I've updated the PR with your and Michael's requests, and am going ahead with the merge + cherry pick.

Links to updated documentation: 

docs.openshift.com

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

https://docs.openshift.com/container-platform/4.4/openshift_images/configuring-samples-operator.html#samples-operator-overview_configuring-samples-operator

Customer Portal

https://access.redhat.com/documentation/en-us/openshift_container_platform/4.4/html-single/installing/index#installation-restricted-network-samples_installing-restricted-networks-preparations

https://access.redhat.com/documentation/en-us/openshift_container_platform/4.4/html-single/images/index#samples-operator-overview_configuring-samples-operator