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

[Lukas Wagner]

Hi,

two comments inline.

On Fri Dec 5, 2025 at 12:25 PM CET, Christoph Heiss wrote:
> Signed-off-by: Christoph Heiss <c.heiss at 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

I think there is something missing in the first sentence here?

> +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"

Maybe use some concrete example URL here? Mainly to demonstrate that
most people would need to include the port as well.

> +
> +.. _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