From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id EFF0F1FF13C for ; Thu, 30 Apr 2026 14:49:35 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id CDCF975D5; Thu, 30 Apr 2026 14:49:35 +0200 (CEST) From: Christoph Heiss To: pdm-devel@lists.proxmox.com Subject: [PATCH datacenter-manager v4 24/40] docs: add documentation for auto-installer integration Date: Thu, 30 Apr 2026 14:46:53 +0200 Message-ID: <20260430124712.1614305-25-c.heiss@proxmox.com> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260430124712.1614305-1-c.heiss@proxmox.com> References: <20260430124712.1614305-1-c.heiss@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1777553267545 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.075 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_SHORT 0.001 Use of a URL Shortener for very short URL SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: XONNZBWBLATGDBGUG5WOLYKWFW2LS4PD X-Message-ID-Hash: XONNZBWBLATGDBGUG5WOLYKWFW2LS4PD X-MailFrom: c.heiss@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Datacenter Manager development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Christoph Heiss --- Changes v3 -> v4: * document minijinja as new templating engine * improve token section wording a bit Changes v2 -> v3: * use concrete URL in example * add section about templating and token authentication Changes v1 -> v2: * new patch docs/automated-installations.rst | 146 +++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 147 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..8fe964b --- /dev/null +++ b/docs/automated-installations.rst @@ -0,0 +1,146 @@ +.. _automated_installations: + +Automated Installations +======================= + +The Proxmox Datacenter Manager provides integration with the automated +installer for all Proxmox products. + +A detailed documentation of all available options can be found on `our dedicated +wiki page `_. + +.. _autoinst_overview: + +Overview +~~~~~~~~ + +The overview shows all past and ongoing installations done 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 what target filters have been defined for +that particular configuration. + +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 +`_. + +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_templating: + +Templating +^^^^^^^^^^ + +Certain fields support templating via `MiniJinja`_ (a Jinja2-inspired templating +engine) and sequential *counters*. +Counters are automatically incremented each time an answer file is served to a +client, allowing for easy provisioning of unique fields, such as per-system +hostnames. + +The following counter is automatically defined when creating a new prepared +answer configuration: + +* ``installation_nr`` - Counter of the number of installations done with this + particular answer configuration. + +This mechanism allows templating on the following fields for prepared answer +configurations: + +* **Administrator email address** +* **Hostname/FQDN** +* **Network IP address (CIDR)** +* **Network gateway** +* **DNS Server address** + +The templating context provided for each field contains the `system information +data`_ as sent by the automated installer on answer retrieval, as well as all +template counters. + +For example, to provide a unique hostname to each target system, the following +template can be used for the **Hostname/FQDN** field: + +.. code-block:: + + {{ product.product }}{{ installation_nr }}.example.com + +MiniJinja features a wide range of `built-in filters`_, which are enabled by +default, similar to Jinja2. + +.. _autoinst_token: + +Authentication token management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To use the automated installer integration of Proxmox Datacenter Manager, an +installation process must authenticate itself. This also provides for an +additional scoping mechanism for prepared answer configurations. + +The automated installer integration uses a dedicated token mechanism, separate +from the normal API tokens. See the example under :ref:`autoinst_preparing_iso` +on how to include such a token in the ISO when preparing it. + +.. _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:///api2/json/auto-install/answer``, where ```` 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://datacenter.example.com/api2/json/auto-install/answer' \ + --cert-fingerprint 'ab:cd:ef:12:34:56:78:90:a1:b2:c3:d4:e5:f6:7a:8b:9c:0d:aa:bb:cc:dd:ee:ff:21:43:65:87:09:af:bd:ce' \ + --answer-auth-token 'mytoken!ee2a5901-1910-4eb0-b0a2-c914f4adbb75' + +.. _JSON Pointers: https://www.rfc-editor.org/rfc/rfc6901 +.. _fetch an answer via HTTP: https://pve.proxmox.com/edwiki/Automated_Installation#Answer_Fetched_via_HTTP +.. _Filters: https://pve.proxmox.com/wiki/Automated_Installation#Filters +.. _target URL: https://pve.proxmox.com/wiki/Automated_Installation#Answer_Fetched_via_HTTP +.. _system information data: https://pve.proxmox.com/wiki/Automated_Installation#System_information_POST_data +.. _MiniJinja: https://docs.rs/minijinja/latest/minijinja/index.html +.. _built-in filters: https://docs.rs/minijinja/latest/minijinja/filters/index.html#built-in-filters 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.53.0