diff --git a/doc/source/admin/how_it_works.rst b/doc/source/admin/how_it_works.rst new file mode 100644 index 000000000..494bf5e9a --- /dev/null +++ b/doc/source/admin/how_it_works.rst @@ -0,0 +1,117 @@ +How it works +============ + +Integration with Ironic +----------------------- + +Compatible Deploy Drivers +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Agent Deploy Driver +<<<<<<<<<<<<<<<<<<< +IPA works with the agent Deploy driver in Ironic to provision nodes. Starting +with ironic-python-agent running on a ramdisk on an unprovisioned node, +Ironic makes API calls to ironic-python-agent to provision the machine. This +allows for greater control and flexibility of the entire deployment process. + +PXE Deploy Driver +<<<<<<<<<<<<<<<<< +IPA may also be used with the original Ironic pxe driver as of the Kilo +OpenStack Ironic release. + +Configuring Deploy Drivers +<<<<<<<<<<<<<<<<<<<<<<<<<< +For information on how to install and configure Ironic drivers, including +drivers for IPA, see the Ironic drivers documentation [0]_. + +Lookup +~~~~~~ +On startup, the agent performs a lookup in Ironic to determine its node UUID +by sending a hardware profile to the Ironic lookup endpoint: +``/v1/lookup``. + +Heartbeat +~~~~~~~~~ +After successfully looking up its node, the agent heartbeats via +``/v1/heartbeat/{node_ident}`` every N seconds, where +N is the Ironic conductor's agent.heartbeat_timeout value multiplied by a +number between .3 and .6. + +For example, if your conductor's ironic.conf contains:: + + [agent] + heartbeat_timeout = 60 + +IPA will heartbeat between every 20 and 36 seconds. This is to ensure jitter +for any agents reconnecting after a network or API disruption. + +After the agent heartbeats, the conductor performs any actions needed against +the node, including querying status of an already run command. For example, +initiating in-band cleaning tasks or deploying an image to the node. + +Inspection +~~~~~~~~~~ +IPA can conduct hardware inspection on start up and post data to the `Ironic +Inspector`_. Edit your default PXE/iPXE configuration or IPA options +baked in the image, and set ``ipa-inspection-callback-url`` to the +full endpoint of Ironic Inspector, for example:: + + ipa-inspection-callback-url=http://IP:5050/v1/continue + +Make sure your DHCP environment is set to boot IPA by default. + +.. _Ironic Inspector: http://docs.openstack.org/ironic-inspector/ + +Hardware Inventory +------------------ +IPA collects various hardware information using its +:doc:`Hardware Managers <../contributor/hardware_managers>`, +and sends it to Ironic on lookup and to Ironic Inspector on Inspection_. + +The exact format of the inventory depends on the hardware manager used. +Here is the basic format expected to be provided by all hardware managers. +The inventory is a dictionary (JSON object), containing at least the following +fields: + +``cpu`` + CPU information: ``model_name``, ``frequency``, ``count``, + ``architecture`` and ``flags``. + +``memory`` + RAM information: ``total`` (total size in bytes), ``physical_mb`` + (physically installed memory size in MiB, optional). + + .. note:: + The difference is that the latter includes the memory region reserved + by the kernel and is always slightly bigger. It also matches what + the Nova flavor would contain for this node and thus is used by the + inspection process instead of ``total``. + +``bmc_address`` + IP address of the node's BMC (aka IPMI address), optional. + +``disks`` + list of disk block devices with fields: ``name``, ``model``, + ``size`` (in bytes), ``rotational`` (boolean), ``wwn``, ``serial``, + ``vendor``, ``wwn_with_extension``, ``wwn_vendor_extension``, ``hctl``. + +``interfaces`` + list of network interfaces with fields: ``name``, ``mac_address``, + ``ipv4_address``, ``lldp``, ``vendor``, ``product``, and optionally + ``biosdevname``(BIOS given NIC name). If configuration option + ``collect_lldp`` is set to True the ``lldp`` field will be populated + by a list of type-length-value(TLV) fields retrieved using the + Link Layer Discovery Protocol (LLDP). + +``system_vendor`` + system vendor information from SMBIOS as reported by ``dmidecode``: + ``product_name``, ``serial_number`` and ``manufacturer``. + +``boot`` + boot information with fields: ``current_boot_mode`` (boot mode used for + the current boot - BIOS or UEFI) and ``pxe_interface`` (interface used + for PXE booting, if any). + +References +========== +.. [0] Enabling Drivers - http://docs.openstack.org/ironic/latest/admin/drivers/ipa.html diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 000000000..b4545ed84 --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,26 @@ +================================== +Ironic Python Agent Administration +================================== + +Overview +======== + +Ironic Python Agent is an agent for controlling and deploying Ironic controlled +baremetal nodes. Typically run in a ramdisk, the agent exposes a REST API for +provisioning servers. + +Throughout the documentation, Ironic Python Agent will be +abbreviated to IPA. + +Index +===== + +.. toctree:: + how_it_works + troubleshooting + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/source/troubleshooting.rst b/doc/source/admin/troubleshooting.rst similarity index 100% rename from doc/source/troubleshooting.rst rename to doc/source/admin/troubleshooting.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index eee91d261..2303716a5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,134 +9,15 @@ Ironic Python Agent is an agent for controlling and deploying Ironic controlled baremetal nodes. Typically run in a ramdisk, the agent exposes a REST API for provisioning servers. -Throughout the documentation, Ironic Python Agent will be -abbreviated to IPA. - Index ===== .. toctree:: + :maxdepth: 1 - install/index - contributor/index - troubleshooting - -How it works -============ - -Integration with Ironic ------------------------ - -Compatible Deploy Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Agent Deploy Driver -<<<<<<<<<<<<<<<<<<< -IPA works with the agent Deploy driver in Ironic to provision nodes. Starting -with ironic-python-agent running on a ramdisk on an unprovisioned node, -Ironic makes API calls to ironic-python-agent to provision the machine. This -allows for greater control and flexibility of the entire deployment process. - -PXE Deploy Driver -<<<<<<<<<<<<<<<<< -IPA may also be used with the original Ironic pxe driver as of the Kilo -OpenStack Ironic release. - -Configuring Deploy Drivers -<<<<<<<<<<<<<<<<<<<<<<<<<< -For information on how to install and configure Ironic drivers, including -drivers for IPA, see the Ironic drivers documentation [0]_. - -Lookup -~~~~~~ -On startup, the agent performs a lookup in Ironic to determine its node UUID -by sending a hardware profile to the Ironic lookup endpoint: -``/v1/lookup``. - -Heartbeat -~~~~~~~~~ -After successfully looking up its node, the agent heartbeats via -``/v1/heartbeat/{node_ident}`` every N seconds, where -N is the Ironic conductor's agent.heartbeat_timeout value multiplied by a -number between .3 and .6. - -For example, if your conductor's ironic.conf contains:: - - [agent] - heartbeat_timeout = 60 - -IPA will heartbeat between every 20 and 36 seconds. This is to ensure jitter -for any agents reconnecting after a network or API disruption. - -After the agent heartbeats, the conductor performs any actions needed against -the node, including querying status of an already run command. For example, -initiating in-band cleaning tasks or deploying an image to the node. - -Inspection -~~~~~~~~~~ -IPA can conduct hardware inspection on start up and post data to the `Ironic -Inspector`_. Edit your default PXE/iPXE configuration or IPA options -baked in the image, and set ``ipa-inspection-callback-url`` to the -full endpoint of Ironic Inspector, for example:: - - ipa-inspection-callback-url=http://IP:5050/v1/continue - -Make sure your DHCP environment is set to boot IPA by default. - -.. _Ironic Inspector: http://docs.openstack.org/developer/ironic-inspector/ - -Hardware Inventory ------------------- -IPA collects various hardware information using its :ref:`Hardware Managers`, -and sends it to Ironic on lookup and to Ironic Inspector on Inspection_. - -The exact format of the inventory depends on the hardware manager used. -Here is the basic format expected to be provided by all hardware managers. -The inventory is a dictionary (JSON object), containing at least the following -fields: - -``cpu`` - CPU information: ``model_name``, ``frequency``, ``count``, - ``architecture`` and ``flags``. - -``memory`` - RAM information: ``total`` (total size in bytes), ``physical_mb`` - (physically installed memory size in MiB, optional). - - .. note:: - The difference is that the latter includes the memory region reserved - by the kernel and is always slightly bigger. It also matches what - the Nova flavor would contain for this node and thus is used by the - inspection process instead of ``total``. - -``bmc_address`` - IP address of the node's BMC (aka IPMI address), optional. - -``disks`` - list of disk block devices with fields: ``name``, ``model``, - ``size`` (in bytes), ``rotational`` (boolean), ``wwn``, ``serial``, - ``vendor``, ``wwn_with_extension``, ``wwn_vendor_extension``, ``hctl``. - -``interfaces`` - list of network interfaces with fields: ``name``, ``mac_address``, - ``ipv4_address``, ``lldp``, ``vendor``, ``product``, and optionally - ``biosdevname``(BIOS given NIC name). If configuration option - ``collect_lldp`` is set to True the ``lldp`` field will be populated - by a list of type-length-value(TLV) fields retrieved using the - Link Layer Discovery Protocol (LLDP). - -``system_vendor`` - system vendor information from SMBIOS as reported by ``dmidecode``: - ``product_name``, ``serial_number`` and ``manufacturer``. - -``boot`` - boot information with fields: ``current_boot_mode`` (boot mode used for - the current boot - BIOS or UEFI) and ``pxe_interface`` (interface used - for PXE booting, if any). - -References -========== -.. [0] Enabling Drivers - http://docs.openstack.org/developer/ironic/drivers/ipa.html + install/index + admin/index + contributor/index Indices and tables ==================