diff --git a/doc/source/deploy/drivers.rst b/doc/source/deploy/drivers.rst index c14f6dd1aa..370dbbcd0c 100644 --- a/doc/source/deploy/drivers.rst +++ b/doc/source/deploy/drivers.rst @@ -7,19 +7,11 @@ Enabling drivers Ironic-Python-Agent (agent) --------------------------- -To enable IPA, add the appropriate ironic agent driver to the ``enabled_drivers`` -line of the ironic.conf file. +Ironic-Python-Agent is an agent that handles *ironic* bare metal +nodes in various actions such as inspection and deployment of such +nodes, and runs processes inside of a ramdisk. -Several variants are currently supported, they are: - * agent_ilo - * agent_ipmitool - * agent_pyghmi - * agent_ssh - * agent_vbox - -.. note:: Starting with the Kilo release IPA ramdisk may also be used with ironic PXE drivers. - -For more information see the `ironic-python-agent GitHub repo <https://github.com/openstack/ironic-python-agent/>`_ +For more information on this, see :ref:`IPA`. DRAC ---- diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst index 0681ef54f7..b586379eae 100644 --- a/doc/source/deploy/user-guide.rst +++ b/doc/source/deploy/user-guide.rst @@ -211,6 +211,13 @@ Deploy Process #. Images from Glance are pulled down to the local disk of the Ironic conductor servicing the bare metal node. + #. For pxe_* drivers these include all images: both the deploy ramdisk and + user instance images. + + #. For agent_* drivers only the deploy ramdisk is stored locally. Temporary + URLs in OpenStack's Object Storage service are created for user instance + images. + #. Virtual interfaces are plugged in and Neutron API updates DHCP port to support PXE/TFTP options. @@ -222,10 +229,16 @@ Deploy Process #. The IPMI driver issues command to enable network boot of a node and power it on. -#. The DHCP boots the deploy ramdisk. The PXE driver actually copies the image - over iSCSI to the physical node. It connects to the iSCSI end point, - partitions volume, "dd" the image and closes the iSCSI connection. The - deployment is done. The Ironic conductor will switch pxe config to service +#. The DHCP boots the deploy ramdisk. Next, depending on the exact driver + used, either the conductor copies the image over iSCSI to the physical node + (pxe_* group of drivers) or the deploy ramdisk downloads the image from + a temporary URL (agent_* group of drivers), which can be generated by + a variety of object stores, e.g. *swift*, *radosgw*, etc, and uploaded + to OpenStack's Object Storage service. In the former case, the conductor + connects to the iSCSI end point, partitions volume, "dd" the image and + closes the iSCSI connection. + + The deployment is done. The Ironic conductor will switch pxe config to service mode and notify ramdisk agent on the successful deployment. #. The IPMI driver reboots the bare metal node. Note that there are 2 power @@ -236,8 +249,10 @@ Deploy Process #. The bare metal node status is updated and the node instance is made available. -Example 1: PXE Deploy Process --------------------------------- +Example 1: PXE Boot and iSCSI Deploy Process +-------------------------------------------- + +This process is used with pxe_* family of drivers. .. seqdiag:: :scale: 80 @@ -277,8 +292,10 @@ Example 1: PXE Deploy Process (From a `talk`_ and `slides`_) -Example 2: Agent Deploy Process ---------------------------------- +Example 2: PXE Boot and Direct Deploy Process +---------------------------------------------- + +This process is used with agent_* family of drivers. .. seqdiag:: :scale: 80 diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index 5ea560dd93..aaf718f0b3 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -351,8 +351,9 @@ Switch to the stack user and clone DevStack:: git clone https://github.com/openstack-dev/devstack.git devstack Create devstack/local.conf with minimal settings required to enable Ironic. -Note that Ironic under devstack can only support running *either* the PXE -or the agent driver, not both. The default is the PXE driver.:: +You can use either of two drivers for deploy: pxe_* or agent_*, see :ref:`IPA` +for explanation. An example local.conf that enables both types of drivers +and uses the ``pxe_ssh`` driver by default:: cd devstack cat >local.conf <<END @@ -363,6 +364,8 @@ or the agent driver, not both. The default is the PXE driver.:: RABBIT_PASSWORD=password SERVICE_PASSWORD=password SERVICE_TOKEN=password + SWIFT_HASH=password + SWIFT_TEMPURL_KEY=password # Enable Ironic API and Ironic Conductor enable_service ironic @@ -379,6 +382,12 @@ or the agent driver, not both. The default is the PXE driver.:: enable_service q-meta enable_service neutron + # Enable Swift for agent_* drivers + enable_service s-proxy + enable_service s-object + enable_service s-container + enable_service s-account + # Disable Horizon disable_service horizon @@ -388,10 +397,21 @@ or the agent driver, not both. The default is the PXE driver.:: # Disable Cinder disable_service cinder c-sch c-api c-vol + # Swift temp URL's are required for agent_* drivers. + SWIFT_ENABLE_TEMPURLS=True + # Create 3 virtual machines to pose as Ironic's baremetal nodes. IRONIC_VM_COUNT=3 IRONIC_VM_SSH_PORT=22 IRONIC_BAREMETAL_BASIC_OPS=True + IRONIC_DEPLOY_DRIVER_ISCSI_WITH_IPA=True + + # Enable Ironic drivers. + IRONIC_ENABLED_DRIVERS=fake,agent_ssh,agent_ipmitool,pxe_ssh,pxe_ipmitool + + # Change this to alter the default driver for nodes created by devstack. + # This driver should be in the enabled list above. + IRONIC_DEPLOY_DRIVER=pxe_ssh # The parameters below represent the minimum possible values to create # functional nodes. @@ -401,6 +421,9 @@ or the agent driver, not both. The default is the PXE driver.:: # Size of the ephemeral partition in GB. Use 0 for no ephemeral partition. IRONIC_VM_EPHEMERAL_DISK=0 + # To build your own IPA ramdisk from source, set this to True + IRONIC_BUILD_DEPLOY_RAMDISK=False + VIRT_DRIVER=ironic # By default, DevStack creates a 10.0.0.0/24 network for instances. @@ -417,31 +440,6 @@ or the agent driver, not both. The default is the PXE driver.:: END -If running with the agent driver (instead of PXE driver), add these additional -settings to local.conf:: - - cat >>local.conf <<END - # Agent driver requires swift with tempurls - # Enable swift services - enable_service s-proxy - enable_service s-object - enable_service s-container - enable_service s-account - - # Enable tempurls and set credentials - SWIFT_HASH=password - SWIFT_TEMPURL_KEY=password - SWIFT_ENABLE_TEMPURLS=True - - # Enable agent driver - IRONIC_ENABLED_DRIVERS=fake,agent_ssh,agent_ipmitool - IRONIC_DEPLOY_DRIVER=agent_ssh - - # To build your own IPA ramdisk from source, set this to True - IRONIC_BUILD_DEPLOY_RAMDISK=False - - END - Run stack.sh:: ./stack.sh diff --git a/doc/source/drivers/ipa.rst b/doc/source/drivers/ipa.rst new file mode 100644 index 0000000000..7cbe842abd --- /dev/null +++ b/doc/source/drivers/ipa.rst @@ -0,0 +1,49 @@ +.. _IPA: + +=================== +Ironic Python Agent +=================== + +Overview +======== + +*Ironic Python Agent* (also often called *IPA* or just *agent*) is a +Python-based agent which handles *ironic* bare metal nodes in a +variety of actions such as inspect, configure, clean and deploy images. +IPA is distributed over nodes and runs, inside of a ramdisk, the +process of booting this ramdisk on the node. + +For more information see the `ironic-python-agent documentation +<http://docs.openstack.org/developer/ironic-python-agent/>`_. + +Drivers +======= + +Starting with the Kilo release all drivers (except for fake ones) are using +IPA for deployment. There are two types of them, which can be distinguished +by prefix: + +* For drivers with ``pxe_`` or ``iscsi_`` prefix IPA exposes the root hard + drive as an iSCSI share and calls back to the ironic conductor. The + conductor mounts the share and copies an image there. It then signals back + to IPA for post-installation actions like setting up a bootloader for local + boot support. + +* For drivers with ``agent_`` prefix the conductor prepares a swift temporary + URL for an image. IPA then handles the whole deployment process: + downloading an image from swift, putting it on the machine and doing any + post-deploy actions. + +Which one to choose depends on your environment. iSCSI-based drivers put +higher load on conductors, agent-based drivers currently require the whole +image to fit in the node's memory. + +.. todo: other differences? + +.. todo: explain configuring swift for temporary URL's + +Requirements +~~~~~~~~~~~~ + +Using IPA requires it to be present and configured on the deploy ramdisk, see +:ref:`BuildingDeployRamdisk` for details. diff --git a/doc/source/index.rst b/doc/source/index.rst index 0d265b78bb..f7627e5a80 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -39,6 +39,7 @@ Overview Installation Guide <deploy/install-guide> Upgrade Guide <deploy/upgrade-guide> Configuration Reference (Liberty) <http://docs.openstack.org/liberty/config-reference/content/ch_configuring-openstack-bare-metal.html> + drivers/ipa deploy/drivers deploy/cleaning