[pdm-devel] [PATCH datacenter-manager v2 14/14] docs: add documentation for auto-installer integration

[Christoph Heiss <c.heiss@proxmox.com>]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
Changes v1 -> v2:
  * new patch

 docs/automated-installations.rst | 83 ++++++++++++++++++++++++++++++++
 docs/index.rst                   |  1 +
 2 files changed, 84 insertions(+)
 create mode 100644 docs/automated-installations.rst

diff --git a/docs/automated-installations.rst b/docs/automated-installations.rst
new file mode 100644
index 0000000..eef591b
--- /dev/null
+++ b/docs/automated-installations.rst
@@ -0,0 +1,83 @@
+.. _automated_installations:
+
+Automated Installations
+=======================
+
+The Proxmox Datacenter Manager provides integration with the automated
+installer available across all Proxmox products.
+
+A detailed documentation for all available options can be found on
+`our wiki <https://pve.proxmox.com/wiki/Automated_Installation>`_.
+
+.. _autoinst_overview:
+
+Overview
+~~~~~~~~
+
+The overview shows all past and ongoing installations using the Proxmox
+Datacenter Manager. It allows access to the raw system information data as sent
+by the automated installer before the actual installation and (if configured)
+post-installation notification hook data, containing extensive information about
+the newly installed system.
+
+.. _autoinst_answers:
+
+Prepared Answers
+~~~~~~~~~~~~~~~~
+
+This view provides an overview over all defined answer files and allows editing,
+copying into new answers and deleting them. For a quick overview, it shows
+whether an answer is the default and/or what target filters have been defined.
+
+Target filter
+^^^^^^^^^^^^^
+
+Target filter allow you to control what systems should match.
+
+Filters are key-value pairs in the format ``key=format``, with keys being `JSON
+Pointers`_, and match systems based the identifying information sent by the
+installer as JSON document. An example of such a document is provided `on the
+wiki <https://pve.proxmox.com/wiki/Automated_Installation#System_information_POST_data>`_.
+
+JSON Pointers allow for identifying specific values within a JSON document. For
+example, to match only Proxmox VE installations by the product name, a filter
+entry like ``/product/product=pve`` can be used.
+
+Values are *globs* and use the same syntax as the automated installer itself.
+The following special characters can be used in filters:
+
+* ``?`` -- matches any single character
+* ``*`` -- matches any number of characters, can be none
+* ``[a]``, ``[abc]``, ``[0-9]`` -- matches any single character inside the brackets, ranges are possible
+* ``[!a]`` -- negate the filter, any single character but the ones specified
+
+A prepared answer can be also set as default, in which case it will be used if
+no other more specific answer matches based on its configured target filters.
+
+.. _autoinst_preparing_iso:
+
+Preparing an ISO
+~~~~~~~~~~~~~~~~
+
+To use an installation ISO of a Proxmox product with the Proxmox Datacenter
+Manager functionality, the ISO must be appropriately prepared to `fetch an
+answer via HTTP`_ from the Proxmox Datacenter Manager using the
+``proxmox-auto-install-assistant`` tool, available from the Proxmox VE package
+repositories.
+
+The `target URL`_ for the automated installer must point to
+``https://<pdm>/api2/json/auto-install/answer``, where ``<pdm>`` is the address
+under which the Proxmox Datacenter Manager is reachable from the systems to be
+installed.
+
+For example:
+
+.. code-block:: shell
+
+   proxmox-auto-install-assistant prepare-iso /path/to/source.iso \
+     --fetch-from http \
+     --url "https://<pdm>/api2/json/auto-install/answer"
+
+.. _JSON Pointers: https://www.rfc-editor.org/rfc/rfc6901
+.. _fetch an answer via HTTP: https://pve.proxmox.com/wiki/Automated_Installation#Answer_Fetched_via_HTTP
+.. _target URL: https://pve.proxmox.com/wiki/Automated_Installation#Answer_Fetched_via_HTTP
diff --git a/docs/index.rst b/docs/index.rst
index 8398f57..2fc8a5d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,6 +25,7 @@ in the section entitled "GNU Free Documentation License".
    web-ui.rst
    sdn-integration.rst
    remotes.rst
+   automated-installations.rst
    views.rst
    access-control.rst
    sysadmin.rst
-- 
2.51.2



_______________________________________________
pdm-devel mailing list
pdm-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pdm-devel