Documentation update
This patch contains several changes to the documentation which were brought about by, initially, removing the webapi/v1 page and replacing it with a link to the /api-ref/ page. As I did that, I saw that our front page (index.html) needed to be updated as well, and decided that the front page needed to actually be completely rerwitten -- while preserving all the links. Some of the TOC links from the front page were malformed because subpages included more than one H1 heading, so I had to make small changes in the api-audit-support and code-contribution-guide and dev-quickstart pages, in order for the front page to render properly. As I corrected the headings on dev-quickstart, I realized the page was not comprehensively organized, and so decided to reorganize the sections and make it easier to navigate. Here is a bullet-point summary of this change: * Major changes to content and organization of index page * Moved the version history from webapi/v1 to dev/webapi-version-history * Added API conceptual guide at dev/webapi * Replaced webapi/v1 with a link to dev/webapi, in case anyone bookmarked it * Removed doc references to webapi/v1 * Merged the pages dev/contributing and dev/code-contribution-guide * Removed duplicate H1 headers in deploy/api-audit-support * Reorganized and renamed section headers in dev/dev-quickstart, and made some substantive corrections and changes as well * Updated wording at the top of the index and deploy/user-guide pages. Change-Id: Ib418e1d4fdfab4f0e15560270f39922e33df3f12
This commit is contained in:
Devananda van der Veen
Jay Faulkner
parent
77875d6aca
commit
d0e49e1b41
@ -26,4 +26,4 @@ on Launchpad:
|
||||
http://launchpad.net/ironic
|
||||
|
||||
For information on how to contribute to ironic, see
|
||||
http://docs.openstack.org/infra/manual/developers.html
|
||||
http://docs.openstack.org/developer/ironic/dev/code-contribution-guide.html
|
||||
|
||||
@ -1,5 +1,6 @@
|
||||
.. _api-audit-support:
|
||||
|
||||
=================
|
||||
API Audit Logging
|
||||
=================
|
||||
|
||||
|
||||
@ -4,30 +4,25 @@
|
||||
Introduction to Ironic
|
||||
======================
|
||||
|
||||
Ironic is an OpenStack project which provisions physical hardware as opposed to
|
||||
virtual machines. Ironic provides several reference drivers which leverage
|
||||
common technologies like PXE and IPMI, to cover a wide range of hardware.
|
||||
Ironic's pluggable driver architecture also allows vendor-specific drivers to
|
||||
be added for improved performance or functionality not provided by reference
|
||||
drivers.
|
||||
Ironic is an OpenStack project which provisions bare metal (as opposed to
|
||||
virtual) machines. It may be used independently or as part of an OpenStack
|
||||
Cloud, and integrates with the OpenStack Identity (keystone), Compute (nova),
|
||||
Network (neutron), and Image (glance) services.
|
||||
|
||||
If one thinks of traditional hypervisor functionality (e.g., creating a
|
||||
VM, enumerating virtual devices, managing the power state, loading an OS onto
|
||||
the VM, and so on), then Ironic may be thought of as a hypervisor API gluing
|
||||
together multiple drivers, each of which implement some portion of that
|
||||
functionality with respect to physical hardware.
|
||||
When the Bare Metal service is appropriately configured with the Compute and
|
||||
Network services, it is possible to provision both virtual and physical
|
||||
machines through the Compute service's API. However, the set of instance
|
||||
actions is limited, arising from the different characteristics of physical
|
||||
servers and switch hardware. For example, live migration can not be performed
|
||||
on a bare metal instance.
|
||||
|
||||
OpenStack's Ironic project makes physical servers as easy to provision as
|
||||
virtual machines in cloud, which in turn will open up new avenues for
|
||||
enterprises and service providers.
|
||||
The community maintains reference drivers that leverage open-source
|
||||
technologies (eg. PXE and IPMI) to cover a wide range of hardware. Ironic's
|
||||
pluggable driver architecture also allows hardware vendors to write and
|
||||
contribute drivers that may improve performance or add functionality not
|
||||
provided by the community drivers.
|
||||
|
||||
Ironic's driver replaces the Nova "bare metal" driver (in Grizzly - Juno
|
||||
releases). Ironic is available for use and is supported by the Ironic
|
||||
developers starting with the Juno release. It is officially integrated with
|
||||
OpenStack in the Kilo release.
|
||||
|
||||
See https://wiki.openstack.org/wiki/Ironic for links to the project's current
|
||||
development status.
|
||||
.. TODO: the remainder of this file needs to be cleaned up still
|
||||
|
||||
Why Provision Bare Metal
|
||||
========================
|
||||
|
||||
@ -8,6 +8,60 @@ This document provides some necessary points for developers to consider when
|
||||
writing and reviewing Ironic code. The checklist will help developers get
|
||||
things right.
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
If you're completely new to OpenStack and want to contribute to the ironic
|
||||
project, please start by familiarizing yourself with the `Infra Team's Developer
|
||||
Guide <http://docs.openstack.org/infra/manual/developers.html>`_. This will help
|
||||
you get your accounts set up in Launchpad and Gerrit, familiarize you with the
|
||||
workflow for the OpenStack continuous integration and testing systems, and help
|
||||
you with your first commit.
|
||||
|
||||
LaunchPad Project
|
||||
-----------------
|
||||
|
||||
Most of the tools used for OpenStack require a launchpad.net ID for
|
||||
authentication.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net
|
||||
* https://launchpad.net/ironic
|
||||
|
||||
Related Projects
|
||||
----------------
|
||||
|
||||
There are several projects that are tightly integrated with ironic and which are
|
||||
developed by the same community.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net/bifrost
|
||||
* https://launchpad.net/ironic-inspector
|
||||
* https://launchpad.net/ironic-lib
|
||||
* https://launchpad.net/ironic-python-agent
|
||||
* https://launchpad.net/python-ironicclient
|
||||
* https://launchpad.net/python-ironic-inspector-client
|
||||
|
||||
Project Hosting Details
|
||||
-----------------------
|
||||
|
||||
Bug tracker
|
||||
http://launchpad.net/ironic
|
||||
|
||||
Mailing list (prefix Subject line with ``[ironic]``)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
|
||||
|
||||
Wiki
|
||||
http://wiki.openstack.org/Ironic
|
||||
|
||||
Code Hosting
|
||||
https://git.openstack.org/cgit/openstack/ironic
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+project:openstack/ironic,n,z
|
||||
|
||||
Adding New Features
|
||||
===================
|
||||
|
||||
@ -208,4 +262,3 @@ For approved and completed specs:
|
||||
|
||||
Please see the `Ironic specs process wiki page <https://wiki.openstack.org/
|
||||
wiki/Ironic/Specs_Process>`_ for further reference.
|
||||
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
.. _contributing:
|
||||
|
||||
======================
|
||||
Contributing to Ironic
|
||||
======================
|
||||
|
||||
If you're interested in contributing to the Ironic project,
|
||||
the following will help get you started.
|
||||
|
||||
Contributor License Agreement
|
||||
-----------------------------
|
||||
|
||||
.. index::
|
||||
single: license; agreement
|
||||
|
||||
In order to contribute to the Ironic project, you need to have
|
||||
signed OpenStack's contributor's agreement.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* http://docs.openstack.org/infra/manual/developers.html
|
||||
* http://wiki.openstack.org/CLA
|
||||
|
||||
LaunchPad Project
|
||||
-----------------
|
||||
|
||||
Most of the tools used for OpenStack depend on a launchpad.net ID for
|
||||
authentication.
|
||||
|
||||
.. seealso::
|
||||
|
||||
* https://launchpad.net
|
||||
* https://launchpad.net/ironic
|
||||
|
||||
Related Projects
|
||||
----------------
|
||||
|
||||
* https://launchpad.net/ironic-inspector
|
||||
* https://launchpad.net/python-ironicclient
|
||||
* https://launchpad.net/python-ironic-inspector-client
|
||||
* https://launchpad.net/bifrost
|
||||
|
||||
Project Hosting Details
|
||||
-----------------------
|
||||
|
||||
Bug tracker
|
||||
http://launchpad.net/ironic
|
||||
|
||||
Mailing list (prefix subjects with ``[ironic]`` for faster responses)
|
||||
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
|
||||
|
||||
Wiki
|
||||
http://wiki.openstack.org/Ironic
|
||||
|
||||
Code Hosting
|
||||
https://git.openstack.org/cgit/openstack/ironic
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+project:openstack/ironic,n,z
|
||||
|
||||
@ -18,12 +18,23 @@ to submitting a patch.
|
||||
|
||||
.. note::
|
||||
This document is compatible with Python (3.5), Ubuntu (16.04) and Fedora (23).
|
||||
When referring to different versions of Python and OS distributions, this
|
||||
is explicitly stated.
|
||||
|
||||
.. seealso::
|
||||
|
||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
||||
|
||||
Install prerequisites for python 2.7:
|
||||
Prepare Development System
|
||||
==========================
|
||||
|
||||
System Prerequisites
|
||||
--------------------
|
||||
|
||||
The following packages cover the prerequisites for a local development
|
||||
environment on most current distributions. Instructions for getting set up with
|
||||
non-default versions of Python and on older distributions are included below as
|
||||
well.
|
||||
|
||||
- Ubuntu/Debian::
|
||||
|
||||
@ -53,8 +64,11 @@ Install prerequisites for python 2.7:
|
||||
`<https://software.opensuse.org/download.html?project=graphics&package=graphviz-plugins>`_.
|
||||
|
||||
|
||||
If you need Python 3.4, follow the instructions above to install prerequisites for 2.7 and
|
||||
additionally install the following packages:
|
||||
(Optional) Installing Py34 requirements
|
||||
---------------------------------------
|
||||
|
||||
If you need Python 3.4, follow the instructions above to install prerequisites
|
||||
and *additionally* install the following packages:
|
||||
|
||||
- On Ubuntu 14.x/Debian::
|
||||
|
||||
@ -81,8 +95,12 @@ additionally install the following packages:
|
||||
|
||||
sudo dnf install python3-devel
|
||||
|
||||
If you need Python 3.5, follow the instructions for installing prerequisites for Python 2.7 and
|
||||
run the following commands.
|
||||
(Optional) Installing Py35 requirements
|
||||
---------------------------------------
|
||||
|
||||
If you need Python 3.5 support on an older distro that does not already have
|
||||
it, follow the instructions for installing prerequisites above and
|
||||
*additionally* run the following commands.
|
||||
|
||||
- On Ubuntu 14.04::
|
||||
|
||||
@ -103,45 +121,43 @@ run the following commands.
|
||||
sudo dnf copr enable -y mstuchli/Python3.5
|
||||
dnf install -y python35-python3
|
||||
|
||||
Python Prerequisites
|
||||
--------------------
|
||||
|
||||
If your distro has at least tox 1.8, use similar command to install
|
||||
``python-tox`` package. Otherwise install this on all distros::
|
||||
|
||||
sudo pip install -U tox
|
||||
|
||||
|
||||
You may need to explicitly upgrade virtualenv if you've installed the one
|
||||
from your OS distribution and it is too old (tox will complain). You can
|
||||
upgrade it individually, if you need to::
|
||||
|
||||
sudo pip install -U virtualenv
|
||||
|
||||
Ironic source code should be pulled directly from git::
|
||||
|
||||
Running Unit Tests Locally
|
||||
==========================
|
||||
|
||||
If you haven't already, Ironic source code should be pulled directly from git::
|
||||
|
||||
# from your home or source directory
|
||||
cd ~
|
||||
git clone https://git.openstack.org/openstack/ironic
|
||||
cd ironic
|
||||
|
||||
Set up a local environment for development and testing should be done with tox,
|
||||
for example::
|
||||
|
||||
# create a virtualenv for development
|
||||
tox -evenv --notest
|
||||
Running Unit and Style Tests
|
||||
----------------------------
|
||||
|
||||
All unit tests should be run using tox. To run Ironic's entire test suite::
|
||||
|
||||
# run all tests (unit under both py27 and py34, and pep8)
|
||||
# to run the py27, py34, py35 unit tests, and the style tests
|
||||
tox
|
||||
|
||||
To run the unit tests under py34 and also run the pep8 tests::
|
||||
To run a specific test or tests, use the "-e" option followed by the tox target
|
||||
name. For example::
|
||||
|
||||
# run all tests (unit under py34 and pep8)
|
||||
tox -epy34 -epep8
|
||||
|
||||
To run the unit tests under py27 and also run the pep8 tests::
|
||||
|
||||
# run all tests (unit under py27 and pep8)
|
||||
# run the unit tests under py27 and also run the pep8 tests
|
||||
tox -epy27 -epep8
|
||||
|
||||
.. note::
|
||||
@ -160,10 +176,6 @@ To run a specific unit test, this passes the -r option and desired test
|
||||
# run a specific test for Python 2.7
|
||||
tox -epy27 -- -r test_conductor
|
||||
|
||||
To run only the pep8/flake8 syntax and style checks::
|
||||
|
||||
tox -epep8
|
||||
|
||||
Debugging unit tests
|
||||
--------------------
|
||||
|
||||
@ -184,25 +196,89 @@ Then run ``tox`` with the debug environment as one of the following::
|
||||
For more information see the `oslotest documentation
|
||||
<http://docs.openstack.org/developer/oslotest/features.html#debugging-with-oslo-debug-helper>`_.
|
||||
|
||||
===============================
|
||||
Additional Test Targets
|
||||
-----------------------
|
||||
|
||||
There are several additional tox targets not included in the default list, such
|
||||
as the target which builds the documentation site. See the ``tox.ini`` file
|
||||
for a complete listing of tox targets. These can be run directly by specifying
|
||||
the target name::
|
||||
|
||||
# generate the documentation pages locally
|
||||
tox -edocs
|
||||
|
||||
# generate the sample configuration file
|
||||
tox -egenconfig
|
||||
|
||||
|
||||
Exercising the Services Locally
|
||||
===============================
|
||||
|
||||
If you would like to exercise the Ironic services in isolation within a local
|
||||
virtual 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.
|
||||
In addition to running automated tests, sometimes it can be helpful to actually
|
||||
run the services locally, without needing a server in a remote datacenter.
|
||||
|
||||
Step 1: System Dependencies
|
||||
---------------------------
|
||||
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.
|
||||
|
||||
There are two ways you may use to install the required system dependencies:
|
||||
Manually, or by using the included Vagrant file.
|
||||
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.
|
||||
|
||||
Option 1: Manual Install
|
||||
########################
|
||||
Step 1: Create a Python virtualenv
|
||||
----------------------------------
|
||||
|
||||
#. Install a few system prerequisites::
|
||||
#. If you haven't already downloaded the source code, do that first::
|
||||
|
||||
cd ~
|
||||
git clone https://git.openstack.org/openstack/ironic
|
||||
cd ironic
|
||||
|
||||
#. Create the Python virtualenv::
|
||||
|
||||
tox -evenv --notest --develop -r
|
||||
|
||||
#. Activate the virtual environment::
|
||||
|
||||
source .tox/venv/bin/activate
|
||||
|
||||
#. Export some ENV vars so the client will connect to the local services
|
||||
that you'll start in the next section::
|
||||
|
||||
export OS_AUTH_TOKEN=fake-token
|
||||
export IRONIC_URL=http://localhost:6385/
|
||||
|
||||
Next, install and configure system dependencies. Two different approaches are
|
||||
described below; you should only do one of these.
|
||||
|
||||
Step 2a: System Depdencies In A Virtual Machine
|
||||
-----------------------------------------------
|
||||
|
||||
This option requires `virtualbox <https://www.virtualbox.org>`_,
|
||||
`vagrant <https://www.vagrantup.com>`_, and
|
||||
`ansible <https://www.ansible.com>`_. You may install these using your
|
||||
favorite package manager, or by downloading from the provided links.
|
||||
|
||||
#. Let vagrant do the work::
|
||||
|
||||
vagrant up
|
||||
|
||||
This will create a VM available to your local system at `192.168.99.11`,
|
||||
will install all the necessary service dependencies,
|
||||
and configure some default users. It will also generate
|
||||
`./etc/ironic/ironic.conf.local` preconfigured for local dev work.
|
||||
We recommend you compare and familiarize yourself with the settings in
|
||||
`./etc/ironic/ironic.conf.sample` so you can adjust it to meet your own needs.
|
||||
|
||||
Step 2b: Install System Dependencies Locally
|
||||
--------------------------------------------
|
||||
|
||||
This option will install RabbitMQ and 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).
|
||||
|
||||
#. Install rabbitmq-server::
|
||||
|
||||
# install rabbit message broker
|
||||
# Ubuntu/Debian:
|
||||
@ -220,7 +296,7 @@ Option 1: Manual Install
|
||||
sudo zypper install rabbitmq-server
|
||||
sudo systemctl start rabbitmq-server.service
|
||||
|
||||
# optionally, install mysql-server
|
||||
#. Install mysql-server::
|
||||
|
||||
# Ubuntu/Debian:
|
||||
# sudo apt-get install mysql-server
|
||||
@ -237,17 +313,11 @@ Option 1: Manual Install
|
||||
# sudo zypper install mariadb
|
||||
# sudo systemctl start mysql.service
|
||||
|
||||
#. Clone the ``Ironic`` repository and install it within a virtualenv::
|
||||
# If using MySQL, you need to create the initial database
|
||||
mysql -u root -pMYSQL_ROOT_PWD -e "create schema ironic"
|
||||
|
||||
# activate the virtualenv
|
||||
cd ~
|
||||
git clone https://git.openstack.org/openstack/ironic
|
||||
cd ironic
|
||||
tox -evenv --notest
|
||||
source .tox/venv/bin/activate
|
||||
|
||||
# install ironic within the virtualenv
|
||||
python setup.py develop
|
||||
.. NOTE: if you choose not to install mysql-server, ironic will default to
|
||||
using a local sqlite database.
|
||||
|
||||
#. Create a configuration file within the ironic source directory::
|
||||
|
||||
@ -266,95 +336,41 @@ Option 1: Manual Install
|
||||
# turn off the periodic sync_power_state task, to avoid getting NodeLocked exceptions
|
||||
sed -i "s/#sync_power_state_interval = 60/sync_power_state_interval = -1/" etc/ironic/ironic.conf.local
|
||||
|
||||
#. Initialize the ironic database (optional)::
|
||||
|
||||
# ironic defaults to storing data in ./ironic/ironic.sqlite
|
||||
|
||||
# If using MySQL, you need to create the initial database
|
||||
mysql -u root -pMYSQL_ROOT_PWD -e "create schema ironic"
|
||||
|
||||
# and switch the DB connection from sqlite to something else, eg. mysql
|
||||
# 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
|
||||
|
||||
At this point, you can continue to Step 2.
|
||||
Step 3: Start the Services
|
||||
--------------------------
|
||||
|
||||
Option 2: Vagrant, VirtualBox, and Ansible
|
||||
##########################################
|
||||
From within the python virtualenv, run the following command to prepare the
|
||||
database before you start the ironic services::
|
||||
|
||||
This option requires `virtualbox <https://www.virtualbox.org>`_,
|
||||
`vagrant <https://www.vagrantup.com>`_, and
|
||||
`ansible <https://www.ansible.com>`_. You may install these using your
|
||||
favorite package manager, or by downloading from the provided links.
|
||||
|
||||
Next, run vagrant::
|
||||
|
||||
vagrant up
|
||||
|
||||
This will create a VM available to your local system at `192.168.99.11`,
|
||||
will install all the necessary service dependencies,
|
||||
and configure some default users. It will also generate
|
||||
`./etc/ironic/ironic.conf.local` preconfigured for local dev work.
|
||||
We recommend you compare and familiarize yourself with the settings in
|
||||
`./etc/ironic/ironic.conf.sample` so you can adjust it to meet your own needs.
|
||||
|
||||
Step 2: Start the API
|
||||
---------------------
|
||||
#. Activate the virtual environment created in the previous section to run
|
||||
the API::
|
||||
|
||||
# switch to the ironic source (Not necessary if you followed Option 1)
|
||||
cd ironic
|
||||
|
||||
# activate the virtualenv
|
||||
source .tox/venv/bin/activate
|
||||
|
||||
# install ironic within the virtualenv
|
||||
python setup.py develop
|
||||
|
||||
# This creates the database tables.
|
||||
# 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::
|
||||
|
||||
# start the API service
|
||||
cd ~/ironic
|
||||
source .tox/venv/bin/activate
|
||||
ironic-api -v -d --config-file etc/ironic/ironic.conf.local
|
||||
|
||||
#. Start the Conductor service in debug mode and watch its output::
|
||||
|
||||
Step 3: Install the Client
|
||||
--------------------------
|
||||
#. Clone the ``python-ironicclient`` repository and install it within a
|
||||
virtualenv::
|
||||
|
||||
# from your home or source directory
|
||||
cd ~
|
||||
git clone https://git.openstack.org/openstack/python-ironicclient
|
||||
cd python-ironicclient
|
||||
tox -evenv --notest
|
||||
cd ~/ironic
|
||||
source .tox/venv/bin/activate
|
||||
|
||||
#. Export some ENV vars so the client will connect to the local services
|
||||
that you'll start in the next section::
|
||||
|
||||
export OS_AUTH_TOKEN=fake-token
|
||||
export IRONIC_URL=http://localhost:6385/
|
||||
|
||||
|
||||
Step 4: Start the Conductor Service
|
||||
-----------------------------------
|
||||
Open one more window (or screen session), again activate the venv, and then
|
||||
start the conductor service and watch its output::
|
||||
|
||||
# activate the virtualenv
|
||||
cd ironic
|
||||
source .tox/venv/bin/activate
|
||||
|
||||
# start the conductor service
|
||||
ironic-conductor -v -d --config-file etc/ironic/ironic.conf.local
|
||||
|
||||
You should now be able to interact with Ironic via the python client (installed
|
||||
in Step 3) 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.
|
||||
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, list the available commands and resources::
|
||||
|
||||
@ -394,11 +410,35 @@ Here is an example walkthrough of creating a node::
|
||||
# its power state from ironic!
|
||||
ironic node-set-power-state $NODE on
|
||||
|
||||
If you make some code changes and want to test their effects, install
|
||||
again with "python setup.py develop", stop the services with Ctrl-C,
|
||||
and restart them.
|
||||
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
|
||||
source .tox/venv/bin/activate
|
||||
pip uninstall ironic
|
||||
pip install -e .
|
||||
|
||||
# install and upgrade ironic and all python dependencies
|
||||
cd ~/ironic
|
||||
source .tox/venv/bin/activate
|
||||
pip install -U -e .
|
||||
|
||||
|
||||
==============================
|
||||
Deploying Ironic with DevStack
|
||||
==============================
|
||||
|
||||
@ -649,7 +689,6 @@ The server should now be accessible via SSH::
|
||||
ssh cirros@10.1.0.4
|
||||
$
|
||||
|
||||
=====================
|
||||
Running Tempest tests
|
||||
=====================
|
||||
|
||||
@ -703,7 +742,6 @@ For more information about the supported parameters see::
|
||||
Always be careful when running debuggers in time sensitive code,
|
||||
they may cause timeout errors that weren't there before.
|
||||
|
||||
================================
|
||||
Building developer documentation
|
||||
================================
|
||||
|
||||
@ -741,4 +779,3 @@ commands to build the documentation set:
|
||||
#Now use your browser to open the top-level index.html located at:
|
||||
|
||||
http://your_ip:8000
|
||||
|
||||
|
||||
146
doc/source/dev/webapi-version-history.rst
Normal file
146
doc/source/dev/webapi-version-history.rst
Normal file
@ -0,0 +1,146 @@
|
||||
========================
|
||||
REST API Version History
|
||||
========================
|
||||
|
||||
**1.22**
|
||||
|
||||
Added endpoints for deployment ramdisks.
|
||||
|
||||
**1.21**
|
||||
|
||||
Add node ``resource_class`` field.
|
||||
|
||||
**1.20**
|
||||
|
||||
Add node ``network_interface`` field.
|
||||
|
||||
**1.19**
|
||||
|
||||
Add ``local_link_connection`` and ``pxe_enabled`` fields to the port object.
|
||||
|
||||
**1.18**
|
||||
|
||||
Add ``internal_info`` readonly field to the port object, that will be used
|
||||
by ironic to store internal port-related information.
|
||||
|
||||
**1.17**
|
||||
|
||||
Addition of provision_state verb ``adopt`` which allows an operator
|
||||
to move a node from ``manageable`` state to ``active`` state without
|
||||
performing a deployment operation on the node. This is intended for
|
||||
nodes that have already been deployed by external means.
|
||||
|
||||
**1.16**
|
||||
|
||||
Add ability to filter nodes by driver.
|
||||
|
||||
**1.15**
|
||||
|
||||
Add ability to do manual cleaning when a node is in the manageable
|
||||
provision state via PUT v1/nodes/<identifier>/states/provision,
|
||||
target:clean, clean_steps:[...].
|
||||
|
||||
**1.14**
|
||||
|
||||
Make the following endpoints discoverable via Ironic API:
|
||||
|
||||
* '/v1/nodes/<UUID or logical name>/states'
|
||||
* '/v1/drivers/<driver name>/properties'
|
||||
|
||||
**1.13**
|
||||
|
||||
Add a new verb ``abort`` to the API used to abort nodes in
|
||||
``CLEANWAIT`` state.
|
||||
|
||||
**1.12**
|
||||
|
||||
This API version adds the following abilities:
|
||||
|
||||
* Get/set ``node.target_raid_config`` and to get
|
||||
``node.raid_config``.
|
||||
* Retrieve the logical disk properties for the driver.
|
||||
|
||||
**1.11** (breaking change)
|
||||
|
||||
Newly registered nodes begin in the ``enroll`` provision state by default,
|
||||
instead of ``available``. To get them to the ``available`` state,
|
||||
the ``manage`` action must first be run to verify basic hardware control.
|
||||
On success the node moves to ``manageable`` provision state. Then the
|
||||
``provide`` action must be run. Automated cleaning of the node is done and
|
||||
the node is made ``available``.
|
||||
|
||||
**1.10**
|
||||
|
||||
Logical node names support all RFC 3986 unreserved characters.
|
||||
Previously only valid fully qualified domain names could be used.
|
||||
|
||||
**1.9**
|
||||
|
||||
Add ability to filter nodes by provision state.
|
||||
|
||||
**1.8**
|
||||
|
||||
Add ability to return a subset of resource fields.
|
||||
|
||||
**1.7**
|
||||
|
||||
Add node ``clean_step`` field.
|
||||
|
||||
**1.6**
|
||||
|
||||
Add :ref:`inspection` process: introduce ``inspecting`` and ``inspectfail``
|
||||
provision states, and ``inspect`` action that can be used when a node is in
|
||||
``manageable`` provision state.
|
||||
|
||||
**1.5**
|
||||
|
||||
Add logical node names that can be used to address a node in addition to
|
||||
the node UUID. Name is expected to be a valid `fully qualified domain
|
||||
name`_ in this version of API.
|
||||
|
||||
**1.4**
|
||||
|
||||
Add ``manageable`` state and ``manage`` transition, which can be used to
|
||||
move a node to ``manageable`` state from ``available``.
|
||||
The node cannot be deployed in ``manageable`` state.
|
||||
This change is mostly a preparation for future inspection work
|
||||
and introduction of ``enroll`` provision state.
|
||||
|
||||
**1.3**
|
||||
|
||||
Add node ``driver_internal_info`` field.
|
||||
|
||||
**1.2** (breaking change)
|
||||
|
||||
Renamed NOSTATE (``None`` in Python, ``null`` in JSON) node state to
|
||||
``available``. This is needed to reduce confusion around ``None`` state,
|
||||
especially when future additions to the state machine land.
|
||||
|
||||
**1.1**
|
||||
|
||||
This was the initial version when API versioning was introduced.
|
||||
Includes the following changes from Kilo release cycle:
|
||||
|
||||
* Add node ``maintenance_reason`` field and an API endpoint to
|
||||
set/unset the node maintenance mode.
|
||||
|
||||
* Add sync and async support for vendor passthru methods.
|
||||
|
||||
* Vendor passthru endpoints support different HTTP methods, not only
|
||||
``POST``.
|
||||
|
||||
* Make vendor methods discoverable via the Ironic API.
|
||||
|
||||
* Add logic to store the config drive passed by Nova.
|
||||
|
||||
This has been the minimum supported version since versioning was
|
||||
introduced.
|
||||
|
||||
**1.0**
|
||||
|
||||
This version denotes Juno API and was never explicitly supported, as API
|
||||
versioning was not implemented in Juno, and **1.1** became the minimum
|
||||
supported version in Kilo.
|
||||
|
||||
.. _fully qualified domain name: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
|
||||
|
||||
76
doc/source/dev/webapi.rst
Normal file
76
doc/source/dev/webapi.rst
Normal file
@ -0,0 +1,76 @@
|
||||
=========================
|
||||
REST API Conceptual Guide
|
||||
=========================
|
||||
|
||||
Versioning
|
||||
==========
|
||||
|
||||
The ironic REST API supports two types of versioning:
|
||||
|
||||
- "major versions", which have dedicated urls.
|
||||
- "microversions", which can be requested through the use of the
|
||||
``X-OpenStack-Ironic-API-Version`` header.
|
||||
|
||||
There is only one major version supported currently, "v1". As such, most URLs
|
||||
in this documentation are written with the "/v1/" prefix.
|
||||
|
||||
Starting with the Kilo release, ironic supports microversions. In this context,
|
||||
a version is defined as a string of 2 integers separated by a dot: **X.Y**.
|
||||
Here ``X`` is a major version, always equal to ``1``, and ``Y`` is
|
||||
a minor version. Server minor version is increased every time the API behavior
|
||||
is changed (note `Exceptions from Versioning`_).
|
||||
|
||||
.. note::
|
||||
`Nova versioning documentation`_ has a nice guide for developers on when to
|
||||
bump an API version.
|
||||
|
||||
The server indicates its minimum and maximum supported API versions in the
|
||||
``X-OpenStack-Ironic-API-Minimum-Version`` and
|
||||
``X-OpenStack-Ironic-API-Maximum-Version`` headers respectively, returned
|
||||
with every response. Client may request a specific API version by providing
|
||||
``X-OpenStack-Ironic-API-Version`` header with request.
|
||||
|
||||
The requested microversion determines both the allowable requests and the
|
||||
response format for all requests. A resource may be represented differently
|
||||
based on the requested microversion.
|
||||
|
||||
If no version is requested by the client, the minimum supported version will be
|
||||
assumed. In this way, a client is only exposed to those API features that are
|
||||
supported in the requested (explicitly or implicitly) API version (again note
|
||||
`Exceptions from Versioning`_, they are not covered by this rule).
|
||||
|
||||
We recommend clients that require a stable API to always request a specific
|
||||
version of API that they have been tested against.
|
||||
|
||||
.. note::
|
||||
A special value ``latest`` can be requested instead a numerical
|
||||
microversion, which always requests the newest supported API version from
|
||||
the server.
|
||||
|
||||
.. _Nova versioning documentation: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion
|
||||
|
||||
REST API Versions History
|
||||
-------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
API Version History <dev/webapi-version-history>
|
||||
|
||||
|
||||
Exceptions from Versioning
|
||||
--------------------------
|
||||
|
||||
The following API-visible things are not covered by the API versioning:
|
||||
|
||||
* Current node state is always exposed as it is, even if not supported by the
|
||||
requested API version, with exception of ``available`` state, which is
|
||||
returned in version 1.1 as ``None`` (in Python) or ``null`` (in JSON).
|
||||
|
||||
* Data within free-form JSON attributes: ``properties``, ``driver_info``,
|
||||
``instance_info``, ``driver_internal_info`` fields on a node object;
|
||||
``extra`` fields on all objects.
|
||||
|
||||
* Addition of new drivers.
|
||||
|
||||
* All vendor passthru methods.
|
||||
@ -6,74 +6,199 @@ Introduction
|
||||
============
|
||||
|
||||
Ironic is an OpenStack project which provisions bare metal (as opposed to
|
||||
virtual) machines by leveraging common technologies such as PXE boot and IPMI
|
||||
to cover a wide range of hardware, while supporting pluggable drivers to allow
|
||||
vendor-specific functionality to be added.
|
||||
virtual) machines. It may be used independently or as part of an OpenStack
|
||||
Cloud, and integrates with the OpenStack Identity (keystone), Compute (nova),
|
||||
Network (neutron), Image (glance), and Object (swift) services.
|
||||
|
||||
If one thinks of traditional hypervisor functionality (eg, creating a VM,
|
||||
enumerating virtual devices, managing the power state, loading an OS onto the
|
||||
VM, and so on), then Ironic may be thought of as a *hypervisor API* gluing
|
||||
together multiple drivers, each of which implement some portion of that
|
||||
functionality with respect to physical hardware.
|
||||
The Bare Metal service manages hardware through both common (eg. PXE and IPMI)
|
||||
and vendor-specific remote management protocols. It provides the cloud operator
|
||||
with a unified interface to a heterogeneous fleet of servers while also
|
||||
providing the Compute service with an interface that allows physical servers to
|
||||
be managed as though they were virtual machines.
|
||||
|
||||
The documentation provided here is continually kept up-to-date based
|
||||
on the latest code, and may not represent the state of the project at any
|
||||
specific prior release.
|
||||
`An introduction to the ironic's conceptual architecture <deploy/user-guide>`_
|
||||
is available for those new to the project.
|
||||
|
||||
For information on any current or prior version of Ironic, see `the release
|
||||
notes`_.
|
||||
Site Notes
|
||||
----------
|
||||
|
||||
.. _the release notes: http://docs.openstack.org/releasenotes/ironic/
|
||||
This site is primarily intended to provide documentation for developers
|
||||
interested in contributing to or working with ironic. It *also* contains
|
||||
references and guides for administrators which are not yet hosted elsewhere on
|
||||
the OpenStack documentation sites.
|
||||
|
||||
Administrator's Guide
|
||||
=====================
|
||||
This documentation is continually updated and may not represent the state of
|
||||
the project at any specific prior release. To access documentation for a
|
||||
previous release of ironic, append the OpenStack release name to the URL, for
|
||||
example:
|
||||
|
||||
http://docs.openstack.org/developer/ironic/mitaka/
|
||||
|
||||
|
||||
Bare Metal API References
|
||||
=========================
|
||||
|
||||
Ironic's REST API has changed since its first release, and continues to evolve
|
||||
to meet the changing needs of the community. Here we provide a conceptual
|
||||
guide as well as more detailed reference documentation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
API Concept Guide <dev/webapi>
|
||||
API Reference (latest) <http://developer.openstack.org/api-ref/baremetal/>
|
||||
API Version History <dev/webapi-version-history>
|
||||
|
||||
|
||||
Developer's Guide
|
||||
=================
|
||||
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
If you are new to ironic, this section contains information that should help
|
||||
you get started as a developer working on the project or contributing to the
|
||||
project.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Developer Contribution Guide <dev/code-contribution-guide>
|
||||
Setting Up Your Development Environment <dev/dev-quickstart>
|
||||
Frequently Asked Questions <dev/faq>
|
||||
|
||||
The following pages describe the architecture of the Bare Metal service
|
||||
and may be helpful to anyone working on or with the service, but are written
|
||||
primarily for developers.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Ironic System Architecture <dev/architecture>
|
||||
Provisioning State Machine <dev/states>
|
||||
|
||||
|
||||
Writing Drivers
|
||||
---------------
|
||||
|
||||
Ironic's community includes many hardware vendors who contribute drivers that
|
||||
enable more advanced functionality when Ironic is used in conjunction with that
|
||||
hardware. To do this, the Ironic developer community is committed to
|
||||
standardizing on a `Python Driver API <api/ironic.drivers.base.html>`_ that
|
||||
meets the common needs of all hardware vendors, and evolving this API without
|
||||
breaking backwards compatibility. However, it is sometimes necessary for driver
|
||||
authors to implement functionality - and expose it through the REST API - that
|
||||
can not be done through any existing API.
|
||||
|
||||
To facilitate that, we also provide the means for API calls to be "passed
|
||||
through" ironic and directly to the driver. Some guidelines on how to implement
|
||||
this are provided below. Driver authors are strongly encouraged to talk with
|
||||
the developer community about any implementation using this functionality.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Driver Overview <dev/drivers>
|
||||
Driver Base Class Definition <api/ironic.drivers.base.html>
|
||||
Writing "vendor_passthru" methods <dev/vendor-passthru>
|
||||
|
||||
Testing Network Integration
|
||||
---------------------------
|
||||
|
||||
In order to test the integration between the Bare Metal and Networking
|
||||
services, support has been added to `devstack <http://launchpad.net/devstack>`_
|
||||
to mimic an external physical switch. Here we include a recommended
|
||||
configuration for devstack to bring up this environment.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Configuring Devstack for multitenant network testing <dev/ironic-multitenant-networking>
|
||||
|
||||
|
||||
Administrator's Guide
|
||||
=====================
|
||||
|
||||
Installation & Operations
|
||||
-------------------------
|
||||
|
||||
If you are a system administrator running Ironic, this section contains
|
||||
information that should help you understand how to deploy, operate, and upgrade
|
||||
the services.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
deploy/user-guide
|
||||
Installation Guide <deploy/install-guide>
|
||||
Upgrade Guide <deploy/upgrade-guide>
|
||||
Configuration Reference (Mitaka) <http://docs.openstack.org/mitaka/config-reference/bare-metal.html>
|
||||
drivers/ipa
|
||||
deploy/drivers
|
||||
deploy/cleaning
|
||||
deploy/multitenancy
|
||||
deploy/raid
|
||||
deploy/inspection
|
||||
deploy/console
|
||||
deploy/security
|
||||
deploy/adoption
|
||||
deploy/api-audit-support
|
||||
deploy/troubleshooting
|
||||
Release Notes <http://docs.openstack.org/releasenotes/ironic/>
|
||||
Troubleshooting FAQ <deploy/troubleshooting>
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
There are many aspects of the Bare Metal service which are environment
|
||||
specific. The following pages will be helpful in configuring specific aspects
|
||||
of ironic that may or may not be suitable to every situation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Guide to Node Cleaning <deploy/cleaning>
|
||||
Configuring Node Inspection <deploy/inspection>
|
||||
Configuring RAID during deployment <deploy/raid>
|
||||
Security considerations for your Bare Metal installation <deploy/security>
|
||||
Adopting Nodes in an ACTIVE state <deploy/adoption>
|
||||
Auditing API Traffic <deploy/api-audit-support>
|
||||
Configuring for Multi-tenant Networking <deploy/multitenancy>
|
||||
|
||||
.. TODO::
|
||||
Add page on metrics.
|
||||
|
||||
A reference guide listing all available configuration options is published for
|
||||
every major release. Additionally, a `sample configuration file`_ is included
|
||||
within the project and kept continually up to date.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Configuration Reference (Mitaka) <http://docs.openstack.org/mitaka/config-reference/bare-metal.html>
|
||||
|
||||
.. _sample configuration file: https://git.openstack.org/cgit/openstack/ironic/tree/etc/ironic/ironic.conf.sample
|
||||
|
||||
Dashboard Integration
|
||||
---------------------
|
||||
|
||||
A plugin for the OpenStack Dashboard (horizon) service is under development.
|
||||
Documentation for that can be found within the ironic-ui project.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Dashboard (horizon) plugin <http://docs.openstack.org/developer/ironic-ui/>
|
||||
|
||||
Commands and API References
|
||||
===========================
|
||||
|
||||
Driver References
|
||||
=================
|
||||
|
||||
Every driver author is expected to document the use and configuration of their
|
||||
driver. These pages are linked below.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Driver Documentation pages <deploy/drivers>
|
||||
Further Considerations for the Agent Drivers <drivers/ipa>
|
||||
|
||||
Command References
|
||||
==================
|
||||
|
||||
Here are references for commands not elsewhere documented.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
cmds/ironic-dbsync
|
||||
webapi/v1
|
||||
dev/drivers
|
||||
|
||||
Developer's Guide
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
dev/architecture
|
||||
dev/states
|
||||
dev/contributing
|
||||
dev/code-contribution-guide
|
||||
dev/dev-quickstart
|
||||
dev/vendor-passthru
|
||||
dev/ironic-multitenant-networking
|
||||
|
||||
dev/faq
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
@ -1,277 +1,5 @@
|
||||
====================
|
||||
RESTful Web API (v1)
|
||||
====================
|
||||
========
|
||||
REST API
|
||||
========
|
||||
|
||||
API Versioning
|
||||
==============
|
||||
|
||||
Starting with the Kilo release ironic supports versioning of API. Version is
|
||||
defined as a string of 2 integers separated by a dot: **X.Y**. Here ``X`` is a
|
||||
major version, always equal to ``1`` at the moment of writing, ``Y`` is
|
||||
a minor version. Server minor version is increased every time the API behavior
|
||||
is changed (note `Exceptions from Versioning`_). `Nova versioning
|
||||
documentation`_ has a nice guide on when to bump an API version.
|
||||
|
||||
Server indicates its minimum and maximum supported API versions in the
|
||||
``X-OpenStack-Ironic-API-Minimum-Version`` and
|
||||
``X-OpenStack-Ironic-API-Maximum-Version`` headers respectively, returned
|
||||
with every response. Client may request a specific API version by providing
|
||||
``X-OpenStack-Ironic-API-Version`` header with request.
|
||||
|
||||
If no version is requested by the client, minimum supported version - **1.1**,
|
||||
is assumed. The client is only exposed to those API features that are supported
|
||||
in the requested (explicitly or implicitly) API version (again note `Exceptions
|
||||
from Versioning`_, they are not covered by this rule).
|
||||
|
||||
We recommend clients requiring stable API to always request a specific version
|
||||
of API. However, a special value ``latest`` can be requested instead, which
|
||||
always requests the newest supported API version.
|
||||
|
||||
.. _Nova versioning documentation: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion
|
||||
|
||||
API Versions History
|
||||
--------------------
|
||||
|
||||
**1.22**
|
||||
|
||||
Added endpoints for deployment ramdisks.
|
||||
|
||||
**1.21**
|
||||
|
||||
Add node ``resource_class`` field.
|
||||
|
||||
**1.20**
|
||||
|
||||
Add node ``network_interface`` field.
|
||||
|
||||
**1.19**
|
||||
|
||||
Add ``local_link_connection`` and ``pxe_enabled`` fields to the port object.
|
||||
|
||||
**1.18**
|
||||
|
||||
Add ``internal_info`` readonly field to the port object, that will be used
|
||||
by ironic to store internal port-related information.
|
||||
|
||||
**1.17**
|
||||
|
||||
Addition of provision_state verb ``adopt`` which allows an operator
|
||||
to move a node from ``manageable`` state to ``active`` state without
|
||||
performing a deployment operation on the node. This is intended for
|
||||
nodes that have already been deployed by external means.
|
||||
|
||||
**1.16**
|
||||
|
||||
Add ability to filter nodes by driver.
|
||||
|
||||
**1.15**
|
||||
|
||||
Add ability to do manual cleaning when a node is in the manageable
|
||||
provision state via PUT v1/nodes/<identifier>/states/provision,
|
||||
target:clean, clean_steps:[...].
|
||||
|
||||
**1.14**
|
||||
|
||||
Make the following endpoints discoverable via Ironic API:
|
||||
|
||||
* '/v1/nodes/<UUID or logical name>/states'
|
||||
* '/v1/drivers/<driver name>/properties'
|
||||
|
||||
**1.13**
|
||||
|
||||
Add a new verb ``abort`` to the API used to abort nodes in
|
||||
``CLEANWAIT`` state.
|
||||
|
||||
**1.12**
|
||||
|
||||
This API version adds the following abilities:
|
||||
|
||||
* Get/set ``node.target_raid_config`` and to get
|
||||
``node.raid_config``.
|
||||
* Retrieve the logical disk properties for the driver.
|
||||
|
||||
**1.11** (breaking change)
|
||||
|
||||
Newly registered nodes begin in the ``enroll`` provision state by default,
|
||||
instead of ``available``. To get them to the ``available`` state,
|
||||
the ``manage`` action must first be run to verify basic hardware control.
|
||||
On success the node moves to ``manageable`` provision state. Then the
|
||||
``provide`` action must be run. Automated cleaning of the node is done and
|
||||
the node is made ``available``.
|
||||
|
||||
**1.10**
|
||||
|
||||
Logical node names support all RFC 3986 unreserved characters.
|
||||
Previously only valid fully qualified domain names could be used.
|
||||
|
||||
**1.9**
|
||||
|
||||
Add ability to filter nodes by provision state.
|
||||
|
||||
**1.8**
|
||||
|
||||
Add ability to return a subset of resource fields.
|
||||
|
||||
**1.7**
|
||||
|
||||
Add node ``clean_step`` field.
|
||||
|
||||
**1.6**
|
||||
|
||||
Add :ref:`inspection` process: introduce ``inspecting`` and ``inspectfail``
|
||||
provision states, and ``inspect`` action that can be used when a node is in
|
||||
``manageable`` provision state.
|
||||
|
||||
**1.5**
|
||||
|
||||
Add logical node names that can be used to address a node in addition to
|
||||
the node UUID. Name is expected to be a valid `fully qualified domain
|
||||
name`_ in this version of API.
|
||||
|
||||
**1.4**
|
||||
|
||||
Add ``manageable`` state and ``manage`` transition, which can be used to
|
||||
move a node to ``manageable`` state from ``available``.
|
||||
The node cannot be deployed in ``manageable`` state.
|
||||
This change is mostly a preparation for future inspection work
|
||||
and introduction of ``enroll`` provision state.
|
||||
|
||||
**1.3**
|
||||
|
||||
Add node ``driver_internal_info`` field.
|
||||
|
||||
**1.2** (breaking change)
|
||||
|
||||
Renamed NOSTATE (``None`` in Python, ``null`` in JSON) node state to
|
||||
``available``. This is needed to reduce confusion around ``None`` state,
|
||||
especially when future additions to the state machine land.
|
||||
|
||||
**1.1**
|
||||
|
||||
This was the initial version when API versioning was introduced.
|
||||
Includes the following changes from Kilo release cycle:
|
||||
|
||||
* Add node ``maintenance_reason`` field and an API endpoint to
|
||||
set/unset the node maintenance mode.
|
||||
|
||||
* Add sync and async support for vendor passthru methods.
|
||||
|
||||
* Vendor passthru endpoints support different HTTP methods, not only
|
||||
``POST``.
|
||||
|
||||
* Make vendor methods discoverable via the Ironic API.
|
||||
|
||||
* Add logic to store the config drive passed by Nova.
|
||||
|
||||
This has been the minimum supported version since versioning was
|
||||
introduced.
|
||||
|
||||
**1.0**
|
||||
|
||||
This version denotes Juno API and was never explicitly supported, as API
|
||||
versioning was not implemented in Juno, and **1.1** became the minimum
|
||||
supported version in Kilo.
|
||||
|
||||
.. _fully qualified domain name: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
|
||||
|
||||
Exceptions from Versioning
|
||||
--------------------------
|
||||
|
||||
The following API-visible things are not covered by the API versioning:
|
||||
|
||||
* Current node state is always exposed as it is, even if not supported by the
|
||||
requested API version, with exception of ``available`` state, which is
|
||||
returned in version 1.1 as ``None`` (in Python) or ``null`` (in JSON).
|
||||
|
||||
* Data within free-form JSON attributes: ``properties``, ``driver_info``,
|
||||
``instance_info``, ``driver_internal_info`` fields on a node object;
|
||||
``extra`` fields on all objects.
|
||||
|
||||
* Addition of new drivers.
|
||||
|
||||
* All vendor passthru methods.
|
||||
|
||||
Chassis
|
||||
=======
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.chassis:ChassisController
|
||||
:webprefix: /v1/chassis
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.chassis.ChassisCollection
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.chassis.Chassis
|
||||
:members:
|
||||
|
||||
|
||||
Drivers
|
||||
=======
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.driver:DriversController
|
||||
:webprefix: /v1/drivers
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.driver:DriverRaidController
|
||||
:webprefix: /v1/drivers/(driver_name)/raid
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.driver:DriverPassthruController
|
||||
:webprefix: /v1/drivers/(driver_name)/vendor_passthru
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.driver.DriverList
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.driver.Driver
|
||||
:members:
|
||||
|
||||
|
||||
Links
|
||||
=====
|
||||
|
||||
.. autotype:: ironic.api.controllers.link.Link
|
||||
:members:
|
||||
|
||||
|
||||
Nodes
|
||||
=====
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:NodesController
|
||||
:webprefix: /v1/nodes
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:NodeMaintenanceController
|
||||
:webprefix: /v1/nodes/(node_ident)/maintenance
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:BootDeviceController
|
||||
:webprefix: /v1/nodes/(node_ident)/management/boot_device
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:NodeStatesController
|
||||
:webprefix: /v1/nodes/(node_ident)/states
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:NodeConsoleController
|
||||
:webprefix: /v1/nodes/(node_ident)/states/console
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.node:NodeVendorPassthruController
|
||||
:webprefix: /v1/nodes/(node_ident)/vendor_passthru
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.node.ConsoleInfo
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.node.Node
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.node.NodeCollection
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.node.NodeStates
|
||||
:members:
|
||||
|
||||
|
||||
Ports
|
||||
=====
|
||||
|
||||
.. rest-controller:: ironic.api.controllers.v1.port:PortsController
|
||||
:webprefix: /v1/ports
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.port.PortCollection
|
||||
:members:
|
||||
|
||||
.. autotype:: ironic.api.controllers.v1.port.Port
|
||||
:members:
|
||||
The API documentation reference `has been moved here <../dev/webapi.html>`_.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user