Document fast-track and the agent power interface

To prevent the administrator guide from growing too long, split
away advanced topics (i.e. stuff we don't expect most of admins
to read, use or understand).

Story: #2007771
Task: #40382
Change-Id: Ia3e3178692c96aaebdd4479e865a56fbe63c820a

4 files changed, 143 insertions, 6 deletions

diff --git a/doc/source/admin/agent-power.rst b/doc/source/admin/agent-power.rst
new file mode 100644
index 000000000..b948733ee
--- /dev/null
+++ b/doc/source/admin/agent-power.rst
@@ -0,0 +1,76 @@
+=================================
+Deploying without BMC Credentials
+=================================
+
+The Bare Metal service usually requires BMC credentials for all provisioning
+operations. Starting with the Victoria release series there is limited support
+for inspection, cleaning and deployments without the credentials.
+
+.. warning::
+   This feature is experimental and only works in a limited scenario. When
+   using it, you have to be prepared to provide BMC credentials in case of
+   a failure or any non-supported actions.
+
+How it works
+============
+
+The expected workflow is as follows:
+
+#. The node is discovered by manually powering it on and gets the
+   `manual-management` hardware type and `agent` power interface.
+
+   If discovery is not used, a node can be enrolled through the API and then
+   powered on manually.
+
+#. The operator moves the node to `manageable`. It works because the `agent`
+   power only requires to be able to connect to the agent.
+
+#. The operator moves the node to `available`. Cleaning happens normally via
+   the already running agent. If reboot is needed, it is done by telling the
+   agent to reboot the node in-band.
+
+#. A user deploys the node. Deployment happens normally via the already
+   running agent.
+
+#. In the end of the deployment, the node is rebooted via the reboot command
+   instead of power off+on.
+
+Enabling
+========
+
+:doc:`fast-track` is a requirement for this feature to work. After enabling it,
+adds the ``agent`` power interface and the ``manual-management`` hardware type
+to the enabled list:
+
+.. code-block:: ini
+
+   [DEFAULT]
+   enabled_hardware_types = manual-management
+   enabled_management_interfaces = noop
+   enabled_power_interfaces = agent
+
+   [deploy]
+   fast_track = true
+
+As usual with the ``noop`` management, enable the networking boot fallback:
+
+.. code-block:: ini
+
+   [pxe]
+   enable_netboot_fallback = true
+
+If using discovery, :ironic-inspector-doc:`configure discovery in
+ironic-inspector <user/usage.html#discovery>` with the default driver set
+to ``manual-management``.
+
+Limitations
+===========
+
+* Only the ``noop`` network interface is supported.
+
+* Undeploy and rescue are not supported, you need to add BMC credentials first.
+
+* If any errors happens in the process, recovery will likely require BMC
+  credentials.
+
+* Only rebooting is possible through the API, power on/off commands will fail.
diff --git a/doc/source/admin/fast-track.rst b/doc/source/admin/fast-track.rst
new file mode 100644
index 000000000..464966da8
--- /dev/null
+++ b/doc/source/admin/fast-track.rst
@@ -0,0 +1,50 @@
+=====================
+Fast-Track Deployment
+=====================
+
+*Fast track* is a mode of operation where the Bare Metal service keeps a
+machine powered on with the agent running between provisioning operations.
+It is first booted during in-band inspection or cleaning (whatever happens
+first) and is only shut down before rebooting into the final instance.
+Depending on the configuration, this mode can save several reboots and is
+particularly useful for scenarios where nodes are enrolled, prepared and
+provisioned within a short period of time.
+
+.. warning::
+   Fast track deployment targets standalone use cases and is only tested with
+   the ``noop`` networking. The case where inspection, cleaning and
+   provisioning networks are different is not supported.
+
+Enabling
+========
+
+Fast track is off by default and should be enabled in the configuration:
+
+.. code-block:: ini
+
+   [deploy]
+   fast_track = true
+
+Inspection
+----------
+
+If using :ref:`in-band inspection`, you need to tell ironic-inspector not to
+power off nodes afterwards. Depending on the inspection mode (managed or
+unmanaged), you need to configure two places. In ``ironic.conf``:
+
+.. code-block:: ini
+
+   [inspector]
+   power_off = false
+
+And in ``inspector.conf``:
+
+.. code-block:: ini
+
+   [processing]
+   power_off = false
+
+Finally, you need to update the :ironic-inspector-doc:`inspection PXE
+configuration <install/index.html#configuration>` to include the
+``ipa-api-url`` kernel parameter, pointing at the **ironic** endpoint, in
+addition to the existing ``ipa-inspection-callback-url``.
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 4815be3c3..5154aa39b 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -23,18 +23,27 @@ the services.
    Port Groups <portgroups>
    Configuring Web or Serial Console <console>
    Enabling Notifications <notifications>
-   Ceph Object Gateway <radosgw>
-   Emitting Software Metrics <metrics>
-   Auditing API Traffic <api-audit-support>
-   Service State Reporting <gmr>
    Conductor Groups <conductor-groups>
    Upgrade Guide <upgrade-guide>
    Security <security>
-   Windows Images <building-windows-images>
    Troubleshooting FAQ <troubleshooting>
    Power Sync with the Compute Service <power-sync>
-   Agent Token <agent-token>
    Node Multi-Tenancy <node-multitenancy>
+   Fast-Track Deployment <fast-track>
+
+Advanced Topics
+---------------
+
+.. toctree::
+  :maxdepth: 1
+
+   Ceph Object Gateway <radosgw>
+   Windows Images <building-windows-images>
+   Emitting Software Metrics <metrics>
+   Auditing API Traffic <api-audit-support>
+   Service State Reporting <gmr>
+   Agent Token <agent-token>
+   Deploying without BMC Credentials <agent-power>
 
 .. toctree::
   :hidden:
diff --git a/doc/source/admin/inspection.rst b/doc/source/admin/inspection.rst
index f403c0bbc..41605f1b1 100644
--- a/doc/source/admin/inspection.rst
+++ b/doc/source/admin/inspection.rst
@@ -68,6 +68,8 @@ for scheduling::
 Please see a specific :doc:`hardware type page </admin/drivers>` for
 the exact list of capabilities this hardware type can discover.
 
+.. _in-band inspection:
+
 In-band inspection
 ------------------