Merge "Document managed inspection"

doc/source/admin/inspection.rst

@@ -98,11 +98,62 @@ the following option:
 
 In order to ensure that ports in Bare Metal service are synchronized with
 NIC ports on the node, the following settings in the ironic-inspector
-configuration file must be set::
+configuration file must be set:
+
+.. code-block:: ini
 
     [processing]
     add_ports = all
     keep_ports = present
 
+There are two modes of in-band inspection: `managed inspection`_ and `unmanaged
+inspection`_.
+
 .. _ironic-inspector: https://pypi.org/project/ironic-inspector
 .. _python-ironicclient: https://pypi.org/project/python-ironicclient
+
+Managed inspection
+~~~~~~~~~~~~~~~~~~
+
+Inspection is *managed* when the Bare Metal conductor fully configures the node
+for inspection, including setting boot device, boot mode and power state. This
+is the only way to conductor inspection using :ref:`redfish-virtual-media` or
+with :doc:`/admin/dhcp-less`. This mode is engaged automatically when the node
+has sufficient information to configure boot (e.g. ports in case of iPXE).
+
+There are a few configuration options that tune managed inspection, the most
+important is ``extra_kernel_params``, which allows add kernel parameters for
+inspection specifically. This is where you can configure
+:ironic-python-agent-doc:`inspection collectors and other parameters
+<admin/how_it_works.html#inspection>`, for example:
+
+.. code-block:: ini
+
+   [inspector]
+   extra_kernel_params = ipa-inspection-collectors=default,logs ipa-collect-lldp=1
+
+For callback URL the ironic-inspector endpoint from the service catalog is
+used. If you want to override the endpoint for callback only, set the following
+option:
+
+.. code-block:: ini
+
+   [inspector]
+   callback_endpoint_override = https://example.com/baremetal-introspection/v1/continue
+
+Unmanaged inspection
+~~~~~~~~~~~~~~~~~~~~
+
+Under *unmanaged* inspection we understand in-band inspection orchestrated by
+ironic-inspector or a third party. This was the only inspection mode before the
+Ussuri release, and it is still used when the node's boot cannot be configured
+by the conductor. The options described above do not affect unmanaged
+inspection. See :ironic-inspector-doc:`ironic-inspector installation guide
+<install/index.html>` for more information.
+
+If you want to **prevent** unmanaged inspection from working, set this option:
+
+.. code-block:: ini
+
+   [inspector]
+   require_managed_boot = True