advanced_install: installer image

Update, simplify, and also note some things that were not apparent about
running as a system container.
Rearrange containerized install material to enable discussion of running
it as a Docker container.

Author: sosiouxme

install_config/install/advanced_install.adoc

@@ -2296,115 +2296,181 @@ If for any reason the installation fails, before re-running the installer, see
 xref:installer-known-issues[Known Issues] to check for any specific
 instructions or workarounds.
 
-[[running-the-advanced-installation-system-container]]
+[[running-the-advanced-installation-containerized]]
 === Running the Containerized Installer
 
-include::install_config/install/advanced_install.adoc[tag=syscontainers_techpreview]
-
 The
 ifdef::openshift-enterprise[]
 *openshift3/ose-ansible*
 endif::[]
 ifdef::openshift-origin[]
 *openshift/origin-ansible*
 endif::[]
-image is a containerized version of the {product-title} installer that runs as a
-link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html/managing_containers/running_system_containers[system container]. System containers are stored and run outside of the traditional
-*docker* service. Functionally, using the containerized installer is the same as
-using the traditional RPM-based installer, except it is running in a
-containerized environment instead of directly on the host.
+image is a containerized version of the {product-title} installer.
+This installer image provides the same functionality as the RPM-based
+installer, but it runs in a containerized environment that provides all
+of its dependencies rather than being installed directly on the host.
+The only requirement to use it is the ability to run a container.
 
-. Use the Docker CLI to pull the image locally:
-+
-----
-ifdef::openshift-enterprise[]
-$ docker pull registry.access.redhat.com/openshift3/ose-ansible:v3.7
-endif::[]
-ifdef::openshift-origin[]
-$ docker pull docker.io/openshift/origin-ansible:v3.7
-endif::[]
-----
+[[running-the-advanced-installation-system-container]]
+==== Running the Installer as a System Container
 
-. The installer system container must be stored in
-link:https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/content_management_guide/managing_ostree_content[OSTree]
-instead of defaulting to *docker* daemon storage. Use the Atomic CLI to import
-the installer image from the local *docker* engine to OSTree storage:
-+
-----
-$ atomic pull --storage ostree \
-ifdef::openshift-enterprise[]
-    docker:registry.access.redhat.com/openshift3/ose-ansible:v3.7
-endif::[]
-ifdef::openshift-origin[]
-    docker:docker.io/openshift/origin-ansible:v3.7
-endif::[]
-----
+include::install_config/install/advanced_install.adoc[tag=syscontainers_techpreview]
+
+The installer image can be used as a
+link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html/managing_containers/running_system_containers[system container].
+System containers are stored and run outside of the traditional *docker* service.
+This enables running the installer image from one of the target hosts without
+concern for the install restarting *docker* on the host.
 
-. Install the system container so it is set up as a systemd service:
+. As the `root` user, use the Atomic CLI to run the installer as a run-once system container:
 +
 ----
-$ atomic install --system \
+# atomic install --system \
     --storage=ostree \
-    --name=openshift-installer \//<1>
-    --set INVENTORY_FILE=/path/to/inventory \//<2>
+    --set INVENTORY_FILE=/path/to/inventory \//<1>
 ifdef::openshift-enterprise[]
-    docker:registry.access.redhat.com/openshift3/ose-ansible:v3.7
+    registry.access.redhat.com/openshift3/ose-ansible:v3.7
 endif::[]
 ifdef::openshift-origin[]
-    docker:docker.io/openshift/origin-ansible:v3.7
+    docker.io/openshift/origin-ansible:v3.7
 endif::[]
 ----
-<1> Sets the name for the systemd service.
-<2> Specify the location for your inventory file on your local workstation.
-
-. Use the `systemctl` command to start the installer service as you would any
-other systemd service. This command initiates the cluster installation:
+<1> Specify the location on the local host for your inventory file.
 +
-----
-$ systemctl start openshift-installer
-----
+This command initiates the cluster installation using the inventory file specified and the `root` user's
+SSH configuration, logging to the terminal as well as *_/var/log/ansible.log_*. The first time this is executed, the image is imported into
+link:https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/content_management_guide/managing_ostree_content[OSTree]
+storage (system containers use this instead of *docker* daemon storage).
+Later executions re-use the stored image.
 +
 If for any reason the installation fails, before re-running the installer, see
 xref:installer-known-issues[Known Issues] to check for any specific instructions
 or workarounds.
 
-. After the installation completes, you can uninstall the system container if you want. However, if you need to run the installer again to run any other playbooks later, you would have to follow this procedure again.
-+
-To uninstall the system container:
-+
-----
-$ atomic uninstall openshift-installer
-----
-
 [[running-the-advanced-installation-system-container-other-playbooks]]
 ==== Running Other Playbooks
 
-After you have completed the cluster installation, if you want to later run any
-other playbooks using the containerized installer (for example, cluster upgrade
-playbooks), you can use the `PLAYBOOK_FILE` environment variable. The default
-value is `playbooks/byo/config.yml`, which is the main cluster installation
-playbook, but you can set it to the path of another playbook inside the
-container.
+To run any other playbooks (for example, to run the
+xref:configuring-cluster-pre-install-checks[pre-install checks]
+before proceeding to install) using the containerized installer, you can
+specify a playbook with the `PLAYBOOK_FILE` environment variable. The
+default value is *_/usr/share/ansible/openshift-ansible/playbooks/byo/config.yml_*, which is the main cluster
+installation playbook, but you can set it to the path of another playbook
+inside the container.
 
 For example:
 
 ----
-$ atomic install --system \
+# atomic install --system \
     --storage=ostree \
-    --name=openshift-installer \
-    --set INVENTORY_FILE=/etc/ansible/hosts \
-    --set PLAYBOOK_FILE=playbooks/byo/openshift-cluster/upgrades/v3_7/upgrade.yml \//<1>
+    --set INVENTORY_FILE=/path/to/inventory \
+    --set PLAYBOOK_FILE=/usr/share/ansible/openshift-ansible/playbooks/byo/openshift-checks/pre-install.yml \//<1>
+    --set OPTS="-v" \//<2>
 ifdef::openshift-enterprise[]
-    docker:registry.access.redhat.com/openshift3/ose-ansible:v3.7
+    registry.access.redhat.com/openshift3/ose-ansible:v3.7
 endif::[]
 ifdef::openshift-origin[]
-    docker:docker.io/openshift/origin-ansible:v3.7
+    docker.io/openshift/origin-ansible:v3.7
 endif::[]
 ----
-<1> Set `PLAYBOOK_FILE` to the relative path of the playbook starting at the
-*_playbooks/_* directory. Playbooks mentioned elsewhere in {product-title}
-documentation assume use of the RPM-based installer, so use this relative path
-instead when using the containerized installer.
+<1> Set `PLAYBOOK_FILE` to the full path of the playbook starting at the
+*_playbooks/_* directory. Playbooks are located in the same locations as with
+the RPM-based installer.
+<2> Set `OPTS` to add command line options to `ansible-playbook`.
+
+[[running-the-advanced-installation-docker]]
+==== Running the Installer as a Docker Container
+
+The installer image can also run as a *docker* container anywhere that *docker* can run.
+
+[WARNING]
+====
+This method should not be used to run the installer on one of the hosts being configured,
+as the install typically restarts *docker* on the host, which would disrupt the installer
+container's own execution.
+====
+
+[NOTE]
+====
+Although this method and the system container method above use the same image, they
+run with different entry points and contexts, so runtime parameters are not the same.
+====
+
+At a minimum, when running the installer as a *docker* container you must provide:
+
+* SSH key(s) so that Ansible can reach your hosts.
+* An Ansible inventory file.
+* The location of an Ansible playbook to run against that inventory.
+
+Here is an example of how to run an install via *docker*.
+Note that this must be run by a non-`root` user with access to *docker*.
+
+----
+$ docker run -t -u `id -u` \
+    -v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z \
+    -v $HOME/ansible/hosts:/tmp/inventory:Z \
+    -e INVENTORY_FILE=/tmp/inventory \
+    -e PLAYBOOK_FILE=playbooks/byo/config.yml \
+    -e OPTS="-v" \
+ifdef::openshift-enterprise[]
+    registry.access.redhat.com/openshift3/ose-ansible:v3.7
+endif::[]
+ifdef::openshift-origin[]
+    docker.io/openshift/origin-ansible:v3.7
+endif::[]
+----
+
+The following is a detailed explanation of the options used in the command above.
+
+* `-u `id -u`` makes the container run with the same UID as the current
+user, which allows that user to use the SSH key inside the container (SSH
+private keys are expected to be readable only by their owner).
+
+* `-v $HOME/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa:Z` mounts your
+SSH key (`$HOME/.ssh/id_rsa`) under the container user's `$HOME/.ssh`
+(*_/opt/app-root/src_* is the `$HOME` of the user in the container). If
+you mount the SSH key into a non-standard location you can add an
+environment variable with `-e ANSIBLE_PRIVATE_KEY_FILE=/the/mount/point`
+or set `ansible_ssh_private_key_file=/the/mount/point` as a variable in
+the inventory to point Ansible at it.
++
+Note that the SSH key is mounted with the `:Z` flag: this is
+required so that the container can read the SSH key under
+its restricted SELinux context; this also means that your
+original SSH key file will be re-labeled to something like
+`system_u:object_r:container_file_t:s0:c113,c247`. For more details
+about `:Z` please check the `docker-run(1)` man page. Keep this in mind
+when providing these volume mount specifications because this could
+have unexpected consequences: for example, if you mount (and therefore
+re-label) your whole `$HOME/.ssh` directory it will block the host's
+*sshd* from accessing your public keys to login. For this reason you
+may want to use a separate copy of the SSH key (or directory), so that
+the original file labels remain untouched.
+
+* `-v $HOME/ansible/hosts:/tmp/inventory:Z` and `-e INVENTORY_FILE=/tmp/inventory`
+mount a static Ansible inventory file into the container as
+*_/tmp/inventory_* and set the corresponding environment variable to
+point at it. As with the SSH key, the inventory file SELinux labels may
+need to be relabeled via the `:Z` flag to allow reading in the container,
+depending on the existing label (for files in a user `$HOME` directory
+this is likely to be needed). So again you may prefer to copy the
+inventory to a dedicated location before mounting it.
++
+The inventory file can also be downloaded from a web server if you specify
+the `INVENTORY_URL` environment variable, or generated dynamically using
+`DYNAMIC_SCRIPT_URL` to specify an executable script that provides a
+dynamic inventory.
+
+* `-e PLAYBOOK_FILE=playbooks/byo/config.yml` specifies the playbook
+to run (in this example, the BYO installer) as a relative path from the
+top level directory of *openshift-ansible* content. The full path from the
+RPM can also be used, as well as the path to any other playbook file in
+the container.
+
+* `-e OPTS="-v"` supplies arbitrary command line options (in this case,
+`-v` to increase verbosity) to the `ansible-playbook` command that runs
+inside the container.
 
 [[running-the-advanced-installation-individual-components]]
 === Running Individual Component Playbooks