[stable/2023.1] Add documentation about image builds (#1304)
This is an automated cherry-pick of #1301
/assign mnaser
diff --git a/doc/source/arch/images.rst b/doc/source/arch/images.rst
new file mode 100644
index 0000000..8ca423b
--- /dev/null
+++ b/doc/source/arch/images.rst
@@ -0,0 +1,97 @@
+======
+Images
+======
+
+*************
+Build Process
+*************
+
+This section provides an overview of how the container images used by Atmosphere
+are built. Understanding this process is crucial for maintaining and customizing
+the images for your specific needs.
+
+Multi-Stage Builds
+==================
+
+The images are built using a multi-stage build process. This means that all
+build-time dependencies are included only in the intermediate stages and are not
+present in the final runtime images.
+
+Benefits
+--------
+
+The multi-stage build process offers several benefits which improve the
+efficiency, security, and performance of the images.
+
+Smaller Image Size
+^^^^^^^^^^^^^^^^^^
+
+By excluding build-time dependencies, the final images are significantly
+smaller. This reduction in size offers several advantages.
+
+First, it leads to more efficient storage usage, as smaller images consume less
+disk space, making it easier to manage and store multiple images. Additionally,
+the reduced image size results in faster download times when pulling images from
+a container registry, thereby speeding up deployment times.
+
+Furthermore, smaller images require less network bandwidth, which can be beneficial
+in environments with limited network resources.
+
+Enhanced Security
+^^^^^^^^^^^^^^^^^
+
+Reducing the number of packages and dependencies in the final image decreases
+the attack surface, thereby enhancing security. With only essential runtime
+dependencies included, the opportunities for attackers to exploit
+vulnerabilities are significantly reduced, leading to minimized exposure.
+
+Moreover, a smaller set of packages simplifies auditing, making it easier to
+ensure that all components are secure and up-to-date. Additionally, fewer
+dependencies mean fewer updates and patches, which simplifies the maintenance
+process and reduces the risk of introducing new vulnerabilities.
+
+Improved Performance
+^^^^^^^^^^^^^^^^^^^^
+
+Smaller images lead to faster deployment times and lower resource consumption,
+which improves overall system performance. Containers based on smaller images
+start up more quickly, enhancing the responsiveness of applications and services.
+
+Reduced resource consumption translates to lower memory and CPU usage, allowing
+more efficient utilization of system resources. Furthermore, faster deployment
+and efficient resource use enable better scalability, allowing the system to
+handle increased loads more effectively.
+
+Example
+-------
+
+The ``openstack-venv-builder`` image is used to build a virtual environment with
+all of the Python dependencies required by the OpenStack services. It also
+contains a modified version of the ``upper-constraints.txt`` file, which has
+many of the dependencies pinned to specific versions and modified to avoid
+security vulnerabilities.
+
+.. literalinclude:: ../../../images/openstack-venv-builder/Dockerfile
+ :language: dockerfile
+ :caption: ``images/openstack-venv-builder/Dockerfile``
+
+In addition to that image, the ``openstack-python-runtime`` image is a stripped
+down base image as a run-time for OpenStack services with no installed
+packages than the base Ubuntu image.
+
+.. literalinclude:: ../../../images/openstack-runtime/Dockerfile
+ :language: dockerfile
+ :caption: ``images/openstack-runtime/Dockerfile``
+
+With the ``openstack-venv-builder`` & ``openstack-python-runtime`` the image for
+a project such as OpenStack Nova can be built using the following Dockerfile.
+
+This Dockerfile uses the ``openstack-venv-builder`` image to build the virtual
+environment and then copies the virtual environment into the final image based
+on the ``openstack-python-runtime`` image. With this, it has no other build-time
+dependencies and only the runtime dependencies required for the OpenStack Nova
+service.
+
+.. literalinclude:: ../../../images/nova/Dockerfile
+ :language: dockerfile
+ :caption: ``images/nova/Dockerfile``
diff --git a/doc/source/arch/index.rst b/doc/source/arch/index.rst
new file mode 100644
index 0000000..f48d570
--- /dev/null
+++ b/doc/source/arch/index.rst
@@ -0,0 +1,8 @@
+############
+Architecture
+############
+
+.. toctree::
+ :maxdepth: 2
+
+ images
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f7150fc..38b7906 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -24,6 +24,7 @@
:caption: Contents:
quick-start
+ arch/index
config/index
deploy/index
admin/index