Added clarifications about customizing docker images

docs/examples.rst

@@ -15,29 +15,62 @@ should be addressed by the Ansible Creator Execution Environment project.
 
 .. _`Ansible Creator Execution Environment`: https://github.com/ansible/creator-ee
 
+Customizing the Docker Image Used by a Scenario/Platform
+========================================================
+
+The docker driver supports using pre-built images and ``docker build`` -ing
+local customizations for each scenario's platform. The Docker image used by a
+scenario is governed by the following configuration items:
+
+1. ``platforms[*].image``: Docker image name:tag to use as base image.
+2. ``platforms[*].pre_build_image``: Whether to customize base image or use
+   as-is[^1].
+
+    * When ``true``, use the specified ``platform[].image`` as-is.
+    * When ``false``, exec ``docker build`` to customize base image using
+      either:
+
+        * Dockerfile specified by ``platforms[*].dockerfile`` or
+        * Dockerfile rendered from ``Dockerfile.j2`` template (in scenario dir)
+
+The ``Dockerfile.j2`` template is generated at ``molecule init scenario``-time
+when ``--driver-name`` is ``docker``. The template can be customized as needed
+to create the desired modifications to the Docker image used in the scenario.
+
+Note: ``platforms[*].pre_build_image`` defaults to ``true`` in each scenario's
+generated `molecule.yml` file.
+
 Docker With Non-Privileged User
 ===============================
 
 The default Molecule Docker driver executes Ansible playbooks as the root user.
-If your workflow requires a non-privileged user, then adapt ``molecule.yml``
-and ``Dockerfile.j2`` as follows.
+If your workflow requires adding support for running as a non-privileged user,
+then adapt ``molecule.yml`` and ``Dockerfile.j2`` as follows.
 
-Append the following code block to the end of ``Dockerfile.j2``. It creates an
-``ansible`` user with passwordless sudo privileges.
+Note: The ``Dockerfile`` templating and image building processes are only done
+for scenarios with ``pre_build_image = False``, which is not the default
+setting in generated `molecule.yml` files.
 
-The variable ``SUDO_GROUP`` depends on the target distribution.
+To modify the Docker image to support running as normal user:
+
+Append the following code block to the end of ``Dockerfile.j2``. It creates an
+``ansible`` user with passwordless sudo privileges. Note the variable
+``SUDO_GROUP`` depends on the target distribution[^2].
 
 .. code-block:: docker
 
-    # Create `ansible` user with sudo permissions and membership in `DEPLOY_GROUP`
-    ENV ANSIBLE_USER=ansible SUDO_GROUP=wheel DEPLOY_GROUP=deployer
-    RUN set -xe \
-      && groupadd -r ${ANSIBLE_USER} \
-      && groupadd -r ${DEPLOY_GROUP} \
-      && useradd -m -g ${ANSIBLE_USER} ${ANSIBLE_USER} \
-      && usermod -aG ${SUDO_GROUP} ${ANSIBLE_USER} \
-      && usermod -aG ${DEPLOY_GROUP} ${ANSIBLE_USER} \
-      && sed -i "/^%${SUDO_GROUP}/s/ALL\$/NOPASSWD:ALL/g" /etc/sudoers
+   # Create `ansible` user with sudo permissions and membership in `DEPLOY_GROUP`
+   # This template gets rendered using `loop: "{{ molecule_yml.platforms }}"`, so
+   # each `item` is an element of platforms list from the molecule.yml file for this scenario.
+   ENV ANSIBLE_USER=ansible DEPLOY_GROUP=deployer
+   ENV SUDO_GROUP={{'sudo' if 'debian' in item.image else 'wheel' }}
+   RUN set -xe \
+     && groupadd -r ${ANSIBLE_USER} \
+     && groupadd -r ${DEPLOY_GROUP} \
+     && useradd -m -g ${ANSIBLE_USER} ${ANSIBLE_USER} \
+     && usermod -aG ${SUDO_GROUP} ${ANSIBLE_USER} \
+     && usermod -aG ${DEPLOY_GROUP} ${ANSIBLE_USER} \
+     && sed -i "/^%${SUDO_GROUP}/s/ALL\$/NOPASSWD:ALL/g" /etc/sudoers
 
 Modify ``provisioner.inventory`` in ``molecule.yml`` as follows:
 
@@ -394,3 +427,6 @@ issues.
 .. _GNU Parallel: https://www.gnu.org/software/parallel/
 .. _Pytest: https://docs.pytest.org/en/latest/
 .. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+[^1]: [Implementation in molecule-docker](https://github.com/ansible-community/molecule-docker/blob/f4efce3c4fda226c8ca5f10976927fff7daa8e69/src/molecule_docker/playbooks/create.yml#L35)
+[^2]: e.g. [Debian uses `sudo` instead of `wheel` group.](https://wiki.debian.org/sudo/)