Description of problem:

The docs at https://docs.openshift.com/container-platform/4.16/openshift_images/using-imagestreams-with-kube-resources.html recommend referring to ImageStreams in k8s workloads by setting the Imagestream.spec.lookupPolicy.local field to true, then referencing the image stream by short name and tag in the workload, e.g. Deployment.spec.template.containers.image might reference "imagestreamname:latest" for some imagestream.

This feature is known broken since RHOS 4.8 per https://bugzilla.redhat.com/show_bug.cgi?id=2000216 and KB errata https://access.redhat.com/solutions/6455191 

The documentation should not recommend its use. It should be updated to suggest that workloads be deployed using full container registry URLs instead. Or at minimum it should at minimum link prominently to the errata KB indicating that the feature does not work.

The feature only works when the workload is first created; if the image is changed in the workload after initial creation, no resolution is performed, and the workload will instead create pods with image: imagestreamname:latest. This cause the Pod to fail to pull with an error like

Failed to pull image "imagestreamname:latest": reading manifest latest in docker.io/library/imagestreamname: requested access to the resource is denied

The bug tracking this issue is closed, referring to the workaround KB errata. But the KB says:

> For a permanent fix, you can track bug 2000216

... but that's the bug closed as "ERRATA" referring to the KB. So there's some circular reasoning here, and the need for an actual fix seems to have become lost along the way.

Version-Release number of selected component (if applicable):

    4.16 4.17

How reproducible:

100%    

Steps to Reproduce:

    1. Create an ImageStream/imagestreamname with a tag "imagestreamtag"
    2. Create a Kustomization that defines a Deployment that references the ImageStream using .spec.template.spec.containers.image=imagestreamname:imagestreamtag      3. "kustomize build | oc apply --server-side -f -" to apply your Deployment
    4. Verify that the Deployment's .spec.template.spec.containers.image is rewritten to the RHOS internal registry URI like  registry.redhat.io/workload-namespace-here/imagestreamname@sha256:somedigesthere, a Pod is created, and the Pod pulls the image fine
    5. Repeat the same apply command again to rewrite the Deployment's image
    6. Verify that the image reference in the deployment is now "imagestreamname:imagestreamtag", it has not been rewritten
    7. observe "oc events" which will show pull errors for "docker.io/library" relating to the image

Actual results:

deployment has .spec.template.spec.containers[0].image = imagestreamname:imagestreamtag

pod for deployment in ImagePullBackoff

kube events like:

Warning   Failed                            Pod/some-pod                         Failed to pull image "imagestreamname:imagestreamtag": reading manifest latest in docker.io/library/imagestreamname: requested access to the resource is denied

Expected results:

Deployment should have the image updated by RHOS to expand the imagestream tag when the deployment is patched to change the image.

Additional info:

Known bug, incorrectly closed, and the docs don't warn about it.