From 624ea7d94640f855d181acb9956eb715a96a9d9d Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Tue, 15 Feb 2022 15:01:53 +0100 Subject: [PATCH] Continue decomposing the "How to" documentation * Move DHCP information into a document of its own. * Move custom IPA building to installation guide. * Separate the remote Ironic section. Change-Id: I766e5ccd2569ea58e84be5fbc063df6cf5e0ca54 --- doc/source/install/index.rst | 18 ++++++++ doc/source/user/dhcp.rst | 7 ++-- doc/source/user/howto.rst | 79 +++++++++++++----------------------- doc/source/user/index.rst | 1 + 4 files changed, 51 insertions(+), 54 deletions(-) diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index d00cc4aad..74839e444 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -303,6 +303,24 @@ The Ansible variables generated for installation are stored in a JSON file (``bifrost-install-env.json`` by default) that should be passed via the ``-e`` flag to subsequent playbook or command invokations. +.. _custom-ipa-images: + +Build Custom Ironic Python Agent (IPA) images +============================================= + +Bifrost supports the ability for a user to build a custom IPA ramdisk +utilizing diskimage-builder and ironic-python-agent-builder. In order +to utilize this feature, the ``download_ipa`` setting must be set to ``false`` +and the create_ipa_image must be set to "true". By default, the install +playbook will build a Debian Bullseye based IPA image, if a pre-existing IPA +image is not present on disk. If you wish to explicitly set a specific release +to be passed to diskimage-create, then the setting ``dib_os_release`` can be +set in addition to ``dib_os_element``. + +If you wish to include an extra element into the IPA disk image, such as a +custom hardware manager, you can pass the variable ``ipa_extra_dib_elements`` +as a space-separated list of elements. This defaults to an empty string. + Using Bifrost ============= diff --git a/doc/source/user/dhcp.rst b/doc/source/user/dhcp.rst index 5ea9f2ed7..d79c94ced 100644 --- a/doc/source/user/dhcp.rst +++ b/doc/source/user/dhcp.rst @@ -46,7 +46,7 @@ dnsmasq, which will cause it to reread its configuration:: killall -HUP dnsmasq Using Bifrost with your own DHCP server -======================================= +--------------------------------------- The possibility exists that a user may already have a Dynamic Host Configuration Protocol (DHCP) server on their network. @@ -66,7 +66,8 @@ What is required: not support ICMP redirects. Example DHCP server configurations ----------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + In the examples below port 8080 is used. However, the port number may vary depending on the environment configuration. @@ -87,7 +88,7 @@ Internet Systems Consortium DHCPd:: Architecture ------------- +~~~~~~~~~~~~ It should be emphasized that Ironic in standalone mode is intended to be used only in a trusted environment. diff --git a/doc/source/user/howto.rst b/doc/source/user/howto.rst index df37455cd..d33fc7ca3 100644 --- a/doc/source/user/howto.rst +++ b/doc/source/user/howto.rst @@ -96,7 +96,7 @@ The JSON format resembles the data structure that ironic utilizes internally. ``mac`` - MAC address of the port. * ``ansible_ssh_host`` and ``ipv4_address`` are expected IP addresses of the - node once it is deployed. See also `Configuring the integrated DHCP server`_. + node once it is deployed. See also :doc:`dhcp`. Example: @@ -198,36 +198,17 @@ manually at the moment. Additionally, it is important to note that the playbooks for enrollment are split into three separate playbooks based on the ``ipmi_bridging`` setting. -Using a remote ironic ---------------------- - -When ironic is installed on remote server, a regular ansible inventory -with a target server should be added to ansible. This can be achieved by -specifying a directory with files, each file in that directory will be part of -the ansible inventory. Refer to ansible documentation -http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources - -.. code-block:: bash - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - cd playbooks - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ enroll-dynamic.yaml - .. _deploy: Deploy Hardware =============== -How this works? ---------------- - After the nodes are enrolled, they can be deployed upon. Bifrost is geared to utilize configuration drives to convey basic configuration information to the each host. This configuration information includes an SSH key to allow a user to login to the system. -To utilize the newer dynamic inventory based deployment: +To utilize the dynamic inventory based deployment: .. code-block:: bash @@ -268,22 +249,6 @@ If the hosts need to be re-deployed, the dynamic redeploy playbook may be used: This playbook will undeploy the hosts, followed by a deployment, allowing a configurable timeout for the hosts to transition in each step. -Using a remote ironic ---------------------- - -When ironic is installed on remote server, a regular ansible inventory -with a target server should be added to ansible. This can be achieved by -specifying a directory with files, each file in that directory will be part of -the ansible inventory. Refer to ansible documentation -http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources - -.. code-block:: bash - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - cd playbooks - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ deploy-dynamic.yaml - Deployment and configuration of operating systems ================================================= @@ -308,25 +273,37 @@ Due to the nature of the design, it would be relatively easy for a user to import automatic growth or reconfiguration steps either in the image to be deployed, or in post-deployment steps via custom Ansible playbooks. +Advanced topics +=============== + +Using a remote ironic +--------------------- + +When ironic is installed on remote server, a regular ansible inventory +with a target server should be added to ansible. This can be achieved by +specifying a directory with files, each file in that directory will be part of +the ansible inventory. Refer to ansible documentation +http://docs.ansible.com/ansible/intro_dynamic_inventory.html#using-inventory-directories-and-multiple-inventory-sources. +Example: + +.. code-block:: bash + + export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + cd playbooks + rm inventory/*.example + ansible-playbook -vvvv -i inventory/ enroll-dynamic.yaml + Build Custom Ironic Python Agent (IPA) images -============================================= +--------------------------------------------- -Bifrost supports the ability for a user to build a custom IPA ramdisk -utilizing diskimage-builder and ironic-python-agent-builder. In order -to utilize this feature, the ``download_ipa`` setting must be set to ``false`` -and the create_ipa_image must be set to "true". By default, the install -playbook will build a Debian Bullseye based IPA image, if a pre-existing IPA -image is not present on disk. If you wish to explicitly set a specific release -to be passed to diskimage-create, then the setting ``dib_os_release`` can be -set in addition to ``dib_os_element``. +Content moved, see :ref:`custom-ipa-images`. -If you wish to include an extra element into the IPA disk image, such as a -custom hardware manager, you can pass the variable ``ipa_extra_dib_elements`` -as a space-separated list of elements. This defaults to an empty string. +Configuring the integrated DHCP server +-------------------------------------- -.. include:: dhcp.rst +Content moved, see :doc:`dhcp`. Use Bifrost with Keystone -========================= +------------------------- Content moved, see :doc:`keystone`. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 70b8f2bfc..b7553d52d 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -12,3 +12,4 @@ this documentation serves as a blend of both Admin and User documentation. howto troubleshooting keystone + dhcp