Synchronise master with upstream

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.
 

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 <NODE>
+      baremetal node manage <NODE>
+      baremetal node provide <NODE>
+
+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 <https://docs.openstack.org/bifrost/latest/contributor/testenv.html>`_.
+
+For more on using the Baremetal CLI,
+refer to the `Bifrost user HOWTO <https://docs.openstack.org/bifrost/latest/user/howto.html#baremetal-cli>`_.