From d88dca0374ddaa32f9ab443c6dcd9f2aced9c8dc Mon Sep 17 00:00:00 2001 From: Luong Anh Tuan Date: Tue, 4 Jul 2017 17:25:27 +0700 Subject: Rearrange existing documentation to fit the new standard layout Change-Id: If0c0789ac730c565477b9053d63375c67667b0d1 --- doc/source/cli.rst | 94 ---------------- doc/source/cli/index.rst | 8 ++ doc/source/cli/ironic_client.rst | 94 ++++++++++++++++ doc/source/cli/osc_plugin_cli.rst | 85 ++++++++++++++ doc/source/contributing.rst | 62 ----------- doc/source/contributor/contributing.rst | 62 +++++++++++ doc/source/contributor/index.rst | 8 ++ doc/source/contributor/testing.rst | 67 +++++++++++ doc/source/create_command.rst | 189 -------------------------------- doc/source/index.rst | 10 +- doc/source/osc_plugin_cli.rst | 85 -------------- doc/source/testing.rst | 67 ----------- doc/source/user/create_command.rst | 189 ++++++++++++++++++++++++++++++++ 13 files changed, 517 insertions(+), 503 deletions(-) delete mode 100644 doc/source/cli.rst create mode 100644 doc/source/cli/index.rst create mode 100644 doc/source/cli/ironic_client.rst create mode 100644 doc/source/cli/osc_plugin_cli.rst delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/contributor/testing.rst delete mode 100644 doc/source/create_command.rst delete mode 100644 doc/source/osc_plugin_cli.rst delete mode 100644 doc/source/testing.rst create mode 100644 doc/source/user/create_command.rst (limited to 'doc/source') diff --git a/doc/source/cli.rst b/doc/source/cli.rst deleted file mode 100644 index 78f1ee3..0000000 --- a/doc/source/cli.rst +++ /dev/null @@ -1,94 +0,0 @@ -============================================== -:program:`ironic` Command-Line Interface (CLI) -============================================== - -.. program:: ironic -.. highlight:: bash - -SYNOPSIS -======== - -:program:`ironic` [options] [command-options] - -:program:`ironic help` - -:program:`ironic help` - - -DESCRIPTION -=========== - -The :program:`ironic` command-line interface (CLI) interacts with the -OpenStack Bare Metal Service (Ironic). - -In order to use the CLI, you must provide your OpenStack username, password, -project (historically called tenant), and auth endpoint. You can use -configuration options :option:`--os-username`, :option:`--os-password`, -:option:`--os-tenant-id` (or :option:`--os-tenant-name`), -and :option:`--os-auth-url`, or set the corresponding -environment variables:: - - $ export OS_USERNAME=user - $ export OS_PASSWORD=password - $ export OS_PROJECT_ID=b363706f891f48019483f8bd6503c54b # or OS_PROJECT_NAME - $ export OS_PROJECT_NAME=project # or OS_PROJECT_ID - $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0 - -The command-line tool will attempt to reauthenticate using the provided -credentials for every request. You can override this behavior by manually -supplying an auth token using :option:`--ironic-url` and -:option:`--os-auth-token`, or by setting the corresponding environment -variables:: - - $ export IRONIC_URL=http://ironic.example.org:6385/ - $ export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 - -Since Keystone can return multiple regions in the Service Catalog, you can -specify the one you want with :option:`--os-region-name` or set the following -environment variable. (It defaults to the first in the list returned.) -:: - - export OS_REGION_NAME=region - -Ironic CLI supports bash completion. The command-line tool can automatically -fill partially typed commands. To use this feature, source the below file -(available at -https://git.openstack.org/cgit/openstack/python-ironicclient/tree/tools/ironic.bash_completion) -to your terminal and then bash completion should work:: - - $ source ironic.bash_completion - -To avoid doing this every time, add this to your ``.bashrc`` or copy the -ironic.bash_completion file to the default bash completion scripts directory -on your linux distribution. - -OPTIONS -======= - -To get a list of available (sub)commands and options, run:: - - $ ironic help - -To get usage and options of a command, run:: - - $ ironic help - - -EXAMPLES -======== - -Get information about the node-create command:: - - $ ironic help node-create - -Get a list of available drivers:: - - $ ironic driver-list - -Enroll a node with "fake" deploy driver and "ipmitool" power driver:: - - $ ironic node-create -d fake_ipmitool -i ipmi_address=1.2.3.4 - -Get a list of nodes:: - - $ ironic node-list diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 0000000..251e71c --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,8 @@ +====================================== +python-ironicclient User Documentation +====================================== + +.. toctree:: + + ironic_client + osc_plugin_cli diff --git a/doc/source/cli/ironic_client.rst b/doc/source/cli/ironic_client.rst new file mode 100644 index 0000000..92c02b0 --- /dev/null +++ b/doc/source/cli/ironic_client.rst @@ -0,0 +1,94 @@ +========================================== +Ironic Client Command-Line Interface (CLI) +========================================== + +.. program:: ironic +.. highlight:: bash + +SYNOPSIS +======== + +:program:`ironic` [options] [command-options] + +:program:`ironic help` + +:program:`ironic help` + + +DESCRIPTION +=========== + +The :program:`ironic` command-line interface (CLI) interacts with the +OpenStack Bare Metal Service (Ironic). + +In order to use the CLI, you must provide your OpenStack username, password, +project (historically called tenant), and auth endpoint. You can use +configuration options :option:`--os-username`, :option:`--os-password`, +:option:`--os-tenant-id` (or :option:`--os-tenant-name`), +and :option:`--os-auth-url`, or set the corresponding +environment variables:: + + $ export OS_USERNAME=user + $ export OS_PASSWORD=password + $ export OS_PROJECT_ID=b363706f891f48019483f8bd6503c54b # or OS_PROJECT_NAME + $ export OS_PROJECT_NAME=project # or OS_PROJECT_ID + $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0 + +The command-line tool will attempt to reauthenticate using the provided +credentials for every request. You can override this behavior by manually +supplying an auth token using :option:`--ironic-url` and +:option:`--os-auth-token`, or by setting the corresponding environment +variables:: + + $ export IRONIC_URL=http://ironic.example.org:6385/ + $ export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 + +Since Keystone can return multiple regions in the Service Catalog, you can +specify the one you want with :option:`--os-region-name` or set the following +environment variable. (It defaults to the first in the list returned.) +:: + + export OS_REGION_NAME=region + +Ironic CLI supports bash completion. The command-line tool can automatically +fill partially typed commands. To use this feature, source the below file +(available at +https://git.openstack.org/cgit/openstack/python-ironicclient/tree/tools/ironic.bash_completion) +to your terminal and then bash completion should work:: + + $ source ironic.bash_completion + +To avoid doing this every time, add this to your ``.bashrc`` or copy the +ironic.bash_completion file to the default bash completion scripts directory +on your linux distribution. + +OPTIONS +======= + +To get a list of available (sub)commands and options, run:: + + $ ironic help + +To get usage and options of a command, run:: + + $ ironic help + + +EXAMPLES +======== + +Get information about the node-create command:: + + $ ironic help node-create + +Get a list of available drivers:: + + $ ironic driver-list + +Enroll a node with "fake" deploy driver and "ipmitool" power driver:: + + $ ironic node-create -d fake_ipmitool -i ipmi_address=1.2.3.4 + +Get a list of nodes:: + + $ ironic node-list diff --git a/doc/source/cli/osc_plugin_cli.rst b/doc/source/cli/osc_plugin_cli.rst new file mode 100644 index 0000000..924d3e5 --- /dev/null +++ b/doc/source/cli/osc_plugin_cli.rst @@ -0,0 +1,85 @@ +============================================= +OpenStack Client Command-Line Interface (CLI) +============================================= + +.. program:: openstack baremetal +.. highlight:: bash + +Synopsis +======== + +:program:`openstack [options] baremetal` [command-options] + +:program:`openstack help baremetal` + + +Description +=========== + +The OpenStack Client plugin interacts with the Bare Metal service +through the ``openstack baremetal`` command line interface (CLI). + +To use ``openstack`` CLI, the OpenStackClient should be installed:: + + # pip install python-openstackclient + +To use the CLI, you must provide your OpenStack username, password, +project, and auth endpoint. You can use configuration options +:option:`--os-username`, :option:`--os-password`, :option:`--os-project-id` +(or :option:`--os-project-name`), and :option:`--os-auth-url`, +or set the corresponding environment variables:: + + $ export OS_USERNAME=user + $ export OS_PASSWORD=password + $ export OS_PROJECT_NAME=project # or OS_PROJECT_ID + $ export OS_PROJECT_DOMAIN_ID=default + $ export OS_USER_DOMAIN_ID=default + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_AUTH_URL=http://auth.example.com:5000/identity + +This CLI is provided by python-openstackclient and osc-lib projects: + +* https://git.openstack.org/openstack/python-openstackclient +* https://git.openstack.org/openstack/osc-lib + + +Getting help +============ + +To get a list of available (sub)commands and options, run:: + + $ openstack help baremetal + +To get usage and options of a command, run:: + + $ openstack help baremetal + + +Examples +======== + +Get information about the openstack baremetal node create command:: + + $ openstack help baremetal node create + +Get a list of available drivers:: + + $ openstack baremetal driver list + +Enroll a node with "agent_ipmitool" driver:: + + $ openstack baremetal node create --driver agent_ipmitool --driver-info ipmi_address=1.2.3.4 + +Get a list of nodes:: + + $ openstack baremetal node list + +The baremetal API version can be specified via: + +* environment variable OS_BAREMETAL_API_VERSION:: + + $ export OS_BAREMETAL_API_VERSION=1.25 + +* or optional command line argument --os-baremetal-api-version:: + + $ openstack baremetal port group list --os-baremetal-api-version 1.25 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 18e8cab..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _contributing: - -=================================== -Contributing to python-ironicclient -=================================== - -If you're interested in contributing to the python-ironicclient project, -the following will help get you started. - -#openstack-ironic on Freenode IRC Network ------------------------------------------ -There is a very active chat channel at irc://freenode.net/#openstack-ironic. -This is usually the best place to ask questions and find your way around. -IRC stands for Internet Relay Chat and it is a way to chat online in real -time. You can ask a question and come back later to read the answer in the -log files. Logs for the #openstack-ironic IRC channel are stored at -http://eavesdrop.openstack.org/irclogs/%23openstack-ironic/. - -Contributor License Agreement ------------------------------ - -.. index:: - single: license; agreement - -In order to contribute to the python-ironicclient 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. After signing up for a launchpad account, join the -"openstack" team to have access to the mailing list and receive -notifications of important events. - -.. seealso:: - - * http://launchpad.net - * http://launchpad.net/python-ironicclient - * http://launchpad.net/~openstack - - -Project Hosting Details ------------------------ - -Bug tracker - http://launchpad.net/python-ironicclient - -Mailing list (prefix subjects with ``[ironic]`` for faster responses) - http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev - -Code Hosting - https://git.openstack.org/cgit/openstack/python-ironicclient - -Code Review - https://review.openstack.org/#/q/status:open+project:openstack/python-ironicclient,n,z - diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000..18e8cab --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,62 @@ +.. _contributing: + +=================================== +Contributing to python-ironicclient +=================================== + +If you're interested in contributing to the python-ironicclient project, +the following will help get you started. + +#openstack-ironic on Freenode IRC Network +----------------------------------------- +There is a very active chat channel at irc://freenode.net/#openstack-ironic. +This is usually the best place to ask questions and find your way around. +IRC stands for Internet Relay Chat and it is a way to chat online in real +time. You can ask a question and come back later to read the answer in the +log files. Logs for the #openstack-ironic IRC channel are stored at +http://eavesdrop.openstack.org/irclogs/%23openstack-ironic/. + +Contributor License Agreement +----------------------------- + +.. index:: + single: license; agreement + +In order to contribute to the python-ironicclient 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. After signing up for a launchpad account, join the +"openstack" team to have access to the mailing list and receive +notifications of important events. + +.. seealso:: + + * http://launchpad.net + * http://launchpad.net/python-ironicclient + * http://launchpad.net/~openstack + + +Project Hosting Details +----------------------- + +Bug tracker + http://launchpad.net/python-ironicclient + +Mailing list (prefix subjects with ``[ironic]`` for faster responses) + http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev + +Code Hosting + https://git.openstack.org/cgit/openstack/python-ironicclient + +Code Review + https://review.openstack.org/#/q/status:open+project:openstack/python-ironicclient,n,z + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..e0c9823 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,8 @@ +============================================= +python-ironicclient Contributor Documentation +============================================= + +.. toctree:: + + contributing + testing diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst new file mode 100644 index 0000000..97a6491 --- /dev/null +++ b/doc/source/contributor/testing.rst @@ -0,0 +1,67 @@ +.. _testing: + +======= +Testing +======= + +Python Guideline Enforcement +............................ + +All code has to pass the pep8 style guideline to merge into OpenStack, to +validate the code against these guidelines you can run:: + + $ tox -e pep8 + +Unit Testing +............ + +It is strongly encouraged to run the unit tests locally under one or more +test environments prior to submitting a patch. To run all the recommended +environments sequentially and pep8 style guideline run:: + + $ tox + +You can also selectively pick specific test environments by listing your +chosen environments after a -e flag:: + + $ tox -e py35,py27,pep8,pypy + +.. note:: + Tox sets up virtual environment and installs all necessary dependencies. + Sharing the environment with devstack testing is not recommended due to + conflicting configuration with system dependencies. + +Functional Testing +.................. + +Functional testing assumes the existence of the script run_functional.sh in the +python-ironicclient/tools directory. The script run_functional.sh generates +test.conf file. To run functional tests just run ./run_functional.sh. + +Also, the test.conf file could be created manually or generated from +environment variables. It assumes the existence of an openstack +cloud installation along with admin credentials. The test.conf file lives in +ironicclient/tests/functional/ directory. To run functional tests in that way +create test.conf manually and run:: + + $ tox -e functional + +An example test.conf file:: + + [functional] + api_version = 1 + os_auth_url=http://192.168.0.2:5000/v2.0/ + os_username=admin + os_password=admin + os_project_name=admin + +If you are testing ironic in standalone mode, only the parameters +'auth_strategy', 'os_auth_token' and 'ironic_url' are required; +all others will be ignored. + +An example test.conf file for standalone host:: + + [functional] + auth_strategy = noauth + os_auth_token = fake + ironic_url = http://10.0.0.2:6385 diff --git a/doc/source/create_command.rst b/doc/source/create_command.rst deleted file mode 100644 index ec966c9..0000000 --- a/doc/source/create_command.rst +++ /dev/null @@ -1,189 +0,0 @@ -=================================================== -Creating the Bare Metal service resources from file -=================================================== - -It is possible to create a set of resources using their descriptions in JSON -or YAML format. It can be done in one of three ways: - -1. Using ironic CLI's ``ironic create`` command:: - - $ ironic help create - usage: ironic create [ ...] - - Create baremetal resources (chassis, nodes, port groups and ports). The - resources may be described in one or more JSON or YAML files. If any file - cannot be validated, no resources are created. An attempt is made to - create all the resources; those that could not be created are skipped - (with a corresponding error message). - - Positional arguments: - File (.yaml or .json) containing descriptions of the resources - to create. Can be specified multiple times. - -2. Using openstackclient plugin command ``openstack baremetal create``:: - - $ openstack -h baremetal create - usage: openstack [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN] - [--max-width ] [--noindent] [--prefix PREFIX] - [--chassis-uuid ] [--driver-info ] - [--property ] [--extra ] - [--uuid ] [--name ] - [--network-interface ] - [--resource-class ] [--driver ] - [ [ ...]] - - Create resources from files or Register a new node (DEPRECATED). Create - resources from files (by only specifying the files) or register a new - node by specifying one or more optional arguments (DEPRECATED, use - 'openstack baremetal node create' instead). - - positional arguments: - File (.yaml or .json) containing descriptions of - the resources to create. Can be specified - multiple times. If you want to create resources, - only specify the files. Do not specify any of - the optional arguments. - - .. note:: - If the ``--driver`` argument is passed in, the behaviour of the command - is the same as ``openstack baremetal node create``, and positional - arguments are ignored. If it is not provided, the command does resource - creation from file(s), and only positional arguments will be taken into - account. - -3. Programmatically using the Python API: - - .. autofunction:: ironicclient.v1.create_resources.create_resources - :noindex: - -File containing Resource Descriptions -===================================== - -The resources to be created can be described either in JSON or YAML. A file -ending with ``.json`` is assumed to contain valid JSON, and a file ending with -``.yaml`` is assumed to contain valid YAML. Specifying a file with any other -extension leads to an error. - -The resources that can be created are chassis, nodes, port groups and ports. -A chassis can contain nodes (and resources of nodes) definitions nested under -``"nodes"`` key. A node can contain port groups definitions nested under -``"portgroups"``, and ports definitions under ``"ports"`` keys. Ports can be -also nested under port groups in ``"ports"`` key. - -The schema used to validate the supplied data is the following:: - - { - "$schema": "http://json-schema.org/draft-04/schema#", - "description": "Schema for ironic resources file", - "type": "object", - "properties": { - "chassis": { - "type": "array", - "items": { - "type": "object" - } - }, - "nodes": { - "type": "array", - "items": { - "type": "object" - } - } - }, - "additionalProperties": False - } - -More detailed description of the creation process can be seen in the following -sections. - -Examples -======== - -Here is an example of the JSON file that can be passed to the ``create`` -command:: - - { - "chassis": [ - { - "description": "chassis 3 in row 23", - "nodes": [ - { - "name": "node-3", - "driver": "agent_ipmitool", - "portgroups": [ - { - "name": "switch.cz7882.ports.1-2", - "ports": [ - { - "address": "ff:00:00:00:00:00" - }, - { - "address": "ff:00:00:00:00:01" - } - ] - } - ], - "ports": [ - { - "address": "00:00:00:00:00:02" - }, - { - "address": "00:00:00:00:00:03" - } - ] - }, - { - "name": "node-4", - "driver": "agent_ipmitool", - "ports": [ - { - "address": "00:00:00:00:00:04" - }, - { - "address": "00:00:00:00:00:01" - } - ] - } - ] - } - ], - "nodes": [ - { - "name": "node-5", - "driver": "pxe_ipmitool", - "chassis_uuid": "74d93e6e-7384-4994-a614-fd7b399b0785", - "ports": [ - { - "address": "00:00:00:00:00:00" - } - ] - }, - { - "name": "node-6", - "driver": "pxe_ipmitool" - } - ] - } - -Creation Process -================ - -#. The client deserializes the files' contents and validates that the top-level - dictionary in each of them contains only "chassis" and/or "nodes" keys, - and their values are lists. The creation process is aborted if any failure - is encountered in this stage. The rest of the validation is done by the - ironic-api service. - -#. Each resource is created via issuing a POST request (with the resource's - dictionary representation in the body) to the ironic-api service. In the - case of nested resources (``"nodes"`` key inside chassis, ``"portgroups"`` - key inside nodes, ``"ports"`` key inside nodes or portgroups), the top-level - resource is created first, followed by the sub-resources. For example, if a - chassis contains a list of nodes, the chassis will be created first followed - by the creation of each node. The same is true for ports and port groups - described within nodes. - -#. If a resource could not be created, it does not stop the entire process. - Any sub-resources of the failed resource will not be created, but otherwise, - the rest of the resources will be created if possible. Any failed resources - will be mentioned in the response. diff --git a/doc/source/index.rst b/doc/source/index.rst index a7e7156..16766d7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,14 +10,12 @@ Contents ======== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 api_v1 - cli - osc_plugin_cli - create_command - contributing - testing + cli/index + user/create_command + contributor/index Release Notes Indices and tables diff --git a/doc/source/osc_plugin_cli.rst b/doc/source/osc_plugin_cli.rst deleted file mode 100644 index 119bc44..0000000 --- a/doc/source/osc_plugin_cli.rst +++ /dev/null @@ -1,85 +0,0 @@ -============================================================================ -:program:`openstack baremetal` OpenStack Client Command-Line Interface (CLI) -============================================================================ - -.. program:: openstack baremetal -.. highlight:: bash - -Synopsis -======== - -:program:`openstack [options] baremetal` [command-options] - -:program:`openstack help baremetal` - - -Description -=========== - -The OpenStack Client plugin interacts with the Bare Metal service -through the ``openstack baremetal`` command line interface (CLI). - -To use ``openstack`` CLI, the OpenStackClient should be installed:: - - # pip install python-openstackclient - -To use the CLI, you must provide your OpenStack username, password, -project, and auth endpoint. You can use configuration options -:option:`--os-username`, :option:`--os-password`, :option:`--os-project-id` -(or :option:`--os-project-name`), and :option:`--os-auth-url`, -or set the corresponding environment variables:: - - $ export OS_USERNAME=user - $ export OS_PASSWORD=password - $ export OS_PROJECT_NAME=project # or OS_PROJECT_ID - $ export OS_PROJECT_DOMAIN_ID=default - $ export OS_USER_DOMAIN_ID=default - $ export OS_IDENTITY_API_VERSION=3 - $ export OS_AUTH_URL=http://auth.example.com:5000/identity - -This CLI is provided by python-openstackclient and osc-lib projects: - -* https://git.openstack.org/openstack/python-openstackclient -* https://git.openstack.org/openstack/osc-lib - - -Getting help -============ - -To get a list of available (sub)commands and options, run:: - - $ openstack help baremetal - -To get usage and options of a command, run:: - - $ openstack help baremetal - - -Examples -======== - -Get information about the openstack baremetal node create command:: - - $ openstack help baremetal node create - -Get a list of available drivers:: - - $ openstack baremetal driver list - -Enroll a node with "agent_ipmitool" driver:: - - $ openstack baremetal node create --driver agent_ipmitool --driver-info ipmi_address=1.2.3.4 - -Get a list of nodes:: - - $ openstack baremetal node list - -The baremetal API version can be specified via: - -* environment variable OS_BAREMETAL_API_VERSION:: - - $ export OS_BAREMETAL_API_VERSION=1.25 - -* or optional command line argument --os-baremetal-api-version:: - - $ openstack baremetal port group list --os-baremetal-api-version 1.25 diff --git a/doc/source/testing.rst b/doc/source/testing.rst deleted file mode 100644 index 97a6491..0000000 --- a/doc/source/testing.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _testing: - -======= -Testing -======= - -Python Guideline Enforcement -............................ - -All code has to pass the pep8 style guideline to merge into OpenStack, to -validate the code against these guidelines you can run:: - - $ tox -e pep8 - -Unit Testing -............ - -It is strongly encouraged to run the unit tests locally under one or more -test environments prior to submitting a patch. To run all the recommended -environments sequentially and pep8 style guideline run:: - - $ tox - -You can also selectively pick specific test environments by listing your -chosen environments after a -e flag:: - - $ tox -e py35,py27,pep8,pypy - -.. note:: - Tox sets up virtual environment and installs all necessary dependencies. - Sharing the environment with devstack testing is not recommended due to - conflicting configuration with system dependencies. - -Functional Testing -.................. - -Functional testing assumes the existence of the script run_functional.sh in the -python-ironicclient/tools directory. The script run_functional.sh generates -test.conf file. To run functional tests just run ./run_functional.sh. - -Also, the test.conf file could be created manually or generated from -environment variables. It assumes the existence of an openstack -cloud installation along with admin credentials. The test.conf file lives in -ironicclient/tests/functional/ directory. To run functional tests in that way -create test.conf manually and run:: - - $ tox -e functional - -An example test.conf file:: - - [functional] - api_version = 1 - os_auth_url=http://192.168.0.2:5000/v2.0/ - os_username=admin - os_password=admin - os_project_name=admin - -If you are testing ironic in standalone mode, only the parameters -'auth_strategy', 'os_auth_token' and 'ironic_url' are required; -all others will be ignored. - -An example test.conf file for standalone host:: - - [functional] - auth_strategy = noauth - os_auth_token = fake - ironic_url = http://10.0.0.2:6385 diff --git a/doc/source/user/create_command.rst b/doc/source/user/create_command.rst new file mode 100644 index 0000000..ec966c9 --- /dev/null +++ b/doc/source/user/create_command.rst @@ -0,0 +1,189 @@ +=================================================== +Creating the Bare Metal service resources from file +=================================================== + +It is possible to create a set of resources using their descriptions in JSON +or YAML format. It can be done in one of three ways: + +1. Using ironic CLI's ``ironic create`` command:: + + $ ironic help create + usage: ironic create [ ...] + + Create baremetal resources (chassis, nodes, port groups and ports). The + resources may be described in one or more JSON or YAML files. If any file + cannot be validated, no resources are created. An attempt is made to + create all the resources; those that could not be created are skipped + (with a corresponding error message). + + Positional arguments: + File (.yaml or .json) containing descriptions of the resources + to create. Can be specified multiple times. + +2. Using openstackclient plugin command ``openstack baremetal create``:: + + $ openstack -h baremetal create + usage: openstack [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN] + [--max-width ] [--noindent] [--prefix PREFIX] + [--chassis-uuid ] [--driver-info ] + [--property ] [--extra ] + [--uuid ] [--name ] + [--network-interface ] + [--resource-class ] [--driver ] + [ [ ...]] + + Create resources from files or Register a new node (DEPRECATED). Create + resources from files (by only specifying the files) or register a new + node by specifying one or more optional arguments (DEPRECATED, use + 'openstack baremetal node create' instead). + + positional arguments: + File (.yaml or .json) containing descriptions of + the resources to create. Can be specified + multiple times. If you want to create resources, + only specify the files. Do not specify any of + the optional arguments. + + .. note:: + If the ``--driver`` argument is passed in, the behaviour of the command + is the same as ``openstack baremetal node create``, and positional + arguments are ignored. If it is not provided, the command does resource + creation from file(s), and only positional arguments will be taken into + account. + +3. Programmatically using the Python API: + + .. autofunction:: ironicclient.v1.create_resources.create_resources + :noindex: + +File containing Resource Descriptions +===================================== + +The resources to be created can be described either in JSON or YAML. A file +ending with ``.json`` is assumed to contain valid JSON, and a file ending with +``.yaml`` is assumed to contain valid YAML. Specifying a file with any other +extension leads to an error. + +The resources that can be created are chassis, nodes, port groups and ports. +A chassis can contain nodes (and resources of nodes) definitions nested under +``"nodes"`` key. A node can contain port groups definitions nested under +``"portgroups"``, and ports definitions under ``"ports"`` keys. Ports can be +also nested under port groups in ``"ports"`` key. + +The schema used to validate the supplied data is the following:: + + { + "$schema": "http://json-schema.org/draft-04/schema#", + "description": "Schema for ironic resources file", + "type": "object", + "properties": { + "chassis": { + "type": "array", + "items": { + "type": "object" + } + }, + "nodes": { + "type": "array", + "items": { + "type": "object" + } + } + }, + "additionalProperties": False + } + +More detailed description of the creation process can be seen in the following +sections. + +Examples +======== + +Here is an example of the JSON file that can be passed to the ``create`` +command:: + + { + "chassis": [ + { + "description": "chassis 3 in row 23", + "nodes": [ + { + "name": "node-3", + "driver": "agent_ipmitool", + "portgroups": [ + { + "name": "switch.cz7882.ports.1-2", + "ports": [ + { + "address": "ff:00:00:00:00:00" + }, + { + "address": "ff:00:00:00:00:01" + } + ] + } + ], + "ports": [ + { + "address": "00:00:00:00:00:02" + }, + { + "address": "00:00:00:00:00:03" + } + ] + }, + { + "name": "node-4", + "driver": "agent_ipmitool", + "ports": [ + { + "address": "00:00:00:00:00:04" + }, + { + "address": "00:00:00:00:00:01" + } + ] + } + ] + } + ], + "nodes": [ + { + "name": "node-5", + "driver": "pxe_ipmitool", + "chassis_uuid": "74d93e6e-7384-4994-a614-fd7b399b0785", + "ports": [ + { + "address": "00:00:00:00:00:00" + } + ] + }, + { + "name": "node-6", + "driver": "pxe_ipmitool" + } + ] + } + +Creation Process +================ + +#. The client deserializes the files' contents and validates that the top-level + dictionary in each of them contains only "chassis" and/or "nodes" keys, + and their values are lists. The creation process is aborted if any failure + is encountered in this stage. The rest of the validation is done by the + ironic-api service. + +#. Each resource is created via issuing a POST request (with the resource's + dictionary representation in the body) to the ironic-api service. In the + case of nested resources (``"nodes"`` key inside chassis, ``"portgroups"`` + key inside nodes, ``"ports"`` key inside nodes or portgroups), the top-level + resource is created first, followed by the sub-resources. For example, if a + chassis contains a list of nodes, the chassis will be created first followed + by the creation of each node. The same is true for ports and port groups + described within nodes. + +#. If a resource could not be created, it does not stop the entire process. + Any sub-resources of the failed resource will not be created, but otherwise, + the rest of the resources will be created if possible. Any failed resources + will be mentioned in the response. -- cgit v1.2.1