Details:

OpenShift Sandboxed Containers (OSC) documentation should methodically clarify where commands given as examples should run.

In the context of OSC, many different contexts should be considered whenever a shell command is issued:

1. In most cases, commands are run from a client, using something like oc to control the cluster, or like az to access Azure. Let's call this context "client".
2. Commands can also be run from within the worker node. When not running peer-pods, this is also the virtual machine host, but because of the peer-pods case, we should not call it "host". So let's call this context "worker"
3. Some commands have to specifically be run on the virtual machine host, whether it's the same as the worker node or not. Let's call this context "host".
4. Some commands have to be run in the virtual machine (VM) itself, for example operations related to the guest kernel. Let's call this context "vm".
5. In the case of Sandboxed Containers, the virtual machine also matches a pod, but it may be better to specifically distinguish operations that are related to the fact that we deal with a pod, e.g. mounting storage. Let's call this context "pod".
6. Finally, some commands may have to be issued from within the container itself. Let's call this context "container".

The proposal is that we should ensure we indicate any context other than "client" before the $ sign indicating a shell command.

In the linked documentation, we have an example of the first case ("client") with 

$ RESOURCE_GROUP=$(oc get cm -n openshift-sandboxed-containers-operator peer-pods-cm -o jsonpath='{.data.AZURE_RESOURCE_GROUP}')

or

$ az image list -g ${RESOURCE_GROUP} --query '[].id' -o tsv

I would leave those as is.

We also have examples of code that must run in the pod, which I would modify to use pod$ prefix as follows:

pod$ mount -o remount,size=4G /var/lib/containers

In the documentation as is, we have a specific annotation indicating to use oc rsh to connect to the pod. That should be part of the main documentation, and a link to it stating "Here is how to run a command in the pod" should be added to any element of the release note that must run in the pod context.

Similarly, we should document how to access the container context, e.g. using oc exec.

For the VM context.I think that oc rsh should work in all cases, but I'd like bpradipt to check if we need to have special wording for peer-pods vs. non-peer cases.

For the worker context, I think that OpenShift recommends to use a debug pod, i.e. using oc debug to access the node. When using kcli, there is a kcli ssh command to access the nodes directly, but otherwise you need to know the ssh keys.

For the host context, I don't think there is a readily available way to do it when using a public cloud. When you are using bare metal, then it's typically ssh. Let's hope we never have to document this context  

Documentation URL:

https://content-stage.docs.redhat.com/en/documentation/openshift_sandboxed_containers/1.8