2023-08-17 14:41:47 -07:00
|
|
|
Exercising Ironic Services Locally
|
|
|
|
==================================
|
|
|
|
|
|
|
|
It can sometimes be helpful to run Ironic services locally, without needing a
|
|
|
|
full devstack environment or a server in a remote datacenter.
|
|
|
|
|
|
|
|
If you would like to exercise the Ironic services in isolation within your local
|
|
|
|
environment, you can do this without starting any other OpenStack services. For
|
2024-06-28 11:49:29 -07:00
|
|
|
example, this is useful for rapidly prototyping and debugging interactions between
|
|
|
|
client and API, exploring the Ironic API for the first time, and basic testing.
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
This guide assumes you have already installed all required Ironic prerequisites,
|
|
|
|
as documented in the prerequisites section of :ref:`unit`.
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
Using tox
|
|
|
|
_________
|
|
|
|
Ironic provides a tox environment suitable for running a single-process Ironic
|
|
|
|
against sqlite. This utilizes the config in ``tools/ironic.conf.localdev`` to
|
|
|
|
setup a simple, all-in-one Ironic service useful for testing.
|
|
|
|
|
|
|
|
By default, this configuration uses sqlite with a backing file
|
|
|
|
``ironic/ironic.sqlite``. Deleting this file and restarting ironic will reset
|
|
|
|
you to a blank state.
|
|
|
|
|
|
|
|
Setup
|
|
|
|
-----
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
#. If you haven't already downloaded the source code, do that first::
|
|
|
|
|
|
|
|
cd ~
|
|
|
|
git clone https://opendev.org/openstack/ironic
|
|
|
|
cd ironic
|
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
#. Run the ironic all-in-one process::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
tox -elocal-ironic-dev
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
#. In another window, utilize the client inside the tox venv::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
. .tox/local-ironic-dev/bin/activate
|
|
|
|
export OS_AUTH_TYPE=none
|
|
|
|
export OS_ENDPOINT=http://127.0.0.1:6385
|
|
|
|
baremetal driver list
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
#. Press CTRL+C in the window running ``tox -elocal-ironic-dev`` when you
|
|
|
|
are done.
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
Manually
|
|
|
|
________
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
You may wish to do this manually in order to give you more granular control
|
|
|
|
over library versions and configurations, to enable usage of a database
|
|
|
|
server backend, or to spin up a non-all-in-one Ironic.
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
Step 1: Create a Python virtualenv
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
#. If you haven't already downloaded the source code, do that first::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
cd ~
|
|
|
|
git clone https://opendev.org/openstack/ironic
|
|
|
|
cd ironic
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
#. Create the Python virtualenv::
|
|
|
|
|
|
|
|
tox -elocal-ironic-dev --notest --develop -r
|
|
|
|
|
|
|
|
#. Activate the virtual environment::
|
|
|
|
|
|
|
|
. .tox/local-ironic-dev/bin/activate
|
|
|
|
|
|
|
|
.. note:: This installs ``python-openstackclient`` and
|
|
|
|
``python-ironicclient`` from pypi. You can instead install them
|
|
|
|
from source by cloning the git repository, activating the venv,
|
|
|
|
and running `pip install -e .` while in the root of the git
|
|
|
|
repo.
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
#. Export some ENV vars so the client will connect to the local services
|
|
|
|
that you'll start in the next section::
|
|
|
|
|
|
|
|
export OS_AUTH_TYPE=none
|
|
|
|
export OS_ENDPOINT=http://localhost:6385/
|
|
|
|
|
|
|
|
Step 2: Install System Dependencies Locally
|
|
|
|
--------------------------------------------
|
|
|
|
|
|
|
|
This step will install MySQL on your local system. This may not be desirable
|
|
|
|
in some situations (eg, you're developing from a laptop and do not want to run
|
2024-06-28 11:49:29 -07:00
|
|
|
a MySQL server on it all the time).
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
#. Install mysql-server:
|
|
|
|
|
|
|
|
Ubuntu/Debian::
|
|
|
|
|
|
|
|
sudo apt-get install mysql-server
|
|
|
|
|
|
|
|
RHEL/CentOS/Fedora::
|
|
|
|
|
|
|
|
sudo dnf install mariadb mariadb-server
|
|
|
|
sudo systemctl start mariadb.service
|
|
|
|
|
|
|
|
openSUSE/SLE::
|
|
|
|
sudo zypper install mariadb
|
|
|
|
sudo systemctl start mysql.service
|
|
|
|
|
|
|
|
If using MySQL, you need to create the initial database::
|
|
|
|
|
|
|
|
mysql -u root -pMYSQL_ROOT_PWD -e "create schema ironic"
|
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
#. Use the localdev config as a template, and modify it::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
# copy sample config and modify it as necessary
|
2024-06-28 11:49:29 -07:00
|
|
|
cp tools/ironic.conf.localdev etc/ironic/ironic.conf.local
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
# Add mysql database connection information to config
|
|
|
|
echo -e "\n[database]" >> etc/ironic/ironic.conf.local
|
|
|
|
echo -e "connection = mysql+pymysql://root:MYSQL_ROOT_PWD@localhost/ironic" >> etc/ironic/ironic.conf.local
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
# disable single-process mode and enable json-rpc
|
|
|
|
sed -i "s/rpc_transport = none/rpc_transport = json-rpc/" etc/ironic/ironic.conf.local
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
Step 3: Start the Services
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
From within the python virtualenv, run the following command to prepare the
|
|
|
|
database before you start the ironic services::
|
|
|
|
|
|
|
|
# initialize the database for ironic
|
|
|
|
ironic-dbsync --config-file etc/ironic/ironic.conf.local create_schema
|
|
|
|
|
|
|
|
Next, open two new terminals for this section, and run each of the examples
|
|
|
|
here in a separate terminal. In this way, the services will *not* be run as
|
|
|
|
daemons; you can observe their output and stop them with Ctrl-C at any time.
|
|
|
|
|
|
|
|
#. Start the API service in debug mode and watch its output::
|
|
|
|
|
|
|
|
cd ~/ironic
|
2024-06-28 11:49:29 -07:00
|
|
|
. .tox/local-ironic-dev/bin/activate
|
2023-08-17 14:41:47 -07:00
|
|
|
ironic-api -d --config-file etc/ironic/ironic.conf.local
|
|
|
|
|
|
|
|
#. Start the Conductor service in debug mode and watch its output::
|
|
|
|
|
|
|
|
cd ~/ironic
|
2024-06-28 11:49:29 -07:00
|
|
|
. .tox/local-ironic-dev/bin/activate
|
2023-08-17 14:41:47 -07:00
|
|
|
ironic-conductor -d --config-file etc/ironic/ironic.conf.local
|
|
|
|
|
|
|
|
Step 4: Interact with the running services
|
|
|
|
------------------------------------------
|
|
|
|
|
|
|
|
You should now be able to interact with ironic via the python client, which is
|
|
|
|
present in the python virtualenv, and observe both services' debug outputs in
|
|
|
|
the other two windows. This is a good way to test new features or play with the
|
|
|
|
functionality without necessarily starting DevStack.
|
|
|
|
|
|
|
|
To get started, export the following variables to point the client at the
|
2024-06-28 11:49:29 -07:00
|
|
|
local instance of ironic::
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
export OS_AUTH_TYPE=none
|
|
|
|
export OS_ENDPOINT=http://127.0.0.1:6385
|
|
|
|
|
|
|
|
Then list the available commands and resources::
|
|
|
|
|
|
|
|
# get a list of available commands
|
2024-06-28 11:49:29 -07:00
|
|
|
baremetal help
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
# get the list of drivers currently supported by the available conductor(s)
|
|
|
|
baremetal driver list
|
|
|
|
|
|
|
|
# get a list of nodes (should be empty at this point)
|
|
|
|
baremetal node list
|
|
|
|
|
|
|
|
Here is an example walkthrough of creating a node::
|
|
|
|
|
|
|
|
# enroll the node with the fake hardware type and IPMI-based power and
|
|
|
|
# management interfaces. Note that driver info may be added at node
|
|
|
|
# creation time with "--driver-info"
|
2024-06-28 11:49:29 -07:00
|
|
|
NODE=$(baremetal node create --driver fake-hardware -f value -c uuid)
|
2023-08-17 14:41:47 -07:00
|
|
|
|
2024-06-28 11:49:29 -07:00
|
|
|
# node info may also be added or updated later on
|
|
|
|
baremetal node set $NODE --driver-info fake_driver_info=fake
|
|
|
|
baremetal node set $NODE --extra extradata=isfun
|
2023-08-17 14:41:47 -07:00
|
|
|
|
|
|
|
# view the information for the node
|
|
|
|
baremetal node show $NODE
|
|
|
|
|
|
|
|
# request that the node's driver validate the supplied information
|
|
|
|
baremetal node validate $NODE
|
|
|
|
|
|
|
|
# you have now enrolled a node sufficiently to be able to control
|
|
|
|
# its power state from ironic!
|
|
|
|
baremetal node power on $NODE
|
|
|
|
|
|
|
|
If you make some code changes and want to test their effects, simply stop the
|
|
|
|
services with Ctrl-C and restart them.
|
|
|
|
|
|
|
|
Step 5: Fixing your test environment
|
|
|
|
------------------------------------
|
|
|
|
|
|
|
|
If you are testing changes that add or remove python entrypoints, or making
|
|
|
|
significant changes to ironic's python modules, or simply keep the virtualenv
|
|
|
|
around for a long time, your development environment may reach an inconsistent
|
|
|
|
state. It may help to delete cached ".pyc" files, update dependencies,
|
|
|
|
reinstall ironic, or even recreate the virtualenv. The following commands may
|
|
|
|
help with that, but are not an exhaustive troubleshooting guide::
|
|
|
|
|
|
|
|
# clear cached pyc files
|
|
|
|
cd ~/ironic/ironic
|
|
|
|
find ./ -name '*.pyc' | xargs rm
|
|
|
|
|
|
|
|
# reinstall ironic modules
|
|
|
|
cd ~/ironic
|
2024-06-28 11:49:29 -07:00
|
|
|
. .tox/local-ironic-dev/bin/activate
|
2023-08-17 14:41:47 -07:00
|
|
|
pip uninstall ironic
|
|
|
|
pip install -e .
|
|
|
|
|
|
|
|
# install and upgrade ironic and all python dependencies
|
|
|
|
cd ~/ironic
|
2024-06-28 11:49:29 -07:00
|
|
|
. .tox/local-ironic-dev/bin/activate
|
2023-08-17 14:41:47 -07:00
|
|
|
pip install -U -e .
|
|
|
|
|
2024-10-04 21:12:28 +00:00
|
|
|
Changing the Ironic Localdev Microversion
|
|
|
|
_________________________________________
|
|
|
|
|
|
|
|
Localdev supports testing against a specific microversion, which is useful
|
|
|
|
for testing backwards compatibility or evaluating external tools with
|
|
|
|
different versions of the API.
|
|
|
|
|
|
|
|
Steps to Change the Microversion
|
|
|
|
--------------------------------
|
|
|
|
|
|
|
|
To change the microversion, modify the ``ironic.conf.localdev`` file.
|
|
|
|
Instead of directly modifying the microversion, you should set the release
|
|
|
|
version corresponding to the microversion you intend to test. The mappings
|
|
|
|
between release versions and microversions (for the REST API) are maintained
|
|
|
|
in ``ironic/common/release_mappings.py``.
|
|
|
|
|
|
|
|
For example, to set the microversion to **16.2**, you would adjust
|
|
|
|
the ``pin_release_version`` parameter:
|
|
|
|
|
|
|
|
.. code-block:: ini
|
|
|
|
|
|
|
|
[DEFAULT]
|
|
|
|
# Set the release version corresponding to microversion 16.2
|
|
|
|
pin_release_version = 16.2
|
|
|
|
|
|
|
|
You can review the full configuration and release version mappings
|
|
|
|
in the `sample configuration documentation <https://docs.openstack.org/ironic/latest/configuration/sample-config.html>`_.
|
|
|
|
|
|
|
|
Resetting Localdev Setup
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
After changing the microversion, you need to reset the local development environment.
|
|
|
|
|
|
|
|
1. Delete the existing database file:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
rm -f ironic/ironic.sqlite
|
|
|
|
|
|
|
|
2. Reinstall Ironic in the virtual environment:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
. .tox/local-ironic-dev/bin/activate
|
|
|
|
pip uninstall ironic
|
|
|
|
pip install -e .
|
|
|
|
|
|
|
|
This change ensures that the APIs from the selected Ironic version
|
|
|
|
will be applied, based on the release-to-microversion mapping in
|
|
|
|
the Ironic codebase.
|