diff --git a/doc/source/admin/fast-track.rst b/doc/source/admin/fast-track.rst index e429428181..25c1040f3b 100644 --- a/doc/source/admin/fast-track.rst +++ b/doc/source/admin/fast-track.rst @@ -48,23 +48,24 @@ node: 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``: +If using :ref:`in-band inspection`, you need to tell ironic or ironic-inspector +not to power off nodes afterwards. Depending on the inspection mode (managed or +unmanaged, with ironic-inspector or without), you need to configure two places. +In ``ironic.conf``: .. code-block:: ini [inspector] power_off = false -And in ``inspector.conf``: +And in ``inspector.conf`` (if needed): .. code-block:: ini [processing] power_off = false -Finally, you need to update the :ironic-inspector-doc:`inspection PXE -configuration ` to include the +Finally, you need to update the :ref:`inspection PXE/iPXE +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/inspection/inspector.rst b/doc/source/admin/inspection/inspector.rst index 5e0569b576..b6f6b4b4b7 100644 --- a/doc/source/admin/inspection/inspector.rst +++ b/doc/source/admin/inspection/inspector.rst @@ -32,54 +32,11 @@ configuration file must be set: add_ports = all keep_ports = present -There are two modes of in-band inspection: `managed inspection`_ and `unmanaged -inspection`_. +Managed and unmanaged inspection +-------------------------------- + +There are two modes of in-band inspection: *managed* inspection and *unmanaged* +inspection. See :doc:`/admin/inspection/managed` for more details. .. _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 conduct 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 adding kernel parameters for -inspection specifically. This is where you can configure -:ironic-python-agent-doc:`inspection collectors and other parameters -`, for example: - -.. code-block:: ini - - [inspector] - extra_kernel_params = ipa-inspection-collectors=default,logs ipa-collect-lldp=1 - -For the 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 -` for more information. - -If you want to **prevent** unmanaged inspection from working, set this option: - -.. code-block:: ini - - [inspector] - require_managed_boot = True diff --git a/doc/source/admin/inspection/managed.rst b/doc/source/admin/inspection/managed.rst index 5a3257fee4..93e17d227b 100644 --- a/doc/source/admin/inspection/managed.rst +++ b/doc/source/admin/inspection/managed.rst @@ -1,8 +1,66 @@ Managed and unmanaged inspection ================================ -In-band inspection can be *managed* or *unmanaged*. Please see :doc:`the -Inspector documentation ` for information on these concepts and -how to configure them. +In-band inspection can be *managed* or *unmanaged*. This document explains the +difference between these two concepts and applies both to the built-in in-band +inspection and to :doc:`/admin/inspection/inspector`. -.. TODO(dtantsur): migrate that information here once inspector is deprecated +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 conduct 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 adding kernel parameters for +inspection specifically. This is where you can configure +:ironic-python-agent-doc:`inspection collectors and other parameters +`, for example: + +.. code-block:: ini + + [inspector] + extra_kernel_params = ipa-inspection-collectors=default,logs ipa-collect-lldp=1 + +For the 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 + +For the built-in inspection, the bare metal API endpoint can be overriden +instead: + +.. code-block:: ini + + [service_catalog] + endpoint_override = https://example.com/baremetal + +.. _unmanaged-inspection: + +Unmanaged inspection +~~~~~~~~~~~~~~~~~~~~ + +Under *unmanaged* inspection we understand in-band inspection where the boot +configuration (iPXE scripts, DHCP options, etc) is not provided +by the Bare Metal service. In this case, the node is simply set to boot from +network and powered on. The operator is responsible for the correct network +boot configuration, e.g. as explained in :ref:`configure-unmanaged-inspection`. + +Unmanaged inspection 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. + +Unmanaged inspection is currently enabled by default but will be disabled +in the near future. To enable it, set ``require_managed_boot`` to ``False``: + +.. code-block:: ini + + [inspector] + require_managed_boot = False diff --git a/doc/source/install/configure-pxe.rst b/doc/source/install/configure-pxe.rst index 863ff15497..76808f4b71 100644 --- a/doc/source/install/configure-pxe.rst +++ b/doc/source/install/configure-pxe.rst @@ -469,3 +469,125 @@ those paths will be created using configuration parameter the configuration parameter ``[pxe]file_permission``. Absolute destination paths are not supported and will result in ironic failing to start up as it is a misconfiguration of the deployment. + +.. _configure-unmanaged-inspection: + +Configuring unmanaged in-band inspection +---------------------------------------- + +This section must be followed if you intend to use :ref:`unmanaged-inspection` +without ironic-inspector. For ironic-inspector support, check `its installation +guide +`_. + +With PXE +~~~~~~~~ + +After you followed `TFTP Server Setup`_, you need to create the default PXE +configuration. Populate ``/tftpboot/pxelinux.cfg/default`` with the following +contents:: + + default introspect + + label introspect + kernel ironic-python-agent.kernel + append initrd=ironic-python-agent.initramfs ipa-inspection-callback-url=http://{IP}:6385/v1/continue_inspection systemd.journald.forward_to_console=yes + + ipappend 3 + +Instead of ``http://{IP}:6385/v1/continue_inspection``, insert the correct Bare +Metal API endpoint, keeping the mandatory ``/v1/continue_inspection`` suffix. +You may also populate other IPA options (e.g. ``ipa-debug=1`` for detailed +logging, ``ipa-inspection-collectors`` to customize the inspection process, +or ``ipa-api-url`` to enable :doc:`/admin/fast-track`). + +Second, you need to configure DHCP for unknows hosts since the OpenStack +Networking service won't be able to handle them. For instance, you can install +**dnsmasq** and use the following ``/etc/dnsmasq.conf``: + +.. code-block:: ini + + port=0 + interface={INTERFACE} + bind-interfaces + dhcp-range={DHCP IP RANGE, e.g. 192.168.0.50,192.168.0.150} + enable-tftp + tftp-root=/tftpboot + dhcp-boot=pxelinux.0 + dhcp-sequential-ip + +.. warning:: + Ironic currently lacks `PXE filters + `_ + used by ironic-inspector to allow its DHCP server to co-exist with + OpenStack Networking (neutron) on the same network. Unless you can + physically isolation the inspection network, you may want to stay with + ironic-inspector for the time being. + +Finally, build or download IPA images into +``/tftpboot/ironic-python-agent.kernel`` and +``/tftpboot/ironic-python-agent.initramfs``. These can be the same images that +you use for deployment and cleaning. + +With iPXE +~~~~~~~~~ + +iPXE configuration is pretty similar to PXE above, but differs in details. +Start with `iPXE Setup`_, then create a new file ``/httpboot/inspection.ipxe`` +with the following contents:: + + #!ipxe + + :retry_dhcp + dhcp || goto retry_dhcp + + :retry_boot + imgfree + kernel --timeout 30000 http://{IP}:8080/ironic-python-agent.kernel ipa-inspection-callback-url=http://{IP}:6385/v1/continue_inspection systemd.journald.forward_to_console=yes BOOTIF=${mac} initrd=ironic-python-agent.initramfs || goto retry_boot + initrd --timeout 30000 http://{IP}:8080/ironic-python-agent.initramfs || goto retry_boot + boot + +Just as `with PXE`_, adjust ``ipa-inspection-callback-url`` to match your +deployment and add any required IPA options. You also need to fix ``{IP}:8080`` +to match the iPXE server you configured previously. + +The DHCP configuration is much more complex. Since most hardware does not have +an up-to-date iPXE firmware, you need to bootstrap it from TFTP. The +**dnsmasq** configuration may look roughly like this: + +.. code-block:: ini + + port=0 + interface={INTERFACE} + bind-interfaces + dhcp-range={DHCP IP RANGE, e.g. 192.168.0.50,192.168.0.150} + enable-tftp + tftp-root=/tftpboot + dhcp-sequential-ip + dhcp-match=ipxe,175 + dhcp-match=set:efi,option:client-arch,7 + dhcp-match=set:efi,option:client-arch,9 + dhcp-match=set:efi,option:client-arch,11 + # dhcpv6.option: Client System Architecture Type (61) + dhcp-match=set:efi6,option6:61,0007 + dhcp-match=set:efi6,option6:61,0009 + dhcp-match=set:efi6,option6:61,0011 + dhcp-userclass=set:ipxe6,iPXE + # Client is already running iPXE; move to next stage of chainloading + dhcp-boot=tag:ipxe,http://{IP}:8080/inspection.ipxe + # Client is PXE booting over EFI without iPXE ROM, + # send EFI version of iPXE chainloader + dhcp-boot=tag:efi,tag:!ipxe,ipxe.efi + dhcp-option=tag:efi6,tag:!ipxe6,option6:bootfile-url,tftp://{IP}/ipxe.efi + # Client is running PXE over BIOS; send BIOS version of iPXE chainloader + dhcp-boot=undionly.kpxe,localhost.localdomain,{IP} + +.. note:: + It's not trivial to write such a configuration from scratch. In addition to + this document, you may take some inspiration from `Bifrost + `_ + and `Metal3 + `_. + +Finally, put ``ironic-python-agent.kernel`` and +``ironic-python-agent.initramfs`` to ``/httpboot``.