bifrost/doc/source/contributor/testenv.rst

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:

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:

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.

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:

./bifrost-cli testenv

See the built-in documentation for more details:

./bifrost-cli testenv --help

To install Bifrost services inside the testenv:

./bifrost-cli --testenv

Additionally, the following parameters can be useful:

--driver=[ipmi|redfish]

Choose the default driver for the generated nodes inventory.

Note

Both IPMI and Redfish support is configured anyway, so you can switch the drivers on fly if needed.

IPMI support uses VirtualBMC, Redfish - sushy-tools.

--uefi

Makes the testing VMs boot with UEFI.

Activate the testenv and utilize the baremetal CLI in no-auth mode with clouds.yaml:

Note

You still need to restart services to apply any changes, e.g.:

sudo systemctl restart ironic

source /opt/stack/bifrost/bin/activate

export OS_CLOUD=bifrost

Verify that Ironic and its drivers are installed and operational:

baremetal node list

baremetal driver list

Enroll nodes using the pre-existing inventory:

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 /user/howto for details. Use the command:

./bifrost-cli enroll baremetal-inventory.json

• baremetal-nodes.json can be used with the Ironic enrollment command:

export OS_CLOUD=bifrost

baremetal create baremetal-nodes.json

Deploy the Enrolled Nodes:

./bifrost-cli deploy baremetal-inventory.json

Verify Deployment:

The following command should show the node in an active provision state after a successful deployment.

baremetal node list

Reproduce CI testing locally

A simple scripts/test-bifrost.sh script can be utilized to install pre-requisite software packages, Ansible, and then execute the test-bifrost-create-vm.yaml and test-bifrost.yaml playbooks in order to provide a single step testing mechanism.

playbooks/test-bifrost-create-vm.yaml creates one or more VMs for 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 that has successfully occurred, additional roles will unprovision the host(s) and delete them from ironic.

Command:

scripts/test-bifrost.sh

Note:

• In order to cap requirements for installation, an upper_constraints_file setting is defined. This is consuming the UPPER_CONSTRAINTS_FILE or TOX_CONSTRAINTS_FILE env var by default, to properly integrate with CI systems, and will default to /opt/stack/requirements/upper-constraints.txt file if not present.

Manually test with Virtual Machines

Bifrost supports using virtual machines to emulate the hardware.

The VirtualBMC project is used as an IPMI proxy, so that the same ipmi hardware type can be used as for real hardware. Redfish emulator from sushy-tools is also installed.

1. Set testing to true in the playbooks/inventory/group_vars/target file.
2. You may need to adjust the value for ssh_public_key_path.
3. Execute the ansible-playbook -vvvv -i inventory/target test-bifrost-create-vm.yaml command to create a test virtual machine.
4. Run the install step, as documented in /install/index, however adding -e testing=true to the Ansible command line.
5. Set the environment variable of BIFROST_INVENTORY_SOURCE to the path to the JSON file, which by default has been written to /tmp/baremetal.json.
6. Run the enrollment step <enroll>, using the JSON file you created in the previous step.
7. Run the deployment step, as documented in deploy.