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:
parent
77875d6aca
commit
d0e49e1b41
|
@ -26,4 +26,4 @@ on Launchpad:
|
||||||
http://launchpad.net/ironic
|
http://launchpad.net/ironic
|
||||||
|
|
||||||
For information on how to contribute to ironic, see
|
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-support:
|
||||||
|
|
||||||
|
=================
|
||||||
API Audit Logging
|
API Audit Logging
|
||||||
=================
|
=================
|
||||||
|
|
||||||
|
|
|
@ -4,30 +4,25 @@
|
||||||
Introduction to Ironic
|
Introduction to Ironic
|
||||||
======================
|
======================
|
||||||
|
|
||||||
Ironic is an OpenStack project which provisions physical hardware as opposed to
|
Ironic is an OpenStack project which provisions bare metal (as opposed to
|
||||||
virtual machines. Ironic provides several reference drivers which leverage
|
virtual) machines. It may be used independently or as part of an OpenStack
|
||||||
common technologies like PXE and IPMI, to cover a wide range of hardware.
|
Cloud, and integrates with the OpenStack Identity (keystone), Compute (nova),
|
||||||
Ironic's pluggable driver architecture also allows vendor-specific drivers to
|
Network (neutron), and Image (glance) services.
|
||||||
be added for improved performance or functionality not provided by reference
|
|
||||||
drivers.
|
|
||||||
|
|
||||||
If one thinks of traditional hypervisor functionality (e.g., creating a
|
When the Bare Metal service is appropriately configured with the Compute and
|
||||||
VM, enumerating virtual devices, managing the power state, loading an OS onto
|
Network services, it is possible to provision both virtual and physical
|
||||||
the VM, and so on), then Ironic may be thought of as a hypervisor API gluing
|
machines through the Compute service's API. However, the set of instance
|
||||||
together multiple drivers, each of which implement some portion of that
|
actions is limited, arising from the different characteristics of physical
|
||||||
functionality with respect to physical hardware.
|
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
|
The community maintains reference drivers that leverage open-source
|
||||||
virtual machines in cloud, which in turn will open up new avenues for
|
technologies (eg. PXE and IPMI) to cover a wide range of hardware. Ironic's
|
||||||
enterprises and service providers.
|
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
|
.. TODO: the remainder of this file needs to be cleaned up still
|
||||||
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.
|
|
||||||
|
|
||||||
Why Provision Bare Metal
|
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
|
writing and reviewing Ironic code. The checklist will help developers get
|
||||||
things right.
|
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
|
Adding New Features
|
||||||
===================
|
===================
|
||||||
|
|
||||||
|
@ -208,4 +262,3 @@ For approved and completed specs:
|
||||||
|
|
||||||
Please see the `Ironic specs process wiki page <https://wiki.openstack.org/
|
Please see the `Ironic specs process wiki page <https://wiki.openstack.org/
|
||||||
wiki/Ironic/Specs_Process>`_ for further reference.
|
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::
|
.. note::
|
||||||
This document is compatible with Python (3.5), Ubuntu (16.04) and Fedora (23).
|
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::
|
.. seealso::
|
||||||
|
|
||||||
http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
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::
|
- Ubuntu/Debian::
|
||||||
|
|
||||||
|
@ -53,8 +64,11 @@ Install prerequisites for python 2.7:
|
||||||
`<https://software.opensuse.org/download.html?project=graphics&package=graphviz-plugins>`_.
|
`<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
|
(Optional) Installing Py34 requirements
|
||||||
additionally install the following packages:
|
---------------------------------------
|
||||||
|
|
||||||
|
If you need Python 3.4, follow the instructions above to install prerequisites
|
||||||
|
and *additionally* install the following packages:
|
||||||
|
|
||||||
- On Ubuntu 14.x/Debian::
|
- On Ubuntu 14.x/Debian::
|
||||||
|
|
||||||
|
@ -81,8 +95,12 @@ additionally install the following packages:
|
||||||
|
|
||||||
sudo dnf install python3-devel
|
sudo dnf install python3-devel
|
||||||
|
|
||||||
If you need Python 3.5, follow the instructions for installing prerequisites for Python 2.7 and
|
(Optional) Installing Py35 requirements
|
||||||
run the following commands.
|
---------------------------------------
|
||||||
|
|
||||||
|
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::
|
- On Ubuntu 14.04::
|
||||||
|
|
||||||
|
@ -103,45 +121,43 @@ run the following commands.
|
||||||
sudo dnf copr enable -y mstuchli/Python3.5
|
sudo dnf copr enable -y mstuchli/Python3.5
|
||||||
dnf install -y python35-python3
|
dnf install -y python35-python3
|
||||||
|
|
||||||
|
Python Prerequisites
|
||||||
|
--------------------
|
||||||
|
|
||||||
If your distro has at least tox 1.8, use similar command to install
|
If your distro has at least tox 1.8, use similar command to install
|
||||||
``python-tox`` package. Otherwise install this on all distros::
|
``python-tox`` package. Otherwise install this on all distros::
|
||||||
|
|
||||||
sudo pip install -U tox
|
sudo pip install -U tox
|
||||||
|
|
||||||
|
|
||||||
You may need to explicitly upgrade virtualenv if you've installed the one
|
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
|
from your OS distribution and it is too old (tox will complain). You can
|
||||||
upgrade it individually, if you need to::
|
upgrade it individually, if you need to::
|
||||||
|
|
||||||
sudo pip install -U virtualenv
|
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
|
# from your home or source directory
|
||||||
cd ~
|
cd ~
|
||||||
git clone https://git.openstack.org/openstack/ironic
|
git clone https://git.openstack.org/openstack/ironic
|
||||||
cd ironic
|
cd ironic
|
||||||
|
|
||||||
Set up a local environment for development and testing should be done with tox,
|
Running Unit and Style Tests
|
||||||
for example::
|
----------------------------
|
||||||
|
|
||||||
# create a virtualenv for development
|
|
||||||
tox -evenv --notest
|
|
||||||
|
|
||||||
All unit tests should be run using tox. To run Ironic's entire test suite::
|
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
|
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)
|
# run the unit tests under py27 and also run the pep8 tests
|
||||||
tox -epy34 -epep8
|
|
||||||
|
|
||||||
To run the unit tests under py27 and also run the pep8 tests::
|
|
||||||
|
|
||||||
# run all tests (unit under py27 and pep8)
|
|
||||||
tox -epy27 -epep8
|
tox -epy27 -epep8
|
||||||
|
|
||||||
.. note::
|
.. 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
|
# run a specific test for Python 2.7
|
||||||
tox -epy27 -- -r test_conductor
|
tox -epy27 -- -r test_conductor
|
||||||
|
|
||||||
To run only the pep8/flake8 syntax and style checks::
|
|
||||||
|
|
||||||
tox -epep8
|
|
||||||
|
|
||||||
Debugging unit tests
|
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
|
For more information see the `oslotest documentation
|
||||||
<http://docs.openstack.org/developer/oslotest/features.html#debugging-with-oslo-debug-helper>`_.
|
<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
|
Exercising the Services Locally
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
If you would like to exercise the Ironic services in isolation within a local
|
In addition to running automated tests, sometimes it can be helpful to actually
|
||||||
virtual environment, you can do this without starting any other OpenStack
|
run the services locally, without needing a server in a remote datacenter.
|
||||||
services. For example, this is useful for rapidly prototyping and debugging
|
|
||||||
interactions over the RPC channel, testing database migrations, and so forth.
|
|
||||||
|
|
||||||
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:
|
Here we describe two ways to install and configure the dependencies, either run
|
||||||
Manually, or by using the included Vagrant file.
|
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
|
# install rabbit message broker
|
||||||
# Ubuntu/Debian:
|
# Ubuntu/Debian:
|
||||||
|
@ -220,7 +296,7 @@ Option 1: Manual Install
|
||||||
sudo zypper install rabbitmq-server
|
sudo zypper install rabbitmq-server
|
||||||
sudo systemctl start rabbitmq-server.service
|
sudo systemctl start rabbitmq-server.service
|
||||||
|
|
||||||
# optionally, install mysql-server
|
#. Install mysql-server::
|
||||||
|
|
||||||
# Ubuntu/Debian:
|
# Ubuntu/Debian:
|
||||||
# sudo apt-get install mysql-server
|
# sudo apt-get install mysql-server
|
||||||
|
@ -237,17 +313,11 @@ Option 1: Manual Install
|
||||||
# sudo zypper install mariadb
|
# sudo zypper install mariadb
|
||||||
# sudo systemctl start mysql.service
|
# 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
|
.. NOTE: if you choose not to install mysql-server, ironic will default to
|
||||||
cd ~
|
using a local sqlite database.
|
||||||
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
|
|
||||||
|
|
||||||
#. Create a configuration file within the ironic source directory::
|
#. 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
|
# 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
|
sed -i "s/#sync_power_state_interval = 60/sync_power_state_interval = -1/" etc/ironic/ironic.conf.local
|
||||||
|
|
||||||
#. Initialize the ironic database (optional)::
|
# if you opted to install mysql-server, switch the DB connection from sqlite to mysql
|
||||||
|
|
||||||
# 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
|
|
||||||
sed -i "s/#connection = .*/connection = mysql\+pymysql:\/\/root:MYSQL_ROOT_PWD@localhost\/ironic/" etc/ironic/ironic.conf.local
|
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>`_,
|
# initialize the database for ironic
|
||||||
`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.
|
|
||||||
ironic-dbsync --config-file etc/ironic/ironic.conf.local create_schema
|
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 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
|
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
|
cd ~/ironic
|
||||||
--------------------------
|
|
||||||
#. 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
|
|
||||||
source .tox/venv/bin/activate
|
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
|
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
|
Step 4: Interact with the running services
|
||||||
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.
|
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::
|
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!
|
# its power state from ironic!
|
||||||
ironic node-set-power-state $NODE on
|
ironic node-set-power-state $NODE on
|
||||||
|
|
||||||
If you make some code changes and want to test their effects, install
|
If you make some code changes and want to test their effects, simply stop the
|
||||||
again with "python setup.py develop", stop the services with Ctrl-C,
|
services with Ctrl-C and restart them.
|
||||||
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
|
Deploying Ironic with DevStack
|
||||||
==============================
|
==============================
|
||||||
|
|
||||||
|
@ -649,7 +689,6 @@ The server should now be accessible via SSH::
|
||||||
ssh cirros@10.1.0.4
|
ssh cirros@10.1.0.4
|
||||||
$
|
$
|
||||||
|
|
||||||
=====================
|
|
||||||
Running Tempest tests
|
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,
|
Always be careful when running debuggers in time sensitive code,
|
||||||
they may cause timeout errors that weren't there before.
|
they may cause timeout errors that weren't there before.
|
||||||
|
|
||||||
================================
|
|
||||||
Building developer documentation
|
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:
|
#Now use your browser to open the top-level index.html located at:
|
||||||
|
|
||||||
http://your_ip:8000
|
http://your_ip:8000
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
Ironic is an OpenStack project which provisions bare metal (as opposed to
|
||||||
virtual) machines by leveraging common technologies such as PXE boot and IPMI
|
virtual) machines. It may be used independently or as part of an OpenStack
|
||||||
to cover a wide range of hardware, while supporting pluggable drivers to allow
|
Cloud, and integrates with the OpenStack Identity (keystone), Compute (nova),
|
||||||
vendor-specific functionality to be added.
|
Network (neutron), Image (glance), and Object (swift) services.
|
||||||
|
|
||||||
If one thinks of traditional hypervisor functionality (eg, creating a VM,
|
The Bare Metal service manages hardware through both common (eg. PXE and IPMI)
|
||||||
enumerating virtual devices, managing the power state, loading an OS onto the
|
and vendor-specific remote management protocols. It provides the cloud operator
|
||||||
VM, and so on), then Ironic may be thought of as a *hypervisor API* gluing
|
with a unified interface to a heterogeneous fleet of servers while also
|
||||||
together multiple drivers, each of which implement some portion of that
|
providing the Compute service with an interface that allows physical servers to
|
||||||
functionality with respect to physical hardware.
|
be managed as though they were virtual machines.
|
||||||
|
|
||||||
The documentation provided here is continually kept up-to-date based
|
`An introduction to the ironic's conceptual architecture <deploy/user-guide>`_
|
||||||
on the latest code, and may not represent the state of the project at any
|
is available for those new to the project.
|
||||||
specific prior release.
|
|
||||||
|
|
||||||
For information on any current or prior version of Ironic, see `the release
|
Site Notes
|
||||||
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
deploy/user-guide
|
|
||||||
Installation Guide <deploy/install-guide>
|
Installation Guide <deploy/install-guide>
|
||||||
Upgrade Guide <deploy/upgrade-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/>
|
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/>
|
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
cmds/ironic-dbsync
|
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
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
|
@ -1,277 +1,5 @@
|
||||||
====================
|
========
|
||||||
RESTful Web API (v1)
|
REST API
|
||||||
====================
|
========
|
||||||
|
|
||||||
API Versioning
|
The API documentation reference `has been moved here <../dev/webapi.html>`_.
|
||||||
==============
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
Loading…
Reference in New Issue