Add mechanism for patching files in containers

This patch adds a way to patch files in a Docker
image built by Kolla. This is very useful for several
reasons, specifically:

- Custom modifications
- The stable branch of some library has a fix but no pip
  package has been released
- Eliminates the need to package your own pip packages
- Eliminates the need to invent your own versioning to prevent
  upstream versioning
- Eliminates the need to manage a pip server
- In other words, it eliminates the need to get a wheel into
  the image and install it manually using any method not
  previously mentioned

It is also highly desirable because, although Kolla can replace
the source for a service with a custom URL for a tarball or its
own Git repo, it cannot do this for dependencies pulled from pip.

I would also like to point out that this is a feature with its own
code path and works only if the user "inserts" a patch into the folder
patches/docker-image/something.patch and creates an analogous series
file for patch source code.

Simply said, this code will never interfere with the upstream build process
since this feature is not intended for use in upstream.
It is rather meant for downstream users who know what they are doing.
Now they just have an option to patch their images.

Everything works on all layers of the Docker image and stores a report
of applied patches which can then be seen in /etc.

This mechanism is similar as debian patch quilt.

Change-Id: I61d0790c5d4d070b7ea9e8c99c0a76ff5d22bf9d

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst
index aad3c33a3..3f7de30e7 100644
--- a/doc/source/admin/image-building.rst
+++ b/doc/source/admin/image-building.rst
@@ -301,6 +301,59 @@ To remove a package from that list, say ``locales``, one would do:
 An example of this is the Grafana plugins, which are mentioned in the next
 section.
 
+Patching customization
+----------------------
+
+Kolla provides functionality to apply patches to Docker images during the build
+process. This allows users to modify existing files or add new ones as part of
+the image creation.
+
+You need to define a ``patches_path`` in the ``[DEFAULT]`` section of
+the ``/etc/kolla/kolla-build.conf`` file. This directory will be used to store
+patches for the images.
+
+.. path etc/kolla/kolla-build.conf
+.. code-block:: ini
+
+  [DEFAULT]
+  patches_path = /path/to/your/patches
+
+Create a directory for each image you want to patch, following a directory
+structure similar to the Debian patch quilt format. Refer to
+`quilt documentation <https://linux.die.net/man/1/quilt>`_. for more details.
+
+- ``<patches_path>/image_name/`` : The directory for the specific image.
+- ``<patches_path>/image_name/some-patch`` : Contains the patch content.
+- ``<patches_path>/image_name/another-patch`` : Contains the patch content.
+- ``<patches_path>/image_name/series`` : Lists the order in which the patches
+  will be applied.
+
+For example, if you want to patch the ``nova-api`` image, the structure would
+look like this:
+
+.. code-block:: console
+
+   /path/to/your/patches/nova-api/some-patch
+   /path/to/your/patches/nova-api/another-patch
+   /path/to/your/patches/nova-api/series
+
+The ``series`` file should list the patches in the order they should be
+applied:
+
+.. code-block:: console
+
+   some-patch
+   another-patch
+
+When the images are built using ``kolla-build``, the patches defined in the
+``patches_path`` will automatically be applied to the corresponding images.
+
+After the patches are applied, Kolla stores information about the applied
+patches in ``/etc/kolla/patched``. The patch files themselves are stored
+in the ``/patches`` directory within the image. This allows you to track
+which patches have been applied to each image for debugging or
+verification purposes.
+
 Grafana plugins
 ^^^^^^^^^^^^^^^