From e7ac427ccb745c6cefe20c7a8646121ac1a35475 Mon Sep 17 00:00:00 2001
From: Julien Cristau <jcristau@mozilla.com>
Date: Wed, 22 Jan 2025 11:38:34 +0100
Subject: [PATCH] docs: add to docker howto

Describe the `parent`, `definition` and `args` entries supported by the
docker_image transforms.
---
 docs/howto/docker.rst | 59 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/howto/docker.rst b/docs/howto/docker.rst
index 89a5fc853..44c0cdcaf 100644
--- a/docs/howto/docker.rst
+++ b/docs/howto/docker.rst
@@ -201,6 +201,65 @@ process the ``Dockerfile`` and handle the special syntax. Whereas the
 only generated once and then re-used by all subsequent pushes until the image
 is modified.
 
+Layering images on top of each other
+....................................
+
+The ``parent`` value on a docker-image task can refer to another image's ``name``.
+The parent image can then be referenced from the dependent image's Dockerfile
+as ``$DOCKER_IMAGE_PARENT``.  Whenever the base image's definition (or
+something it includes) changes, that automatically also triggers a
+rebuild of the dependent image.
+
+For example, ``kind.yml`` could include:
+
+.. code-block:: yaml
+
+  tasks:
+    base:
+      symbol: I(base)
+    extras:
+      symbol: I(extras)
+      parent: base
+
+And the ``extras`` image's Dockerfile:
+
+.. code-block::
+
+  FROM $DOCKER_IMAGE_PARENT
+
+  RUN apt-get update && apt-get install -y extra software && apt-get clean
+
+
+.. note::
+   The ``taskgraph build-image`` command doesn't handle this syntax, so it won't work for those images.
+   In taskcluster this is handled by the ``image_builder`` tool, see
+   `the image_builder docker image <https://hub.docker.com/r/mozillareleases/image_builder>`_ and
+   `its source code <https://searchfox.org/mozilla-central/source/taskcluster/docker/image_builder>`_.
+
+
+Reusing image definitions
+.........................
+
+The same ``Dockerfile`` can be used for multiple images, by setting ``definition``, for example:
+
+.. code-block:: yaml
+
+  tasks:
+      debian12:
+          symbol: I(deb12)
+          definition: debian
+          args:
+              BASE_IMAGE: debian:12
+      debian11:
+          symbol: I(deb11)
+          definition: debian
+          args:
+              BASE_IMAGE: debian:11
+
+Both the ``debian11`` and ``debian12`` images will be built from the definition in
+``taskcluster/docker/debian``, but they'll be passed different ``BASE_IMAGE``
+variables (as in ``docker build --build-arg``).
+
 Context Directory Hashing
 ~~~~~~~~~~~~~~~~~~~~~~~~~