diff --git a/doc/source/contributor/testenv.rst b/doc/source/contributor/testenv.rst index 94741ffd..74c01b42 100644 --- a/doc/source/contributor/testenv.rst +++ b/doc/source/contributor/testenv.rst @@ -5,6 +5,43 @@ Testing Environment Quick start with bifrost-cli ============================ +This section provides a structured process to set up and deploy nodes using +the Bifrost test environment. It is ideal for users who want a quick +and guided approach without diving into detailed configurations upfront. + +Clone Bifrost repository: + +.. code-block:: bash + + git clone https://opendev.org/openstack/bifrost + + cd bifrost + +.. note:: + This example uses the development branch ``master``. If you prefer to use + a stable release, switch to the corresponding stable branch. For example: + +.. code-block:: bash + + git checkout stable/2025.1 + +Set up SSH key pairs: + +Bifrost requires that the user who executes bifrost has an SSH key in their +user home, or that the user defines a variable to tell bifrost +where to identify this file. + +.. code-block:: bash + + ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa + +.. note:: + The above example uses an RSA key, but other key types such as ``ed25519`` + are also supported. Choose the key type that + best suits your security and compatibility needs. + +Set up and configure a test environment: + If you want to try Bifrost on virtual machines instead of real hardware, you need to prepare a testing environment. The easiest way is via ``bifrost-cli``, available since the Victoria release series: @@ -13,6 +50,18 @@ available since the Victoria release series: ./bifrost-cli testenv +See the built-in documentation for more details: + +.. code-block:: bash + + ./bifrost-cli testenv --help + +To install Bifrost services inside the testenv: + +.. code-block:: bash + + ./bifrost-cli --testenv + Additionally, the following parameters can be useful: ``--develop`` @@ -36,22 +85,57 @@ Additionally, the following parameters can be useful: ``--uefi`` Makes the testing VMs boot with UEFI. -See the built-in documentation for more details: +Activate the testenv and utilize the baremetal CLI in no-auth +mode with clouds.yaml: + +.. code-block:: bash + + source /opt/stack/bifrost/bin/activate + + export OS_CLOUD=bifrost + +Verify that Ironic and its drivers are installed and operational: .. code-block:: bash - ./bifrost-cli testenv --help + baremetal node list + + baremetal driver list + +Enroll nodes using the pre-existing inventory: -The command generates two files with node inventory in the current directory: +The command `./bifrost-cli testenv` generates two files with node inventory +in the current directory: * ``baremetal-inventory.json`` can be used with the provided playbooks, see - :doc:`/user/howto` for details. + :doc:`/user/howto` for details. Use the command: + +.. code-block:: bash + + ./bifrost-cli enroll baremetal-inventory.json + * ``baremetal-nodes.json`` can be used with the Ironic enrollment command: - .. code-block:: shell +.. code-block:: bash + + export OS_CLOUD=bifrost + + baremetal create baremetal-nodes.json + +Deploy the Enrolled Nodes: + +.. code-block:: bash + + ./bifrost-cli deploy baremetal-inventory.json + +Verify Deployment: + +The following command should show the node in an `active` provision state +after a successful deployment. + +.. code-block:: bash - export OS_CLOUD=bifrost - baremetal create baremetal-nodes.json + baremetal node list Reproduce CI testing locally ============================ @@ -66,7 +150,7 @@ testing and saves out a baremetal.json file which is used by ``playbooks/test-bifrost.yaml`` to execute the remaining roles. Two additional roles are invoked by this playbook which enables Ansible to connect to the new nodes by adding them to the inventory, and then -logging into the remote machine via the user's ssh host key. Once +logging into the remote machine via the user\'s ssh host key. Once that has successfully occurred, additional roles will unprovision the host(s) and delete them from ironic. diff --git a/doc/source/user/troubleshooting.rst b/doc/source/user/troubleshooting.rst index 5a25b358..f8306b23 100644 --- a/doc/source/user/troubleshooting.rst +++ b/doc/source/user/troubleshooting.rst @@ -165,3 +165,43 @@ DIB-based or any other IPA image, you will need to take the following steps: then they will not be replaced. Alternatively, the files can just be directly replaced on disk. The default where the kernel and ramdisk are located is in ``/httboot/``. + +*********************************************************** +Node Enrollment and Provisioning in a Testing Environment +*********************************************************** + +Here are a few steps to troubleshoot node enrollment and provisioning in +testing environment. + +Node Power and Provision State +================================ + +If the nodes enrollment fails, ensure the +power state of the nodes is 'On'. By default, the power state might be 'None'. +You can use the following commands to power on the nodes +and make them available: + +.. code-block:: bash + + baremetal node power on + baremetal node manage + baremetal node provide + +Once the nodes are powered on and provision state is ``available`` +re-run the enrollment process: + +.. code-block:: bash + + ./bifrost-cli enroll baremetal-inventory.json + +After successful enrollment, proceed with the deployment: + +.. code-block:: bash + + ./bifrost-cli deploy baremetal-inventory.json + +For documentation on the testing environment, +see the `Bifrost test environment guide `_. + +For more on using the Baremetal CLI, +refer to the `Bifrost user HOWTO `_.