From c41e07f31342af4fa5d79bb5ef1e0746f6f0cf9a Mon Sep 17 00:00:00 2001
From: Chris Peterson <chris.peterson@canonical.com>
Date: Thu, 21 Sep 2023 11:52:56 -0700
Subject: [PATCH] docs: reflect autoinstall options and precedence

---
 doc/intro-to-autoinstall.rst | 60 ++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 16 deletions(-)

diff --git a/doc/intro-to-autoinstall.rst b/doc/intro-to-autoinstall.rst
index 79f5881e09..a34be5eae5 100644
--- a/doc/intro-to-autoinstall.rst
+++ b/doc/intro-to-autoinstall.rst
@@ -78,24 +78,52 @@ Autoinstall on the install media
 Another option for supplying autoinstall to the Ubuntu installer is to place a
 file named :code:`autoinstall.yaml` on the install media itself.
 
-There are two potential locations for the :code:`autoinstall.yaml` file:
- * At the root of the "CD-ROM". When you write the installation ISO to a USB
-   Flash Drive, this can be done by copying the :code:`autoinstall.yaml` to the
-   partition containing the contents of the ISO - i.e.,
-   in the directory containing the ``casper`` sub-directory.
- * On the rootfs of the installation system - this option will typically
-   require modifying the installation ISO and is not suggested, but is
-   supported.
-
-Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not
-require a :code:`#cloud-config` header, and does not use a top level
-``autoinstall:`` key. The autoinstall directives are placed at the top
-level. For example:
+There are two potential locations that subiquity will check for the
+:code:`autoinstall.yaml` file:
 
-.. code-block:: yaml
+* At the root of the "CD-ROM". When you write the installation ISO to a USB
+  Flash Drive, this can be done by copying the :code:`autoinstall.yaml` to the
+  partition containing the contents of the ISO - i.e.,
+  in the directory containing the ``casper`` sub-directory.
+* On the rootfs of the installation system - this option will typically
+  require modifying the installation ISO and is not suggested, but is
+  supported.
+
+Alternatively, you can pass the location of the autoinstall file on the kernel
+command line via the :code:`subiquity.autoinstallpath` parameter, where the
+path is relative to the rootfs of the installation system. For example:
+
+* :code:`subiquity.autoinstallpath=path/to/autoinstall.yaml`
+
+Similarly, you can pass the location to subiquity directly when invoking it via
+the :code:`--autoinstall <path>` flag, where the path is relative to the
+rootfs of the installation system.
+
+.. note::
+
+    Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not
+    require a :code:`#cloud-config` header, and does not use a top level
+    ``autoinstall:`` key. The autoinstall directives are placed at the top
+    level. For example:
+
+    .. code-block:: yaml
+
+        version: 1
+        ....
+
+
+Order precedence of the autoinstall locations
+======================================
+
+Since there are many ways to specify the autoinstall file, it may happen that
+multiple locations are specified at once. Subiquity will look for the
+autoinstall file in the following order and pick the first existing one:
 
-    version: 1
-    ....
+1. Subiquity command line
+2. Kernel command line
+3. Root of the installation system
+4. Cloud Config
+5. Root of the CD-ROM (ISO)
 
 
 Cloud-init and autoinstall interaction