diff --git a/README.rst b/README.rst index 2b31fb0f83..7f2f32d7c1 100644 --- a/README.rst +++ b/README.rst @@ -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 diff --git a/doc/source/deploy/api-audit-support.rst b/doc/source/deploy/api-audit-support.rst index a83204c91c..e2a5c79baa 100644 --- a/doc/source/deploy/api-audit-support.rst +++ b/doc/source/deploy/api-audit-support.rst @@ -1,5 +1,6 @@ .. _api-audit-support: +================= API Audit Logging ================= diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst index c9d0c5828f..e76f1875b3 100644 --- a/doc/source/deploy/user-guide.rst +++ b/doc/source/deploy/user-guide.rst @@ -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 ======================== diff --git a/doc/source/dev/code-contribution-guide.rst b/doc/source/dev/code-contribution-guide.rst index e669b7ed3f..5ef5fcd815 100644 --- a/doc/source/dev/code-contribution-guide.rst +++ b/doc/source/dev/code-contribution-guide.rst @@ -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 `_. 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 `_ for further reference. - diff --git a/doc/source/dev/contributing.rst b/doc/source/dev/contributing.rst deleted file mode 100644 index 9e1426f5a1..0000000000 --- a/doc/source/dev/contributing.rst +++ /dev/null @@ -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 - diff --git a/doc/source/dev/dev-quickstart.rst b/doc/source/dev/dev-quickstart.rst index c960365c24..814e1df2c3 100644 --- a/doc/source/dev/dev-quickstart.rst +++ b/doc/source/dev/dev-quickstart.rst @@ -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: ``_. -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 `_. -=============================== +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 `_, +`vagrant `_, and +`ansible `_. 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 `_, -`vagrant `_, and -`ansible `_. 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 - diff --git a/doc/source/dev/webapi-version-history.rst b/doc/source/dev/webapi-version-history.rst new file mode 100644 index 0000000000..0fea287081 --- /dev/null +++ b/doc/source/dev/webapi-version-history.rst @@ -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//states/provision, + target:clean, clean_steps:[...]. + +**1.14** + + Make the following endpoints discoverable via Ironic API: + + * '/v1/nodes//states' + * '/v1/drivers//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 + diff --git a/doc/source/dev/webapi.rst b/doc/source/dev/webapi.rst new file mode 100644 index 0000000000..1441da9305 --- /dev/null +++ b/doc/source/dev/webapi.rst @@ -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 + + +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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 3733397934..002d6a3864 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 `_ +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 + API Reference (latest) + API 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 + Setting Up Your Development Environment + Frequently Asked Questions + +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 + Provisioning State Machine + + +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 `_ 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 + Driver Base Class Definition + Writing "vendor_passthru" methods + +Testing Network Integration +--------------------------- + +In order to test the integration between the Bare Metal and Networking +services, support has been added to `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 + + +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 Upgrade Guide - Configuration Reference (Mitaka) - 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 + Troubleshooting FAQ + +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 + Configuring Node Inspection + Configuring RAID during deployment + Security considerations for your Bare Metal installation + Adopting Nodes in an ACTIVE state + Auditing API Traffic + Configuring for Multi-tenant Networking + +.. 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) + +.. _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 -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 + Further Considerations for the Agent Drivers + +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 ================== diff --git a/doc/source/webapi/v1.rst b/doc/source/webapi/v1.rst index 64cadeca89..c086b60057 100644 --- a/doc/source/webapi/v1.rst +++ b/doc/source/webapi/v1.rst @@ -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//states/provision, - target:clean, clean_steps:[...]. - -**1.14** - - Make the following endpoints discoverable via Ironic API: - - * '/v1/nodes//states' - * '/v1/drivers//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>`_.