diff --git a/doc/source/contributor/local-dev-guide.rst b/doc/source/contributor/local-dev-guide.rst index 615da4c464..c7d40d8d0c 100644 --- a/doc/source/contributor/local-dev-guide.rst +++ b/doc/source/contributor/local-dev-guide.rst @@ -6,12 +6,51 @@ 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 -example, this is useful for rapidly prototyping and debugging interactions over -the RPC channel, testing database migrations, and so forth. +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. -Here we describe two ways to install and configure the dependencies, either run -directly on your local machine or encapsulated in a virtual machine or -container. +This guide assumes you have already installed all required Ironic prerequisites, +as documented in the prerequisites section of :ref:`unit`. + +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 +----- + +#. If you haven't already downloaded the source code, do that first:: + + cd ~ + git clone https://opendev.org/openstack/ironic + cd ironic + +#. Run the ironic all-in-one process:: + + tox -elocal-ironic-dev + +#. In another window, utilize the client inside the tox venv:: + + . .tox/local-ironic-dev/bin/activate + export OS_AUTH_TYPE=none + export OS_ENDPOINT=http://127.0.0.1:6385 + baremetal driver list + +#. Press CTRL+C in the window running ``tox -elocal-ironic-dev`` when you + are done. + +Manually +________ + +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. Step 1: Create a Python virtualenv ---------------------------------- @@ -24,24 +63,17 @@ Step 1: Create a Python virtualenv #. Create the Python virtualenv:: - tox -evenv --notest --develop -r + tox -elocal-ironic-dev --notest --develop -r #. Activate the virtual environment:: - . .tox/venv/bin/activate + . .tox/local-ironic-dev/bin/activate -#. Install the `openstack` client command utility:: - - pip install python-openstackclient - - -#. Install the `baremetal` client:: - - pip install python-ironicclient - - .. note:: You can install python-ironicclient from source by cloning the git - repository and running `pip install .` while in the root of the - cloned repository. + .. 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. #. Export some ENV vars so the client will connect to the local services that you'll start in the next section:: @@ -49,15 +81,12 @@ Step 1: Create a Python virtualenv export OS_AUTH_TYPE=none export OS_ENDPOINT=http://localhost:6385/ -Next, install and configure system dependencies. - 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 -a MySQL server on it all the time). If you want to use SQLite, skip it and do -not set the ``connection`` option. +a MySQL server on it all the time). #. Install mysql-server: @@ -78,41 +107,17 @@ not set the ``connection`` option. mysql -u root -pMYSQL_ROOT_PWD -e "create schema ironic" - .. note:: if you choose not to install mysql-server, ironic will default to - using a local sqlite database. The database will then be stored in - ``ironic/ironic.sqlite``. - - -#. Create a configuration file within the ironic source directory:: - - # generate a sample config - tox -egenconfig +#. Use the localdev config as a template, and modify it:: # copy sample config and modify it as necessary - cp etc/ironic/ironic.conf.sample etc/ironic/ironic.conf.local + cp tools/ironic.conf.localdev etc/ironic/ironic.conf.local - # disable auth since we are not running keystone here - sed -i "s/#auth_strategy = keystone/auth_strategy = noauth/" etc/ironic/ironic.conf.local + # 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 - # use the 'fake-hardware' test hardware type - sed -i "s/#enabled_hardware_types = .*/enabled_hardware_types = fake-hardware/" etc/ironic/ironic.conf.local - - # use the 'fake' deploy and boot interfaces - sed -i "s/#enabled_deploy_interfaces = .*/enabled_deploy_interfaces = fake/" etc/ironic/ironic.conf.local - sed -i "s/#enabled_boot_interfaces = .*/enabled_boot_interfaces = fake/" etc/ironic/ironic.conf.local - - # enable both fake and ipmitool management and power interfaces - sed -i "s/#enabled_management_interfaces = .*/enabled_management_interfaces = fake,ipmitool/" etc/ironic/ironic.conf.local - sed -i "s/#enabled_power_interfaces = .*/enabled_power_interfaces = fake,ipmitool/" etc/ironic/ironic.conf.local - - # change the periodic sync_power_state_interval to a week, to avoid getting NodeLocked exceptions - sed -i "s/#sync_power_state_interval = 60/sync_power_state_interval = 604800/" etc/ironic/ironic.conf.local - - # if you opted to install mysql-server, switch the DB connection from sqlite to mysql - sed -i "s/#connection = .*/connection = mysql\+pymysql:\/\/root:MYSQL_ROOT_PWD@localhost\/ironic/" etc/ironic/ironic.conf.local - - # use JSON RPC to avoid installing rabbitmq locally - sed -i "s/#rpc_transport = oslo/rpc_transport = json-rpc/" etc/ironic/ironic.conf.local + # disable single-process mode and enable json-rpc + sed -i "s/rpc_transport = none/rpc_transport = json-rpc/" etc/ironic/ironic.conf.local Step 3: Start the Services -------------------------- @@ -130,13 +135,13 @@ 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 - . .tox/venv/bin/activate + . .tox/local-ironic-dev/bin/activate ironic-api -d --config-file etc/ironic/ironic.conf.local #. Start the Conductor service in debug mode and watch its output:: cd ~/ironic - . .tox/venv/bin/activate + . .tox/local-ironic-dev/bin/activate ironic-conductor -d --config-file etc/ironic/ironic.conf.local Step 4: Interact with the running services @@ -148,7 +153,7 @@ 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 -local instance of ironic and disable the authentication:: +local instance of ironic:: export OS_AUTH_TYPE=none export OS_ENDPOINT=http://127.0.0.1:6385 @@ -156,7 +161,7 @@ local instance of ironic and disable the authentication:: Then list the available commands and resources:: # get a list of available commands - openstack help baremetal + baremetal help # get the list of drivers currently supported by the available conductor(s) baremetal driver list @@ -166,27 +171,14 @@ Then list the available commands and resources:: Here is an example walkthrough of creating a node:: - MAC="aa:bb:cc:dd:ee:ff" # replace with the MAC of a data port on your node - IPMI_ADDR="1.2.3.4" # replace with a real IP of the node BMC - IPMI_USER="admin" # replace with the BMC's user name - IPMI_PASS="pass" # replace with the BMC's password - # 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" - NODE=$(baremetal node create \ - --driver fake-hardware \ - --management-interface ipmitool \ - --power-interface ipmitool \ - --driver-info ipmi_address=$IPMI_ADDR \ - --driver-info ipmi_username=$IPMI_USER \ - -f value -c uuid) + NODE=$(baremetal node create --driver fake-hardware -f value -c uuid) - # driver info may also be added or updated later on - baremetal node set $NODE --driver-info ipmi_password=$IPMI_PASS - - # add a network port - baremetal port create $MAC --node $NODE + # 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 # view the information for the node baremetal node show $NODE @@ -217,12 +209,12 @@ help with that, but are not an exhaustive troubleshooting guide:: # reinstall ironic modules cd ~/ironic - . .tox/venv/bin/activate + . .tox/local-ironic-dev/bin/activate pip uninstall ironic pip install -e . # install and upgrade ironic and all python dependencies cd ~/ironic - . .tox/venv/bin/activate + . .tox/local-ironic-dev/bin/activate pip install -U -e . diff --git a/tools/ironic.conf.localdev b/tools/ironic.conf.localdev new file mode 100644 index 0000000000..894cb54c3c --- /dev/null +++ b/tools/ironic.conf.localdev @@ -0,0 +1,14 @@ +[DEFAULT] +# Disable all but fake hardware types and interfaces +enabled_hardware_types = fake-hardware +enabled_boot_interfaces = fake +enabled_deploy_interfaces = fake +enabled_management_interfaces = fake +enabled_vendor_interfaces = fake +default_network_interface = noop + +# Enable single-process Ironic +rpc_transport = none + +# No authentication for dev +auth_strategy = noauth diff --git a/tox.ini b/tox.ini index fe4c635061..028ed0ae44 100644 --- a/tox.ini +++ b/tox.ini @@ -177,3 +177,29 @@ deps = codespell # to correct spelling issues in our code it's aware of. commands = codespell {posargs} + +[testenv:local-ironic-dev] +constrain_package_deps = true +usedevelop = True +setenv = VIRTUAL_ENV={envdir} + PYTHONDONTWRITEBYTECODE=1 + LANGUAGE=en_US + LC_ALL=en_US.UTF-8 + PYTHONUNBUFFERED=1 + SQLALCHEMY_WARN_20=true +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/requirements.txt + -r{toxinidir}/driver-requirements.txt + python-ironicclient + python-openstackclient +allowlist_externals = bash +commands = + bash -c 'ironic-dbsync --config-file={toxinidir}/tools/ironic.conf.localdev create_schema || echo "===== DB already exists; continuing ====="' + ironic --config-file={toxinidir}/tools/ironic.conf.localdev {posargs} +passenv = http_proxy + HTTP_PROXY + https_proxy + HTTPS_PROXY + no_proxy + NO_PROXY