From 40842895fcd6e44e3d4f7c57de95ca373f9b1c43 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 6 Jan 2022 12:23:00 +0100 Subject: [PATCH] Clean up the "How to" documentation Fix formatting, add missing field descriptions, add instance_info example. Change-Id: Ibc97430efed26b35f941e31c6280f3cf387efc17 --- doc/source/user/dhcp.rst | 8 +- doc/source/user/howto.rst | 176 +++++++++++++++++++++++++++----------- 2 files changed, 131 insertions(+), 53 deletions(-) diff --git a/doc/source/user/dhcp.rst b/doc/source/user/dhcp.rst index ded22ebe5..5ea9f2ed7 100644 --- a/doc/source/user/dhcp.rst +++ b/doc/source/user/dhcp.rst @@ -60,10 +60,10 @@ conceivably the nodes can be segregated. What is required: - - DHCP server on the network segment - - Appropriate permissions to change DHCP settings - - Network access to the API and conductor. Keep in mind the iPXE image does - not support ICMP redirects. +- DHCP server on the network segment +- Appropriate permissions to change DHCP settings +- Network access to the API and conductor. Keep in mind the iPXE image does + not support ICMP redirects. Example DHCP server configurations ---------------------------------- diff --git a/doc/source/user/howto.rst b/doc/source/user/howto.rst index bd95587ac..924503e92 100644 --- a/doc/source/user/howto.rst +++ b/doc/source/user/howto.rst @@ -15,7 +15,9 @@ clouds.yaml During installation, Bifrost creates a ``clouds.yaml`` file with credentials necessary to access Ironic. A cloud called ``bifrost`` is always available. For -example:: +example: + +.. code-block:: bash export OS_CLOUD=bifrost baremetal node list @@ -29,15 +31,12 @@ example:: Environment variables --------------------- -The following two environment variables can be set: - -- ``OS_AUTH_TYPE`` - set to ``none`` to bypass authentication. -- ``OS_ENDPOINT`` - A URL to the ironic API, such as http://localhost:6385/ - For convenience, an environment file called ``openrc`` is created in the home directory of the current user that contains default values for these variables and can be sourced to allow the CLI to connect to a local Ironic installation. -For example:: +For example: + +.. code-block:: bash . ~/openrc bifrost baremetal node list @@ -74,14 +73,34 @@ source. JSON file format ---------------- -The JSON format closely resembles the data structure that ironic -utilizes internally. The ``name``, ``driver_info``, ``nics``, -``driver``, and ``properties`` fields are directly mapped through to -ironic. This means that the data contained within can vary from host -to host, such as drivers and their parameters thus allowing a mixed -hardware environment to be defined in a single file. +The JSON format resembles the data structure that ironic utilizes internally. -Example:: +* The ``name``, ``uuid``, ``driver``, and ``properties`` fields are directly + mapped through to ironic. Only the ``driver`` is required. + + .. note:: + Most properties are automatically populated during inspection, if it is + enabled. However, it is recommended to set the `root device + `_ + for nodes with multiple disks. + +* The ``driver_info`` field format matches one of the OpenStack Ansible + collection and for legacy reasons can use nested structures ``power``, + ``deploy``, ``management`` and ``console``. + + .. note:: + With newer versions of the collection you can just put all fields under + ``driver_info`` directly). + +* The ``nics`` field is a list of ports to create. The required field is + ``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`_. + +Example: + +.. code-block:: json { "testvm1": { @@ -101,12 +120,12 @@ Example:: "driver": "ipmi", "ansible_ssh_host": "192.168.122.2", "ipv4_address": "192.168.122.2", - "provisioning_ipv4_address": "10.0.0.9", "properties": { "cpu_arch": "x86_64", "ram": "3072", "disk_size": "10", - "cpus": "1" + "cpus": "1", + "root_device": {"wwn": "0x4000cca77fc4dba1"} }, "name": "testvm1" } @@ -115,7 +134,42 @@ Example:: The additional power of this format is easy configuration parameter injection, which could potentially allow a user to provision different operating system images onto different hardware chassis by defining the appropriate settings -in an ``instance_info`` variable. +in an ``instance_info`` variable, for example: + +.. code-block:: json + + { + "testvm1": { + "uuid": "00000000-0000-0000-0000-000000000001", + "driver_info": { + "power": { + "ipmi_address": "192.168.122.1", + "ipmi_username": "admin", + "ipmi_password": "pa$$w0rd" + } + }, + "nics": [ + { + "mac": "52:54:00:f9:32:f6" + } + ], + "driver": "ipmi", + "ansible_ssh_host": "192.168.122.2", + "ipv4_address": "192.168.122.2", + "properties": { + "cpu_arch": "x86_64", + "ram": "3072", + "disk_size": "10", + "cpus": "1", + "root_device": {"wwn": "0x4000cca77fc4dba1"} + }, + "name": "testvm1", + "instance_info": { + "image_source": "http://image.server/image.qcow2", + "image_checksum": "" + } + } + } Examples utilizing JSON and YAML formatting, along host specific variable injection can be found in the ``playbooks/inventory/`` folder. @@ -125,29 +179,22 @@ injection can be found in the ``playbooks/inventory/`` folder. How this works? --------------- -Starting with the Wallaby cycle, you can use ``bifrost-cli`` for enrolling:: +Starting with the Wallaby cycle, you can use ``bifrost-cli`` for enrolling: + +.. code-block:: bash ./bifrost-cli enroll /tmp/baremetal.json Utilizing the dynamic inventory module, enrollment is as simple as setting the ``BIFROST_INVENTORY_SOURCE`` environment variable to your inventory data -source, and then executing the enrollment playbook.:: +source, and then executing the enrollment playbook: + +.. code-block:: bash export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + cd playbooks ansible-playbook -vvvv -i inventory/bifrost_inventory.py enroll-dynamic.yaml -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 - -:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ enroll-dynamic.yaml - Note that enrollment is a one-time operation. The Ansible module *does not* synchronize data for existing nodes. You should use the ironic CLI to do this manually at the moment. @@ -155,6 +202,22 @@ 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 @@ -168,24 +231,15 @@ 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 newer dynamic inventory based deployment: + +.. code-block:: bash export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + cd playbooks ansible-playbook -vvvv -i inventory/bifrost_inventory.py deploy-dynamic.yaml -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 - -:: - - export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json - rm inventory/*.example - ansible-playbook -vvvv -i inventory/ deploy-dynamic.yaml - -Note:: +.. note:: Before running the above command, ensure that the value for `ssh_public_key_path` in ``./playbooks/inventory/group_vars/baremetal`` @@ -193,24 +247,48 @@ Note:: on the ansible-playbook command line by setting the variable. Example: "-e ssh_public_key_path=~/.ssh/id_rsa.pub" -If the hosts need to be re-deployed, the dynamic redeploy playbook may be used:: +The image, downloaded or generated during installation, is used by default. +Please see `JSON file format`_ for information on how to override the image per +node. + +If the hosts need to be re-deployed, the dynamic redeploy playbook may be used: + +.. code-block:: bash export BIFROST_INVENTORY_SOURCE=/tmp/baremetal.json + cd playbooks ansible-playbook -vvvv -i inventory/bifrost_inventory.py redeploy-dynamic.yaml 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 ================================================= By default, Bifrost deploys a configuration drive which includes the user SSH public key, hostname, and the network configuration in the form of -network_data.json that can be read/parsed by the -`glean `_ utility. This allows for +network_data.json that can be read/parsed by +`glean `_ or `cloud-init +`_. This allows for the deployment of Ubuntu, CentOS, or Fedora "tenants" on baremetal. -By default, Bifrost utilizes a utility called simple-init which leverages +By default, Bifrost utilizes a utility called *simple-init* which leverages the previously noted glean utility to apply network configuration. This means that by default, root file systems may not be automatically expanded to consume the entire disk, which may, or may not be desirable depending