Recently we discussed the validity of testing a scenario where the operator and operand (UpdateService instance) run in separate namespace. The operator itself declares OwnNamespace an only supported install mode. This means the only supported mode of operation is that the operator and its operands must be installed in the same namespace. While discussing this with QE, we discovered that the relevant documentation could stress this more:

https://docs.openshift.com/container-platform/4.16/updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.html#update-service-create-service-cli_updating-restricted-network-cluster-osus

Ideally we should steer the users to use the recommended namespace openshift-update-service on the happy path (right now our wording kinda suggests otherwise):

Installing the OpenShift Update Service Operator by using the web console -> Procedure -> 2d says:

Select a namespace for Installed Namespace or accept the recommended namespace openshift-update-service.

In the web console path, this is the only place where we likely need more information. Web console path does not even allow users to create UpdateService instances in different namespaces, but it is probably worth adding the information that the selected namespace is where the updateservice will be deployed via the operator.

The CLI path is more complicated and references namespace multiple times. I think we could add an explicit decision to the start of the "Install operator" procedure, similarly to how later "Install operand" has it - set a NAMESPACE=openshift-update-service variable and then make the following steps to use it (use oc -n $NAMESPACE create ... in the instructions. We should stress out that all subsequently created resources need to be created in that namepace, and additionally, the targetNamespace in the OperatorGroup created in step 2 must match it as well.

Then, the "create operand" section should use a stronger language about namespace selection. The namespace must the the one where the operator was created, there's no choice here Right now it says "The namespace must match the targetNamespaces value from the operator group." which is technically correct but not prominent enough.