Clean up the "How to" documentation
Fix formatting, add missing field descriptions, add instance_info example. Change-Id: Ibc97430efed26b35f941e31c6280f3cf387efc17
This commit is contained in:
Dmitry Tantsur
parent
fbe7bb3e54
commit
40842895fc
@ -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
|
||||
----------------------------------
|
||||
|
||||
@ -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
|
||||
<https://docs.openstack.org/ironic/latest/install/advanced.html#specifying-the-disk-for-deployment-root-device-hints>`_
|
||||
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": "<md5 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 <https://opendev.org/opendev/glean>`_ utility. This allows for
|
||||
network_data.json that can be read/parsed by
|
||||
`glean <https://opendev.org/opendev/glean>`_ or `cloud-init
|
||||
<https://cloudinit.readthedocs.io/en/latest/>`_. 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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user