diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000000..8dc0326549 --- /dev/null +++ b/.coveragerc @@ -0,0 +1,7 @@ +[run] +branch = True +source = openstackclient +omit = openstackclient/tests/* + +[report] +ignore_errors = True diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 0000000000..62caf9485a --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,13 @@ +# You can configure git to automatically use this file with the following config: +# git config --global blame.ignoreRevsFile .git-blame-ignore-revs + +c5b772db76c071e493a81105c7d8c0def08b2264 # trivial: Prepare for pyupgrade pre-commit hook +ed0314ac76ae58a6621077feb742efd5c14c3a62 # Blacken everything else +ac64fdb93c32972575a4523ccb23d0279ef584f5 # Blacken openstackclient.api +a3778109d0051a25901569e7bafe54915ab25f82 # Blacken openstack.common +53476e1f73d8af172207ac7089fb85fc0221859f # Blacken openstackclient.image +c51e4ef1bc350905a04690eb019d53e68fe3d633 # Blacken openstackclient.object +af6ea07703ed1c12b86995b97a9618bfa70721ee # Blacken openstackclient.identity +1face4f48b07fbc51824980e989687adaf453f0e # Blacken openstackclient.network +1ca77acc9118b433c14e03bf9fd28f2b1639c430 # Blacken openstackclient.volume +4bbf3bd3846cb3d85e243199910de82df25d35e0 # Blacken openstackclient.compute diff --git a/.gitignore b/.gitignore index 4624f7dd23..54cdd4fccf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,26 @@ +*.DS_Store +*.egg* *.log -*.log.* +*.mo *.pyc +*.swo *.swp *~ -.openstackclient-venv -.venv +.coverage +.idea +.stestr/ +.testrepository +.tox AUTHORS build -dist -python_openstackclient.egg-info -.tox/ ChangeLog -TAGS -openstackclient/versioninfo +dist +# Doc related +doc/build +doc/source/contributor/api/ +# Development environment files +.project +.pydevproject +cover +# Files created by releasenotes build +releasenotes/build diff --git a/.gitreview b/.gitreview index 784c1900ea..4eee726db6 100644 --- a/.gitreview +++ b/.gitreview @@ -1,4 +1,4 @@ [gerrit] -host=review.openstack.org +host=review.opendev.org port=29418 project=openstack/python-openstackclient.git diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000000..c3f1f5615d --- /dev/null +++ b/.mailmap @@ -0,0 +1,2 @@ + + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000000..b277bb059b --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,42 @@ +--- +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: trailing-whitespace + - id: mixed-line-ending + args: ['--fix', 'lf'] + exclude: '.*\.(svg)$' + - id: fix-byte-order-marker + - id: check-executables-have-shebangs + - id: check-merge-conflict + - id: debug-statements + - id: check-yaml + files: .*\.(yaml|yml)$ + args: ['--unsafe'] + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.14.0 + hooks: + - id: ruff-check + args: ['--fix', '--unsafe-fixes'] + - id: ruff-format + - repo: https://opendev.org/openstack/hacking + rev: 7.0.0 + hooks: + - id: hacking + additional_dependencies: [] + exclude: '^(doc|releasenotes)/.*$' + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.18.2 + hooks: + - id: mypy + additional_dependencies: + - types-requests + # keep this in-sync with '[tool.mypy] exclude' in 'pyproject.toml' + exclude: | + (?x)( + doc/.* + | examples/.* + | hacking/.* + | releasenotes/.* + ) diff --git a/.stestr.conf b/.stestr.conf new file mode 100644 index 0000000000..75aec670d7 --- /dev/null +++ b/.stestr.conf @@ -0,0 +1,4 @@ +[DEFAULT] +test_path=${OS_TEST_PATH:-./openstackclient/tests/unit} +top_dir=./ +group_regex=([^\.]+\.)+ diff --git a/.zuul.yaml b/.zuul.yaml new file mode 100644 index 0000000000..d63ee7c5f4 --- /dev/null +++ b/.zuul.yaml @@ -0,0 +1,187 @@ +--- +- job: + name: osc-tox-unit-tips + parent: openstack-tox + description: | + Run unit tests for OpenStackClient with master branch of important libs. + + Takes advantage of the base tox job's install-siblings feature. + irrelevant-files: &common-irrelevant-files + - ^.*\.rst$ + - ^doc/.*$ + - ^releasenotes/.*$ + - ^\.pre-commit-config\.yaml$ + required-projects: + - openstack/cliff + - openstack/keystoneauth + - openstack/openstacksdk + - openstack/osc-lib + - openstack/python-openstackclient + vars: + # Set work dir to openstackclient so that if it's triggered by one of the + # other repos the tests will run in the same place + zuul_work_dir: src/opendev.org/openstack/python-openstackclient + +- job: + name: osc-tox-py310-tips + parent: openstack-tox-py310 + description: | + Run unit tests for OpenStackClient with master branch of important libs. + + Takes advantage of the base tox job's install-siblings feature. + # The job only tests the latest and shouldn't be run on the stable branches + branches: ^master$ + required-projects: + - openstack/cliff + - openstack/keystoneauth + - openstack/openstacksdk + - openstack/osc-lib + - openstack/python-openstackclient + vars: + # Set work dir to openstackclient so that if it's triggered by one of the + # other repos the tests will run in the same place + zuul_work_dir: src/opendev.org/openstack/python-openstackclient + +- job: + name: osc-tox-py313-tips + parent: openstack-tox-py313 + description: | + Run unit tests for OpenStackClient with master branch of important libs. + + Takes advantage of the base tox job's install-siblings feature. + # The job only tests the latest and shouldn't be run on the stable branches + branches: ^master$ + required-projects: + - openstack/cliff + - openstack/keystoneauth + - openstack/openstacksdk + - openstack/osc-lib + - openstack/python-openstackclient + vars: + # Set work dir to openstackclient so that if it's triggered by one of the + # other repos the tests will run in the same place + zuul_work_dir: src/opendev.org/openstack/python-openstackclient + +- job: + name: osc-functional-devstack + parent: devstack-tox-functional + description: | + Run functional tests for OpenStackClient. + timeout: 7800 + irrelevant-files: + - ^.*\.rst$ + - ^doc/.*$ + - ^releasenotes/.*$ + required-projects: + - openstack/python-openstackclient + vars: + devstack_localrc: + LIBS_FROM_GIT: python-openstackclient + # NOTE(dtroyer): Functional tests need a bit more volume headroom + VOLUME_BACKING_FILE_SIZE: 20G + Q_AGENT: openvswitch + Q_ML2_TENANT_NETWORK_TYPE: vxlan + Q_ML2_PLUGIN_MECHANISM_DRIVERS: openvswitch + devstack_plugins: + # NOTE(amotoki): Some neutron features are enabled by devstack plugin + neutron: https://opendev.org/openstack/neutron + devstack_services: + s-account: true + s-container: true + s-object: true + s-proxy: true + # Disable OVN services + br-ex-tcpdump: false + br-int-flows: false + ovn-controller: false + ovn-northd: false + ovs-vswitchd: false + ovsdb-server: false + q-ovn-metadata-agent: false + # Neutron services + q-agt: true + q-dhcp: true + q-l3: true + q-meta: true + neutron-network-segment-range: true + neutron-segments: true + q-metering: true + q-qos: true + neutron-tag-ports-during-bulk-creation: true + neutron-conntrack-helper: true + neutron-ndp-proxy: true + q-trunk: true + osc_environment: + PYTHONUNBUFFERED: 'true' + OS_CLOUD: devstack-admin + tox_envlist: functional + zuul_work_dir: src/opendev.org/openstack/python-openstackclient + +- job: + name: osc-functional-devstack-tips + parent: osc-functional-devstack + description: | + Run functional tests for OpenStackClient with master branch of important libs. + + Takes advantage of the base tox job's install-siblings feature. + timeout: 7800 + required-projects: + - openstack/cliff + - openstack/keystoneauth + - openstack/openstacksdk + - openstack/osc-lib + - openstack/python-openstackclient + vars: + devstack_localrc: + LIBS_FROM_GIT: python-openstackclient,openstacksdk,osc-lib,cliff + tox_envlist: functional + tox_install_siblings: true + +- job: + name: osc-build-image + parent: opendev-build-docker-image + description: Build Docker images. + allowed-projects: openstack/python-openstackclient + requires: + - python-builder-3.11-bookworm-container-image + - python-base-3.11-bookworm-container-image + provides: osc-container-image + vars: + docker_images: + - context: . + tags: [] + +- project-template: + name: osc-tox-unit-tips + check: + jobs: + - osc-tox-py310-tips + - osc-tox-py313-tips + gate: + jobs: + - osc-tox-py310-tips + - osc-tox-py313-tips + +- project: + templates: + - openstackclient-plugin-jobs + - osc-tox-unit-tips + - openstack-cover-jobs + - openstack-python3-jobs + - publish-openstack-docs-pti + - check-requirements + - release-notes-jobs-python3 + check: + jobs: + - openstackclient-check-plugins: + voting: true + - osc-build-image: + voting: false + - osc-functional-devstack + - osc-functional-devstack-tips: + # The functional-tips job only tests the latest and shouldn't be run + # on the stable branches + branches: ^master$ + gate: + jobs: + - osc-functional-devstack diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000000..74b442ef66 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,27 @@ +The source repository for this project can be found at: + + https://opendev.org/openstack/python-openstackclient + +Pull requests submitted through GitHub are not monitored. + +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: + + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html + +Bugs should be filed on Launchpad: + + https://bugs.launchpad.net/python-openstackclient + +Developers should also join the discussion on the mailing list, at: + + https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/ + +or join the IRC channel on + + #openstack-sdks on OFTC (irc.oftc.net) + +For more specific information about contributing to this repository, see the +openstacksdk contributor guide: + + https://docs.openstack.org/openstacksdk/latest/contributor/index.html diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..6709be7514 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,36 @@ +# Copyright (c) 2020 Red Hat, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +FROM docker.io/opendevorg/python-builder:3.12-bookworm AS builder + +COPY . /tmp/src +RUN assemble + +FROM docker.io/opendevorg/python-base:3.12-bookworm + +LABEL org.opencontainers.image.title="python-openstackclient" +LABEL org.opencontainers.image.description="Client for OpenStack services." +LABEL org.opencontainers.image.licenses="Apache License 2.0" +LABEL org.opencontainers.image.url="https://www.openstack.org/" +LABEL org.opencontainers.image.documentation="https://docs.openstack.org/python-openstackclient/latest/" +LABEL org.opencontainers.image.source="https://opendev.org/openstack/python-openstackclient" + +COPY --from=builder /output/ /output +RUN /output/install-from-bindep + +# Trigger entrypoint loading to trigger stevedore entrypoint caching +RUN openstack --help >/dev/null 2>&1 + +CMD ["/usr/local/bin/openstack"] diff --git a/HACKING b/HACKING deleted file mode 100644 index 1218e5f712..0000000000 --- a/HACKING +++ /dev/null @@ -1,114 +0,0 @@ -OpenStack Style Commandments -============================ - -Step 1: Read http://www.python.org/dev/peps/pep-0008/ -Step 2: Read http://www.python.org/dev/peps/pep-0008/ again -Step 3: Read on - -Imports -------- -- thou shalt not import objects, only modules -- thou shalt not import more than one module per line -- thou shalt not make relative imports -- thou shalt organize your imports according to the following template - -:: - # vim: tabstop=4 shiftwidth=4 softtabstop=4 - {{stdlib imports in human alphabetical order}} - \n - {{3rd-party imports in human alphabetical order}} - \n - {{openstack imports in human alphabetical order}} - \n - \n - {{begin your code}} - -General -------- -- thou shalt put two newlines twixt toplevel code (funcs, classes, etc) -- thou shalt put one newline twixt methods in classes and anywhere else -- thou shalt not write "except:", use "except Exception:" at the very least -- thou shalt include your name with TODOs as in "TODO(termie)" -- thou shalt not name anything the same name as a builtin or reserved word -- thou shalt not violate causality in our time cone, or else - -Human Alphabetical Order Examples ---------------------------------- -:: - import httplib - import logging - import random - import StringIO - import time - import unittest - - from nova import flags - from nova import test - from nova.auth import users - from nova.endpoint import api - from nova.endpoint import cloud - -Docstrings ----------- - """A one line docstring looks like this and ends in a period.""" - - """A multiline docstring has a one-line summary, less than 80 characters. - - Then a new paragraph after a newline that explains in more detail any - general information about the function, class or method. Example usages - are also great to have here if it is a complex class for function. After - you have finished your descriptions add an extra newline and close the - quotations. - - When writing the docstring for a class, an extra line should be placed - after the closing quotations. For more in-depth explanations for these - decisions see http://www.python.org/dev/peps/pep-0257/ - - If you are going to describe parameters and return values, use Sphinx, the - appropriate syntax is as follows. - - :param foo: the foo parameter - :param bar: the bar parameter - :returns: description of the return value - - """ - -Text encoding ----------- -- All text within python code should be of type 'unicode'. - - WRONG: - - >>> s = 'foo' - >>> s - 'foo' - >>> type(s) - - - RIGHT: - - >>> u = u'foo' - >>> u - u'foo' - >>> type(u) - - -- Transitions between internal unicode and external strings should always - be immediately and explicitly encoded or decoded. - -- All external text that is not explicitly encoded (database storage, - commandline arguments, etc.) should be presumed to be encoded as utf-8. - - WRONG: - - mystring = infile.readline() - myreturnstring = do_some_magic_with(mystring) - outfile.write(myreturnstring) - - RIGHT: - - mystring = infile.readline() - mytext = s.decode('utf-8') - returntext = do_some_magic_with(mytext) - returnstring = returntext.encode('utf-8') - outfile.write(returnstring) diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 0000000000..432d19f4e4 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,42 @@ +OpenStack Style Commandments +============================ + +- Step 1: Read the OpenStack Style Commandments + https://docs.openstack.org/hacking/latest/ +- Step 2: Read on + +General +------- + +- thou shalt not violate causality in our time cone, or else + +Docstrings +---------- + +Docstrings should ONLY use triple-double-quotes (``"""``) + +Single-line docstrings should NEVER have extraneous whitespace +between enclosing triple-double-quotes. + +Deviation! Sentence fragments do not have punctuation. Specifically in the +command classes the one line docstring is also the help string for that +command and those do not have periods. + + """A one line docstring looks like this""" + +Calling Methods +--------------- + +Deviation! When breaking up method calls due to the 79 char line length limit, +use the alternate 4 space indent. With the first argument on the succeeding +line all arguments will then be vertically aligned. Use the same convention +used with other data structure literals and terminate the method call with +the last argument line ending with a comma and the closing paren on its own +line indented to the starting line level. :: + + unnecessarily_long_function_name( + 'string one', + 'string two', + kwarg1=constants.ACTIVE, + kwarg2=['a', 'b', 'c'], + ) diff --git a/LICENSE b/LICENSE index d645695673..68c771a099 100644 --- a/LICENSE +++ b/LICENSE @@ -174,29 +174,3 @@ incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 0856b5efb6..0000000000 --- a/MANIFEST.in +++ /dev/null @@ -1,6 +0,0 @@ -include AUTHORS -include LICENSE -include README.rst -include openstackclient/versioninfo -recursive-include doc * -recursive-include tests * diff --git a/README.rst b/README.rst index 4ea7000d4b..af3837a351 100644 --- a/README.rst +++ b/README.rst @@ -1,124 +1,229 @@ -================ -OpenStack Client -================ - -python-openstackclient is a unified command-line client for the OpenStack APIs. It is -a thin wrapper to the stock python-*client modules that implement the -actual REST API client actions. - -This is an implementation of the design goals shown in -http://wiki.openstack.org/UnifiedCLI. The primary goal is to provide -a unified shell command structure and a common language to describe -operations in OpenStack. - -python-openstackclient is designed to add support for API extensions via a -plugin mechanism - -For release management: - - * https://launchpad.net/python-openstackclient - -For blueprints and feature specifications: +=============== +OpenStackClient +=============== - * https://blueprints.launchpad.net/python-openstackclient +.. image:: https://img.shields.io/pypi/v/python-openstackclient.svg + :target: https://pypi.org/project/python-openstackclient/ + :alt: Latest Version -For issue tracking: +OpenStackClient (OSC) is a command-line client for OpenStack that brings +the command set for Compute, Identity, Image, Network, Object Store and Block +Storage APIs together in a single shell with a uniform command structure. +Support for additional service APIs is provided via plugins. - * https://bugs.launchpad.net/python-openstackclient +The primary goal is to provide a unified shell command structure and a common +language to describe operations in OpenStack. Getting Started =============== -We recommend using a virtualenv to install the client. This description -uses `virtualenvwrapper`_ to create the virtualenv. Install the prereqs, -then build the egg, and install the client into the virtualenv:: - - mkvirtualenv openstackclient - pip install -r tools/pip-requires - python setup.py build - easy_install dist/python_openstackclient-0.1-py2.7.egg - -.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper +OpenStack Client can be installed from PyPI using pip: -If you want to work in development mode, do this instead:: +.. code-block:: shell - mkvirtualenv openstackclient - pip install -r tools/pip-requires - python setup.py develop + python3 -m pip install python-openstackclient -Toxicity tests can be ran simply by running ``run_tests.sh`` +You can use ``--help`` or the ``help`` command to get a list of global options +and supported commands: -The client can be called interactively by simply typing:: - openstack +.. code-block:: shell -Alternatively command line parameters can be called non-interactively:: - openstack --help + openstack --help + openstack help +You can also get help for a specific command: -Configuration -============= - -The cli is configured via environment variables and command-line -options as listed in http://wiki.openstack.org/UnifiedCLI/Authentication. +.. code-block:: shell -The 'password flow' variation is most commonly used:: + openstack server create --help + openstack help server create - export OS_AUTH_URL= - export OS_TENANT_NAME= - export OS_USERNAME= - export OS_PASSWORD= # (optional) +You can add support for additional services by installing their clients. For +example, to add support for the DNS service (designate): -The corresponding command-line options look very similar:: +.. code-block:: shell - --os-auth-url - --os-tenant-name - --os-username - [--os-password ] + python3 -m pip install python3-designateclient -If a password is not provided above (in plaintext), you will be interactively -prompted to provide one securely. +A ``Dockerfile`` is provided for your convenience in the repository. You can +use this to build your own container images: -The token flow variation for authentication uses an already-aquired token -and a URL pointing directly to the service API that presumably was acquired -from the Service Catalog:: +.. code-block:: shell - export OS_TOKEN= - export OS_URL= + git clone https://opendev.org/openstack/python-openstackclient + cd python-openstackclient + podman build . -t example.com/myuser/openstackclient -The corresponding command-line options look very similar:: +For more information the available options and commands, refer to the `Users +Guide`__. - --os-token - --os-url +.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html -Additional command-line options and their associated environment variables -are listed here:: - - --debug # turns on some debugging of the API conversation - (via httplib2) - --verbose | -v # Increase verbosity of output. Can be repeated. - --quiet | -q # suppress output except warnings and errors - --help | -h # show a help message and exit - -Building Contributor Documentation -================================== - -This documentation is written by contributors, for contributors. - -The source is maintained in the ``doc/source`` folder using -`reStructuredText`_ and built by `Sphinx`_ - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Sphinx: http://sphinx.pocoo.org/ - -* Building Automatically:: - - $ ./run_tests.sh --docs - -* Building Manually:: - - $ export DJANGO_SETTINGS_MODULE=local.local_settings - $ python doc/generate_autodoc_index.py - $ sphinx-build -b html doc/source build/sphinx/html - -Results are in the `build/sphinx/html` directory +Configuration +============= +OpenStack Client must be configured with authentication information in order to +communicate with a given OpenStack cloud. This configuration can be achieved +via a ``clouds.yaml`` file, a set of environment variables (often shared via an +``openrc`` file), a set of command-line options, or a combination of all three. +Your cloud provider or deployment tooling will typically provide either a +``clouds.yaml`` file or ``openrc`` file for you. If using a ``clouds.yaml`` +file, OpenStack Client expects to find it in one of the following locations: + +* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment + variable +* ``.`` (the current directory) +* ``$HOME/.config/openstack`` +* ``/etc/openstack`` + +The options you should set will depend on the configuration of your cloud and +the authentication mechanism(s) supported. For example, consider a cloud that +supports username/password authentication. Configuration for this cloud using a +``clouds.yaml`` file would look like so: + +.. code-block:: yaml + + clouds: + my-cloud: + auth: + auth_url: '' + project_name: '' + project_domain_name: '' + username: '' + user_domain_name: '' + password: '' # (optional) + region_name: '' + +The corresponding environment variables would look very similar: + +.. code-block:: shell + + export OS_AUTH_URL= + export OS_REGION_NAME= + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_USERNAME= + export OS_USER_DOMAIN_NAME= + export OS_PASSWORD= # (optional) + +Likewise, the corresponding command-line options would look very similar: + +:: + + openstack + --os-auth-url + --os-region + --os-project-name + --os-project-domain-name + --os-username + --os-user-domain-name + [--os-password ] + +.. note:: + + If a password is not provided above (in plaintext), you will be + interactively prompted to provide one securely. + +Some clouds use federated authentication. If this is the case, your +configuration will be slightly more involved. For example, to configure +username/password authentication for a federated user using a ``clouds.yaml`` +file: + +.. code-block:: yaml + + clouds: + my-cloud: + auth: + auth_url: '' + project_name: '' + project_domain_name: '' + username: '' + user_domain_name: '' + password: '' + identity_provider: '' + client_id: '' + client_secret: '' + openid_scope: '' + protocol: '' + access_token_type: '' + discovery_endpoint: '' + auth_type: 'v3oidcpassword' + region_name: '' + +The corresponding environment variables would look very similar: + +.. code-block:: shell + + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_AUTH_TYPE=v3oidcpassword + export OS_USERNAME= + export OS_PASSWORD= + export OS_IDENTITY_PROVIDER= + export OS_CLIENT_ID= + export OS_CLIENT_SECRET= + export OS_OPENID_SCOPE= + export OS_PROTOCOL= + export OS_ACCESS_TOKEN_TYPE= + export OS_DISCOVERY_ENDPOINT= + +Likewise, the corresponding command-line options would look very similar: + +.. code-block:: shell + + --os-project-name + --os-project-domain-name + --os-auth-url + --os-identity-api-version 3 + --os-auth-plugin openid + --os-auth-type v3oidcpassword + --os-username + --os-password + --os-identity-provider + --os-client-id + --os-client-secret + --os-openid-scope + --os-protocol + --os-access-token-type + --os-discovery-endpoint + +For more information on configuring authentication, including an overview of +the many authentication mechanisms supported, refer to the `Authentication +guide`__. For more information on configuration in general, refer to the +`Configuration guide`__. + +.. __: https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html. +.. __: https://docs.openstack.org/python-openstackclient/latest/configuration/index.html + +Contributing +============ + +You can clone the repository from opendev.org:: + + git clone https://opendev.org/openstack/python-openstackclient + cd python-openstackclient + +OpenStack Client uses the same contributor process as other OpenStack projects. +For information on this process, including help on setting up you Gerrit +account and an overview of the CI process, refer to the `OpenStack Contributors +Guide`__. + +For more information on contributing to OpenStack Client itself, including +guidance on how to design new commands and how to report bugs, refer to the +`Contributors Guide`__. + +.. __: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html +.. __: https://docs.opendev.org/opendev/infra-manual/latest/developers.html + +Links +----- + +* `Issue Tracker `_ +* `Code Review `_ +* `Documentation `_ +* `PyPi `_ +* `Mailing list `_ +* `Release Notes `_ +* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) `_ diff --git a/bindep.txt b/bindep.txt new file mode 100644 index 0000000000..8402431aed --- /dev/null +++ b/bindep.txt @@ -0,0 +1,11 @@ +# This is a cross-platform list tracking distribution packages needed by tests; +# see https://docs.openstack.org/infra/bindep/ for additional information. + +gcc [compile test] +libc6-dev [compile test platform:dpkg] +libffi-devel [platform:rpm] +libffi-dev [compile test platform:dpkg] +libssl-dev [compile test platform:dpkg] +python3-dev [compile test platform:dpkg] +python3-devel [compile test platform:rpm] +libpcre2-dev [test platform:dpkg] diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..05a9bfa87c --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,27 @@ +openstackdocstheme>=2.2.1 # Apache-2.0 +reno>=3.1.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-apidoc>=0.2.0 # BSD + +# redirect tests in docs +whereto>=0.5.0 # Apache-2.0 + +# Install these to generate sphinx autodocs +aodhclient>=0.9.0 # Apache-2.0 +gnocchiclient>=3.3.1 # Apache-2.0 +osc-placement>=1.7.0 # Apache-2.0 +python-barbicanclient>=4.5.2 # Apache-2.0 +python-cyborgclient>=1.2.1 # Apache-2.0 +python-designateclient>=2.7.0 # Apache-2.0 +python-heatclient>=1.10.0 # Apache-2.0 +python-ironicclient>=2.3.0 # Apache-2.0 +python-ironic-inspector-client>=1.5.0 # Apache-2.0 +python-magnumclient>=2.3.0 # Apache-2.0 +python-manilaclient>=2.0.0 # Apache-2.0 +python-mistralclient!=3.2.0,>=3.1.0 # Apache-2.0 +python-neutronclient>=6.7.0 # Apache-2.0 +python-octaviaclient>=1.11.0 # Apache-2.0 +python-troveclient>=3.1.0 # Apache-2.0 +python-watcherclient>=2.5.0 # Apache-2.0 +python-zaqarclient>=1.0.0 # Apache-2.0 +python-zunclient>=3.6.0 # Apache-2.0 diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess new file mode 100644 index 0000000000..8c0a005425 --- /dev/null +++ b/doc/source/_extra/.htaccess @@ -0,0 +1,16 @@ +# Redirect docs from the old to new location following the Great Docs Migration of 2017 + +redirectmatch 301 ^/python-openstackclient/([^/]+)/command-objects/([^/.]+).html$ /python-openstackclient/$1/cli/command-objects/$2.html + +redirectmatch 301 ^/python-openstackclient/([^/]+)/(authentication|backward-incompatible|command-list|commands|decoder|interactive).html$ /python-openstackclient/$1/cli/$2.html +redirectmatch 301 ^/python-openstackclient/([^/]+)/plugin-commands.html$ /python-openstackclient/$1/cli/plugin-commands/index.html + +redirectmatch 301 ^/python-openstackclient/([^/]+)/specs/([^/.]+).html$ /python-openstackclient/$1/contributor/specs/$2.html + +redirectmatch 301 ^/python-openstackclient/([^/]+)/(command-(beta|errors|logs|options|wrappers)|developing|humaninterfaceguide|plugins).html$ /python-openstackclient/$1/contributor/$2.html +redirectmatch 301 ^/python-openstackclient/([^/]+)/cli/plugin-commands.html$ /python-openstackclient/$1/cli/plugin-commands/index.html +# For common subcommand names: +# - identity pages were split into -v2 and -v3 +# - image pages were split into -v1 and -v2 +# The unversioned page is hidden but contains links to the versioned pages so links in the wild redirect somewhere sane. +redirectmatch 301 ^/python-openstackclient/([^/]+)/cli/command-objects/(ec2-credentials|endpoint|image|project|role|service|token|user).html$ /python-openstackclient/$1/cli/_hidden/$2.html diff --git a/doc/source/cli/_hidden/ec2-credentials.rst b/doc/source/cli/_hidden/ec2-credentials.rst new file mode 100644 index 0000000000..c54459d877 --- /dev/null +++ b/doc/source/cli/_hidden/ec2-credentials.rst @@ -0,0 +1,13 @@ +=============== +ec2 credentials +=============== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/ec2-credentials-v2 + ../command-objects/ec2-credentials-v3 diff --git a/doc/source/cli/_hidden/endpoint.rst b/doc/source/cli/_hidden/endpoint.rst new file mode 100644 index 0000000000..744e3badcb --- /dev/null +++ b/doc/source/cli/_hidden/endpoint.rst @@ -0,0 +1,13 @@ +======== +endpoint +======== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/endpoint-v2 + ../command-objects/endpoint-v3 diff --git a/doc/source/cli/_hidden/image.rst b/doc/source/cli/_hidden/image.rst new file mode 100644 index 0000000000..06919e7ab9 --- /dev/null +++ b/doc/source/cli/_hidden/image.rst @@ -0,0 +1,13 @@ +===== +image +===== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously image v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/image-v1 + ../command-objects/image-v2 diff --git a/doc/source/cli/_hidden/project.rst b/doc/source/cli/_hidden/project.rst new file mode 100644 index 0000000000..209a3129df --- /dev/null +++ b/doc/source/cli/_hidden/project.rst @@ -0,0 +1,13 @@ +======= +project +======= + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/project-v2 + ../command-objects/project-v3 diff --git a/doc/source/cli/_hidden/role.rst b/doc/source/cli/_hidden/role.rst new file mode 100644 index 0000000000..c85f48146c --- /dev/null +++ b/doc/source/cli/_hidden/role.rst @@ -0,0 +1,13 @@ +==== +role +==== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/role-v2 + ../command-objects/role-v3 diff --git a/doc/source/cli/_hidden/service.rst b/doc/source/cli/_hidden/service.rst new file mode 100644 index 0000000000..8b33638610 --- /dev/null +++ b/doc/source/cli/_hidden/service.rst @@ -0,0 +1,13 @@ +======= +service +======= + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/service-v2 + ../command-objects/service-v3 diff --git a/doc/source/cli/_hidden/token.rst b/doc/source/cli/_hidden/token.rst new file mode 100644 index 0000000000..6ebf801b76 --- /dev/null +++ b/doc/source/cli/_hidden/token.rst @@ -0,0 +1,13 @@ +===== +token +===== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/token-v2 + ../command-objects/token-v3 diff --git a/doc/source/cli/_hidden/user.rst b/doc/source/cli/_hidden/user.rst new file mode 100644 index 0000000000..34eb59954f --- /dev/null +++ b/doc/source/cli/_hidden/user.rst @@ -0,0 +1,13 @@ +==== +user +==== + +.. NOTE(efried): This page is hidden from the main TOC; it's here so links in + the wild redirect somewhere sane, because previously identity v2 and v3 were + combined in a single page. + +.. toctree:: + :maxdepth: 2 + + ../command-objects/user-v2 + ../command-objects/user-v3 diff --git a/doc/source/cli/authentication.rst b/doc/source/cli/authentication.rst new file mode 100644 index 0000000000..8c09fc3648 --- /dev/null +++ b/doc/source/cli/authentication.rst @@ -0,0 +1,377 @@ +.. _authentication: + +============== +Authentication +============== + +OpenStackClient leverages `python-keystoneclient`_ authentication +plugins to support a number of different authentication methods. + +.. _`python-keystoneclient`: https://docs.openstack.org/python-keystoneclient/latest/using-sessions.html#sharing-authentication-plugins + +Authentication Process +---------------------- + +The user provides some number of authentication credential options. +If an authentication type is not provided (``--os-auth-type``), the +authentication options are examined to determine if one of the default +types can be used. If no match is found an error is reported and OSC exits. + +Note that the authentication call to the Identity service has not yet +occurred. It is deferred until the last possible moment in order to +reduce the number of unnecessary queries to the server, such as when further +processing detects an invalid command. + +Authentication Plugins +---------------------- + +The Keystone client library implements the base set of plugins. Additional +plugins may be available from the Keystone project or other sources. + +There are at least three authentication types that are always available: + +* **Password**: A project, username and password are used to identify the + user. An optional domain may also be included. This is the most common + type and is the default any time a username is supplied. An authentication + URL for the Identity service is also required. [Required: ``--os-auth-url``, + ``--os-project-name``, ``--os-username``; Optional: ``--os-password``] +* **Token**: This is slightly different from the usual token authentication + in that a token and an authentication + URL are supplied and the plugin retrieves a new token. + [Required: ``--os-auth-url``, ``--os-token``] +* **Others**: Other authentication plugins such as SAML, Kerberos, and OAuth1.0 + are under development and also supported. To use them, they must be selected + by supplying the ``--os-auth-type`` option. + +Detailed Process +---------------- + +The authentication process in OpenStackClient is all contained in and handled +by the ``ClientManager`` object. + +* On import ``api.auth``: + + * obtains the list of installed Keystone authentication + plugins from the ``keystoneclient.auth.plugin`` entry point. + * builds a list of authentication options from the plugins. + +* The command line arguments are processed and a configuration is loaded from + :file:`clouds.yaml` if ``--os-cloud`` is provided. + +* A new ``ClientManager`` is created and supplied with the set of options from the + command line, environment and/or :file:`clouds.yaml`: + + * If ``--os-auth-type`` is provided and is a valid and available plugin + it is used. + * If ``--os-auth-type`` is not provided an authentication plugin + is selected based on the existing options. This is a short-circuit + evaluation, the first match wins. + + * If ``--os-username`` is supplied ``password`` is selected + * If ``--os-token`` is supplied ``token`` is selected + * If no selection has been made by now exit with error + + * Load the selected plugin class. + +* When an operation that requires authentication is attempted ``ClientManager`` + makes the actual initial request to the Identity service. + + * if ``--os-auth-url`` is not supplied for any of the types except + Token/Endpoint, exit with an error. + +Authenticating using Identity Server API v3 +------------------------------------------- + +To authenticate against an Identity Server API v3, the +``OS_IDENTITY_API_VERSION`` environment variable or +``--os-identity-api-version`` option must be changed to ``3``, instead of the +default ``2.0``. Similarly ``OS_AUTH_URL`` or ``os-auth-url`` should also be +updated. + +.. code-block:: bash + + $ export OS_IDENTITY_API_VERSION=3 (Defaults to 2.0) + $ export OS_AUTH_URL=http://localhost:5000/v3 + +Since Identity API v3 authentication is a bit more complex, there are additional +options that may be set, either as command line options or environment +variables. The most common case will be a user supplying both user name and +password, along with the project name; previously in v2.0 this would be +sufficient, but since the Identity API v3 has a ``Domain`` component, we need +to tell the client in which domain the user and project exists. + +If using a user name and password to authenticate, specify either it's owning +domain name or ID. + +* ``--os-user-domain-name`` or ``OS_USER_DOMAIN_NAME`` + +* ``--os-user-domain-id`` or ``OS_USER_DOMAIN_ID`` + +If using a project name as authorization scope, specify either it's owning +domain name or ID. + +* ``--os-project-domain-name`` or ``OS_PROJECT_DOMAIN_NAME`` + +* ``--os-project-domain-id`` or ``OS_PROJECT_DOMAIN_ID`` + +If using a domain as authorization scope, set either it's name or ID. + +* ``--os-domain-name`` or ``OS_DOMAIN_NAME`` + +* ``--os-domain-id`` or ``OS_DOMAIN_ID`` + +Note that if the user and project share the same domain, then simply setting +``--os-default-domain`` or ``OS_DEFAULT_DOMAIN`` to the domain ID is sufficient. + +Thus, a minimal set of environment variables would be: + +.. code-block:: bash + + $ export OS_IDENTITY_API_VERSION=3 + $ export OS_AUTH_URL=http://localhost:5000/v3 + $ export OS_DEFAULT_DOMAIN=default + $ export OS_USERNAME=admin + $ export OS_PASSWORD=secret + $ export OS_PROJECT_NAME=admin + +Federated users support +----------------------- + +The OpenStackClient also allows the use of Federated users to log in. +It enables one to use the identity providers credentials such as Google or +Facebook to log in the OpenStackClient instead of using the Keystone +credentials. + +This is useful in a Federated environment where one credential give access +to many applications/services that the Federation supports. To check how to +configure the OpenStackClient to allow Federated users to log in, please check +the :ref:`Authentication using federation. ` + +Examples +-------- + +.. todo: It would be nice to add more examples here, particularly for + complicated things like oauth2 + +``v3password`` +~~~~~~~~~~~~~~ + +Using ``clouds.yaml``: + +.. code-block:: yaml + + clouds: + demo: + auth: + auth_url: http://openstack.dev/identity + project_name: demo + project_domain_name: default + user_domain_name: default + username: demo + password: password + auth_type: v3password + +or, using command line options: + +.. code-block:: bash + + $ openstack \ + --os-auth-url "http://openstack.dev/identity" \ + --os-project-name demo \ + --os-project-domain-name default \ + --os-user-domain-name default \ + --os-auth-type=v3password \ + --os-username demo \ + --os-password password \ + server list + +or, using environment variables: + +.. code-block:: bash + + $ export OS_AUTH_URL="http://openstack.dev/identity" + $ export OS_PROJECT_NAME=demo + $ export OS_PROJECT_DOMAIN_NAME=default + $ export OS_AUTH_TYPE=v3password + $ export OS_USERNAME=demo + $ export OS_PASSWORD=password + $ openstack server list + +.. note:: + + If a password is not provided, you will be prompted for one. + +``v3applicationcredential`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using ``clouds.yaml``: + +.. code-block:: yaml + + clouds: + demo: + auth: + auth_url: http://openstack.dev/identity + application_credential_id: ${APP_CRED_ID} + application_credential_secret: ${APP_CRED_SECRET} + auth_type: v3applicationcredential + +or, using command line options: + +.. code-block:: bash + + $ openstack \ + --os-auth-url "http://openstack.dev/identity" \ + --os-auth-type=v3applicationcredential \ + --os-application-credential-id=${APP_CRED_ID} \ + --os-application-credential-secret=${APP_CRED_SECRET} + server list + +or, using environment variables: + +.. code-block:: bash + + $ export OS_AUTH_URL="http://openstack.dev/identity" + $ export OS_AUTH_TYPE=v3applicationcredential + $ export OS_APPLICATION_CREDENTIAL_ID=${APP_CRED_ID} + $ export OS_APPLICATION_CREDENTIAL_SECRET=${APP_CRED_SECRET} + $ openstack server list + +.. note:: + + You can generate application credentials using the :program:`openstack + application credential create` command: + + .. code-block:: bash + + $ readarray -t lines <<< $(openstack application credential create test -f value -c id -c secret) + $ APP_CRED_ID=${lines[0]} + $ APP_CRED_SECRET=${lines[1]} + +``v3token`` +~~~~~~~~~~~ + +Using ``clouds.yaml``: + +.. code-block:: yaml + + clouds: + demo: + auth: + auth_url: http://openstack.dev/identity + project_name: demo + project_domain_name: default + token: ${TOKEN} + auth_type: v3token + +or, using command line options: + +.. code-block:: bash + + $ openstack \ + --os-auth-url "http://openstack.dev/identity" \ + --os-project-name demo \ + --os-project-domain-name default \ + --os-auth-type=v3token \ + --os-token ${TOKEN} \ + server list + +or, using environment variables: + +.. code-block:: bash + + $ export OS_AUTH_URL="http://openstack.dev/identity" + $ export OS_PROJECT_NAME=demo + $ export OS_PROJECT_DOMAIN_NAME=default + $ export OS_AUTH_TYPE=v3token + $ export OS_TOKEN=${TOKEN} + $ openstack server list + +.. note:: + + You can generate tokens using the :program:`openstack token issue` command: + + .. code-block:: bash + + $ TOKEN=$(openstack token issue -f value -c id) + +.. note:: + + The above examples assume you require a project-scoped token. You can omit + the project-related configuration if your user has a default project ID set. + Conversely, if requesting domain-scoped or system-scoped, you should update + these examples accordingly. If the user does not have a default project + configured and no scoping information is provided, the resulting token will + be unscoped. + +``v3totp`` +~~~~~~~~~~ + +.. note:: + + The TOTP mechanism is poorly suited to command line-driven API + interactions. Where the TOTP mechanism is configured for a cloud, it is + expected that it is to be used for initial authentication and to create a + token or application credential, which can then be used for future + interactions. + +.. note:: + + The TOTP mechanism is often combined with other mechanisms to enable + Multi-Factor Authentication, or MFA. The authentication type + ``v3multifactor`` is used in this case, while the ``v3totp`` authentication + type is specified alongside the other mechanisms in ``auth_methods``. + +Using ``clouds.yaml``: + +.. code-block:: yaml + + clouds: + demo: + auth: + auth_url: http://openstack.dev/identity + project_name: demo + project_domain_name: default + user_domain_name: default + username: demo + passcode: ${PASSCODE} + auth_type: v3totp + +or, using command line options: + +.. code-block:: bash + + $ openstack \ + --os-auth-url "http://openstack.dev/identity" \ + --os-project-name demo \ + --os-project-domain-name default \ + --os-user-domain-name default \ + --os-auth-type=v3totp \ + --os-username demo \ + --os-passcode ${PASSCODE} \ + server list + +or, using environment variables: + +.. code-block:: bash + + $ export OS_AUTH_URL="http://openstack.dev/identity" + $ export OS_PROJECT_NAME=demo + $ export OS_PROJECT_DOMAIN_NAME=default + $ export OS_AUTH_TYPE=v3totp + $ export OS_USERNAME=demo + $ export OS_PASSCODE=${PASSCODE} + $ openstack server list + +.. note:: + + The passcode will be generated by an authenticator application such FreeOTP + or Google Authenticator. Refer to your cloud provider's documentation for + information on how to configure an authenticator application, or to the + `Keystone documentation`__ if you are configuring this for your own cloud. + + .. __: https://docs.openstack.org/keystone/latest/admin/auth-totp.html + +.. note:: + + If a passcode is not provided, you will be prompted for one. diff --git a/doc/source/cli/backwards-incompatible.rst b/doc/source/cli/backwards-incompatible.rst new file mode 100644 index 0000000000..3fbe65fae9 --- /dev/null +++ b/doc/source/cli/backwards-incompatible.rst @@ -0,0 +1,392 @@ +============================== +Backwards Incompatible Changes +============================== + +Despite our best efforts, sometimes the OpenStackClient team may introduce a +backwards incompatible change. For user convenience we are tracking any such +changes here (as of the 1.0.0 release). + +Should positional arguments for a command need to change, the OpenStackClient +team attempts to make the transition as painless as possible. Look for +deprecation warnings that indicate the new commands (or options) to use. + +Commands labeled as a beta according to :ref:`command-beta` are exempt +from this backwards incompatible change handling. + +Backwards Incompatible Changes +============================== + +Release 4.0 +----------- + +1. Remove ``ip fixed add|remove`` commands. + + Use ``server add|remove fixed ip`` commands instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612781 + +2. Remove ``ip floating add|remove`` commands. + + Use ``server add|remove floating ip`` commands instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612781 + +3. Remove ``service create`` option ``--type``. Service type is + a positional argument. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612798 + +4. Remove ``role list`` options ``--project`` and ``--user``. + + Use ``role assignment list`` options ``--project`` and ``--user`` instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612798 + +5. Remove ``user role list`` command. + + Use ``role assignment list`` options ``--project`` and ``--user`` instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612798 + +6. Remove ``image create|set`` option ``--owner``. + + Use ``--project`` option instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/659431 + +7. Remove ``port create|set`` options ``--device-id`` and ``--host-id``. + + Use ``--device`` and ``--host`` instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/613644 + +8. Remove ``router set`` option ``--clear-routes``. + + Use ``no-route`` option instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/613644 + +9. Remove ``security group rule create`` options ``--src-ip`` and ``--src-group``. + + Use ``--remote-ip`` and ``--remote-group`` options instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/613644 + +10. Remove ``backup`` commands. + + Use ``volume backup`` commands instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612751 + +11. Remove ``snapshot`` commands. + Use ``volume snapshot`` commands instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612751 + +12. Remove ``volume create`` options ``--project``, ``--user``, ``--multi-attach``. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612751 + +13. Change ``volume transfer request accept`` to use new option ``--auth-key`` + rather than a second positional argument. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/612751 + +14. Remove 'Token/Endpoint' auth plugin support (type ``token_endpoint``). + + This remained as a compatibility for the ``admin_token`` auth type to + support the ``--url`` global option. That option is also now removed, + use ``--endpoint`` instead. + + * Removed in: 4.0 + * Commit: https://review.opendev.org/ + +Release 3.12 +------------ + +1. Replace ``Display Name`` by ``Name`` in volume list. + + Change column name ``Display Name`` to ``Name`` in ``volume list`` output. + Current ``volume list --name`` command uses ``display_name`` as search_opts + to send to cinder API, and show the result table with ``Display Name`` + as column title. Replace all ``Display Name`` by ``Name`` to be consistent + with other list commands. + + Support a mapping for volume list -c ``Display Name`` (Volume v1 and v2) + and volume create/show -c ``display_name`` (Volume v1) to maintain backward + compatibility until the next major release. + + * In favor of: ``openstack volume list -c Name`` + * As of: 3.12.0 + * Removed in: n/a + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1657956 + * Commit: https://review.opendev.org/#/c/423081/ + +Release 3.10 +------------ + +1. The ``network create`` command now requires the ``--subnet`` option when used + with nova-network clouds. + + * As of: 3.10 + * Commit: https://review.opendev.org/460679 + +2. The positional argument ```` of the ``volume snapshot create`` + command is no longer optional. + + Previously when the ``--volume`` option was + present ```` defaulted to the ``--volume`` value. When the + ``--volume`` option is not present now it defaults to the value of + ````. + + * As of: 3.10 + * Bug: 1659894 + * Commit: https://review.opendev.org/440497 + +Release 3.0 +----------- + +1. Remove the ``osc_password`` authentication plugin. + + This was the 'last-resort' plugin default that worked around an old default + Keystone configuration for the ``admin_endpoint`` and ``public_endpoint``. + + * In favor of: ``password`` + * As of: 3.0 + * Removed in: n/a + * Bug: n/a + * Commit: https://review.opendev.org/332938 + + +Releases Before 3.0 +------------------- + +1. Rename command `openstack project usage list` + + The `project` part of the command was pointless. + + * In favor of: `openstack usage list` instead. + * As of: 1.0.2 + * Removed in: TBD + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1406654 + * Commit: https://review.opendev.org/#/c/147379/ + +2. should not be optional for command `openstack service create` + + Previously, the command was `openstack service create --type `, + whereas now it is: `openstack service create --name `. + This bug also affected python-keystoneclient, and keystone. + + * In favor of: making a positional argument. + * As of: 1.0.2 + * Removed in: TBD + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1404073 + * Commit: https://review.opendev.org/#/c/143242/ + +3. Command `openstack security group rule delete` now requires rule id + + Previously, the command was `openstack security group rule delete --proto + [--src-ip --dst-port ] `, + whereas now it is: `openstack security group rule delete `. + + * In favor of: Using `openstack security group rule delete `. + * As of: 1.2.1 + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1450872 + * Commit: https://review.opendev.org/#/c/179446/ + +4. Command `openstack image create` does not update already existing image + + Previously, the image create command updated already existing image if it had + same name. It disabled possibility to create multiple images with same name + and lead to potentially unwanted update of existing images by image create + command. + Now, update code was moved from create action to set action. + + * In favor of: Create multiple images with same name (as glance does). + * As of: 1.5.0 + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1461817 + * Commit: https://review.opendev.org/#/c/194654/ + +5. Command `openstack network list --dhcp` has been removed + + The --dhcp option to network list is not a logical use case of listing + networks, it lists agents. Another command should be added in the future + to provide this functionality. It is highly unlikely anyone uses this + feature as we don't support any other agent commands. Use neutron + dhcp-agent-list-hosting-net command instead. + + * In favor of: Create network agent list command in the future + * As of: 1.6.0 + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/472613 + * Commit: https://review.opendev.org/#/c/194654/ + +6. Plugin interface change for default API versions + + Previously, the default version was set in the parsed arguments, + but this makes it impossible to tell what has been passed in at the + command line, set in an environment variable or is just the default. + Now, the module should have a DEFAULT_API_VERSION that contains the + value and it will be set after command line argument, environment + and OCC file processing. + + * In favor of: DEFAULT_API_VERSION + * As of: 1.2.1 + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1453229 + * Commit: https://review.opendev.org/#/c/181514/ + +7. `image set` commands will no longer return the modified resource + + Previously, modifying an image would result in the new image being displayed + to the user. To keep things consistent with other `set` commands, we will + no longer be showing the modified resource. + + * In favor of: Use `set` then `show` + * As of: NA + * Removed in: NA + * Bug: NA + * Commit: NA + +8. `region` commands no longer support `url` + + The Keystone team removed support for the `url` attribute from the client + and server side. Changes to the `create`, `set` and `list` commands for + regions have been affected. + + * In favor of: NA + * As of 1.9.0 + * Removed in: NA + * Bug: https://launchpad.net/bugs/1506841 + * Commit: https://review.opendev.org/#/c/236736/ + +9. `flavor set/unset` commands will no longer return the modified resource + + Previously, modifying a flavor would result in the new flavor being displayed + to the user. To keep things consistent with other `set/unset` commands, we + will no longer be showing the modified resource. + + * In favor of: Use `set/unset` then `show` + * As of: NA + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 + * Commit: https://review.opendev.org/#/c/280663/ + +10. `security group set` commands will no longer return the modified resource + + Previously, modifying a security group would result in the new security group + being displayed to the user. To keep things consistent with other `set` + commands, we will no longer be showing the modified resource. + + * In favor of: Use `set` then `show` + * As of: NA + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 + * Commit: https://review.opendev.org/#/c/281087/ + +11. `compute agent set` commands will no longer return the modified resource + + Previously, modifying an agent would result in the new agent being displayed + to the user. To keep things consistent with other `set` commands, we will + no longer be showing the modified resource. + + * In favor of: Use `set` then `show` + * As of: NA + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 + * Commit: https://review.opendev.org/#/c/281088/ + +12. ` ` should be optional for command `openstack + compute agent set` + + Previously, the command was `openstack compute agent set + `, whereas now it is: `openstack compute agent set --version + --url --md5hash `. + + * In favor of: making optional. + * As of: NA + * Removed in: NA + * Bug: NA + * Commit: https://review.opendev.org/#/c/328819/ + +13. `aggregate set` commands will no longer return the modified resource + + Previously, modifying an aggregate would result in the new aggregate being + displayed to the user. To keep things consistent with other `set` commands, + we will no longer be showing the modified resource. + + * In favor of: Use `set` then `show` + * As of: NA + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1546065 + * Commit: https://review.opendev.org/#/c/281089/ + +14. Output of `ip floating list` command has changed. + + When using Compute v2, the original output is: + + .. code-block:: bash + + # ip floating list + + +----+--------+------------+----------+-------------+ + | ID | Pool | IP | Fixed IP | Instance ID | + +----+--------+-----------------------+-------------+ + | 1 | public | 172.24.4.1 | None | None | + +----+--------+------------+----------+-------------+ + + Now it changes to: + + .. code-block:: bash + + # ip floating list + + +----+---------------------+------------------+-----------+--------+ + | ID | Floating IP Address | Fixed IP Address | Server ID | Pool | + +----+---------------------+------------------+-----------+--------+ + | 1 | 172.24.4.1 | None | None | public | + +----+---------------------+------------------+-----------+--------+ + + When using Network v2, which is different from Compute v2. The output is: + + .. code-block:: bash + + # ip floating list + + +--------------------------------------+---------------------+------------------+------+ + | ID | Floating IP Address | Fixed IP Address | Port | + +--------------------------------------+---------------------+------------------+------+ + | 1976df86-e66a-4f96-81bd-c6ffee6407f1 | 172.24.4.3 | None | None | + +--------------------------------------+---------------------+------------------+------+ + + * In favor of: Use `ip floating list` command + * As of: NA + * Removed in: NA + * Bug: https://bugs.launchpad.net/python-openstackclient/+bug/1519502 + * Commit: https://review.opendev.org/#/c/277720/ + +For Developers +============== + +If introducing a backwards incompatible change, then add the tag: +``BackwardsIncompatibleImpact`` to your git commit message, and if possible, +update this file. + +To review all changes that are affected, use the following query: + +https://review.opendev.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z diff --git a/doc/source/cli/command-list.rst b/doc/source/cli/command-list.rst new file mode 100644 index 0000000000..9044f69389 --- /dev/null +++ b/doc/source/cli/command-list.rst @@ -0,0 +1,11 @@ +.. _command-list: + +============ +Command List +============ + +.. toctree:: + :glob: + :maxdepth: 2 + + command-objects/* diff --git a/doc/source/cli/command-objects/access-rules.rst b/doc/source/cli/command-objects/access-rules.rst new file mode 100644 index 0000000000..6e811fc7df --- /dev/null +++ b/doc/source/cli/command-objects/access-rules.rst @@ -0,0 +1,19 @@ +=========== +access rule +=========== + +Identity v3 + +Access rules are fine-grained permissions for application credentials. An access +rule comprises of a service type, a request path, and a request method. Access +rules may only be created as attributes of application credentials, but they may +be viewed and deleted independently. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: access rule delete + +.. autoprogram-cliff:: openstack.identity.v3 + :command: access rule list + +.. autoprogram-cliff:: openstack.identity.v3 + :command: access rule show diff --git a/doc/source/cli/command-objects/access-token.rst b/doc/source/cli/command-objects/access-token.rst new file mode 100644 index 0000000000..7ef9167eb3 --- /dev/null +++ b/doc/source/cli/command-objects/access-token.rst @@ -0,0 +1,10 @@ +============ +access token +============ + +An **access token** is used by the Identity service's OS-OAUTH1 extension. It +is used by the **consumer** to request new Identity API tokens on behalf of the +authorizing **user**. Applicable to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: access token create diff --git a/doc/source/cli/command-objects/address-group.rst b/doc/source/cli/command-objects/address-group.rst new file mode 100644 index 0000000000..c1ff6f8858 --- /dev/null +++ b/doc/source/cli/command-objects/address-group.rst @@ -0,0 +1,12 @@ +============= +address group +============= + +An **address group** is a group of IPv4 or IPv6 address blocks which could be +referenced as a remote source or destination when creating a security group +rule. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: address group * diff --git a/doc/source/cli/command-objects/address-scope.rst b/doc/source/cli/command-objects/address-scope.rst new file mode 100644 index 0000000000..38141d5c97 --- /dev/null +++ b/doc/source/cli/command-objects/address-scope.rst @@ -0,0 +1,11 @@ +============= +address scope +============= + +An **address scope** is a scope of IPv4 or IPv6 addresses that belongs +to a given project and may be shared between projects. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: address scope * diff --git a/doc/source/cli/command-objects/aggregate.rst b/doc/source/cli/command-objects/aggregate.rst new file mode 100644 index 0000000000..0f62ce8f43 --- /dev/null +++ b/doc/source/cli/command-objects/aggregate.rst @@ -0,0 +1,11 @@ +========= +aggregate +========= + +Host aggregates provide a mechanism to group hosts according to certain +criteria. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: aggregate * diff --git a/doc/source/cli/command-objects/application-credentials.rst b/doc/source/cli/command-objects/application-credentials.rst new file mode 100644 index 0000000000..cef3ef0dfc --- /dev/null +++ b/doc/source/cli/command-objects/application-credentials.rst @@ -0,0 +1,13 @@ +====================== +application credential +====================== + +Identity v3 + +With application credentials, a user can grant their applications limited +access to their cloud resources. Once created, users can authenticate with an +application credential by using the ``v3applicationcredential`` auth type. + + +.. autoprogram-cliff:: openstack.identity.v3 + :command: application credential * diff --git a/doc/source/cli/command-objects/availability-zone.rst b/doc/source/cli/command-objects/availability-zone.rst new file mode 100644 index 0000000000..bdc64f1537 --- /dev/null +++ b/doc/source/cli/command-objects/availability-zone.rst @@ -0,0 +1,11 @@ +================= +availability zone +================= + +An **availability zone** is a logical partition of cloud block storage, +compute and network services. + +Block Storage v2, Compute v2, Network v2 + +.. autoprogram-cliff:: openstack.common + :command: availability zone list diff --git a/doc/source/cli/command-objects/block-storage-cleanup.rst b/doc/source/cli/command-objects/block-storage-cleanup.rst new file mode 100644 index 0000000000..6a593c1187 --- /dev/null +++ b/doc/source/cli/command-objects/block-storage-cleanup.rst @@ -0,0 +1,8 @@ +============= +block storage +============= + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage cleanup diff --git a/doc/source/cli/command-objects/block-storage-cluster.rst b/doc/source/cli/command-objects/block-storage-cluster.rst new file mode 100644 index 0000000000..318419e079 --- /dev/null +++ b/doc/source/cli/command-objects/block-storage-cluster.rst @@ -0,0 +1,8 @@ +===================== +block storage cluster +===================== + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage cluster * diff --git a/doc/source/cli/command-objects/block-storage-log-level.rst b/doc/source/cli/command-objects/block-storage-log-level.rst new file mode 100644 index 0000000000..17241a0edf --- /dev/null +++ b/doc/source/cli/command-objects/block-storage-log-level.rst @@ -0,0 +1,8 @@ +======================= +Block Storage Log Level +======================= + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage log level * diff --git a/doc/source/cli/command-objects/block-storage-manage.rst b/doc/source/cli/command-objects/block-storage-manage.rst new file mode 100644 index 0000000000..a1cff1ad67 --- /dev/null +++ b/doc/source/cli/command-objects/block-storage-manage.rst @@ -0,0 +1,11 @@ +==================== +Block Storage Manage +==================== + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage volume manageable list + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage snapshot manageable list diff --git a/doc/source/cli/command-objects/block-storage-resource-filter.rst b/doc/source/cli/command-objects/block-storage-resource-filter.rst new file mode 100644 index 0000000000..3e4c33ba5f --- /dev/null +++ b/doc/source/cli/command-objects/block-storage-resource-filter.rst @@ -0,0 +1,8 @@ +============================= +block storage resource filter +============================= + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: block storage resource filter * diff --git a/doc/source/cli/command-objects/catalog.rst b/doc/source/cli/command-objects/catalog.rst new file mode 100644 index 0000000000..84cd160a0b --- /dev/null +++ b/doc/source/cli/command-objects/catalog.rst @@ -0,0 +1,9 @@ +======= +catalog +======= + +A **catalog** lists OpenStack services that are available on the cloud. +Applicable to Identity v2 and v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: catalog * diff --git a/doc/source/cli/command-objects/command.rst b/doc/source/cli/command-objects/command.rst new file mode 100644 index 0000000000..5afc4940ab --- /dev/null +++ b/doc/source/cli/command-objects/command.rst @@ -0,0 +1,10 @@ +======= +command +======= + +Internal + +Installed commands in the OSC process. + +.. autoprogram-cliff:: openstack.cli + :command: command * diff --git a/doc/source/cli/command-objects/complete.rst b/doc/source/cli/command-objects/complete.rst new file mode 100644 index 0000000000..165d5d07d5 --- /dev/null +++ b/doc/source/cli/command-objects/complete.rst @@ -0,0 +1,28 @@ +======== +complete +======== + +The ``complete`` command is inherited from the `python-cliff` library, it can +be used to generate a bash-completion script. Currently, the command will +generate a script for bash versions 3 or 4. The bash-completion script is +printed directly to standard out. + +Typical usage for this command is:: + + openstack complete | sudo tee /etc/bash_completion.d/osc.bash_completion > /dev/null + +It is highly recommended to install ``python-openstackclient`` from a package +(``apt-get`` or ``yum``). In some distributions the package ``bash-completion`` is shipped +as dependency, and the `openstack complete` command will be run as a post-install action, +however not every distribution include this dependency and you might need to install +``bash-completion`` package to enable autocomplete feature. + +complete +-------- + +print bash completion command + +.. program:: complete +.. code:: bash + + openstack complete diff --git a/doc/source/cli/command-objects/compute-agent.rst b/doc/source/cli/command-objects/compute-agent.rst new file mode 100644 index 0000000000..89d7492879 --- /dev/null +++ b/doc/source/cli/command-objects/compute-agent.rst @@ -0,0 +1,8 @@ +============= +compute agent +============= + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: compute agent * diff --git a/doc/source/cli/command-objects/compute-service.rst b/doc/source/cli/command-objects/compute-service.rst new file mode 100644 index 0000000000..ac54786e5b --- /dev/null +++ b/doc/source/cli/command-objects/compute-service.rst @@ -0,0 +1,8 @@ +=============== +compute service +=============== + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: compute service * diff --git a/doc/source/cli/command-objects/configuration.rst b/doc/source/cli/command-objects/configuration.rst new file mode 100644 index 0000000000..22fd13e43d --- /dev/null +++ b/doc/source/cli/command-objects/configuration.rst @@ -0,0 +1,10 @@ +============= +configuration +============= + +Available for all services + +.. _configuration-show: + +.. autoprogram-cliff:: openstack.common + :command: configuration show diff --git a/doc/source/cli/command-objects/consistency-group-snapshot.rst b/doc/source/cli/command-objects/consistency-group-snapshot.rst new file mode 100644 index 0000000000..51241685fd --- /dev/null +++ b/doc/source/cli/command-objects/consistency-group-snapshot.rst @@ -0,0 +1,17 @@ +========================== +consistency group snapshot +========================== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group snapshot create + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group snapshot delete + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group snapshot list + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group snapshot show diff --git a/doc/source/cli/command-objects/consistency-group.rst b/doc/source/cli/command-objects/consistency-group.rst new file mode 100644 index 0000000000..9ff207ff79 --- /dev/null +++ b/doc/source/cli/command-objects/consistency-group.rst @@ -0,0 +1,26 @@ +================= +consistency group +================= + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group add volume + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group create + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group delete + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group list + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group remove volume + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group set + +.. autoprogram-cliff:: openstack.volume.v3 + :command: consistency group show diff --git a/doc/source/cli/command-objects/console-connection.rst b/doc/source/cli/command-objects/console-connection.rst new file mode 100644 index 0000000000..c3358050fb --- /dev/null +++ b/doc/source/cli/command-objects/console-connection.rst @@ -0,0 +1,10 @@ +================== +console connection +================== + +Server console connection information + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: console connection show diff --git a/doc/source/cli/command-objects/console-log.rst b/doc/source/cli/command-objects/console-log.rst new file mode 100644 index 0000000000..46ef370d84 --- /dev/null +++ b/doc/source/cli/command-objects/console-log.rst @@ -0,0 +1,10 @@ +=========== +console log +=========== + +Server console text dump + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: console log * diff --git a/doc/source/cli/command-objects/console-url.rst b/doc/source/cli/command-objects/console-url.rst new file mode 100644 index 0000000000..001ccc56c7 --- /dev/null +++ b/doc/source/cli/command-objects/console-url.rst @@ -0,0 +1,10 @@ +=========== +console url +=========== + +Server remote console URL + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: console url * diff --git a/doc/source/cli/command-objects/consumer.rst b/doc/source/cli/command-objects/consumer.rst new file mode 100644 index 0000000000..17cfc0c996 --- /dev/null +++ b/doc/source/cli/command-objects/consumer.rst @@ -0,0 +1,10 @@ +======== +consumer +======== + +An **consumer** is used by the Identity service's OS-OAUTH1 extension. It +is used to create a **request token** and **access token**. Applicable to +Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: consumer * diff --git a/doc/source/cli/command-objects/container.rst b/doc/source/cli/command-objects/container.rst new file mode 100644 index 0000000000..83deeb8156 --- /dev/null +++ b/doc/source/cli/command-objects/container.rst @@ -0,0 +1,26 @@ +========= +container +========= + +A **container** defines a namespace for **objects**. Applies to Object Storage v1 + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container create + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container delete + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container list + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container save + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container set + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container show + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: container unset diff --git a/doc/source/cli/command-objects/credential.rst b/doc/source/cli/command-objects/credential.rst new file mode 100644 index 0000000000..f490f1cfee --- /dev/null +++ b/doc/source/cli/command-objects/credential.rst @@ -0,0 +1,8 @@ +========== +credential +========== + +Identity v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: credential * diff --git a/doc/source/cli/command-objects/default-security-group-rule.rst b/doc/source/cli/command-objects/default-security-group-rule.rst new file mode 100644 index 0000000000..1905614bfc --- /dev/null +++ b/doc/source/cli/command-objects/default-security-group-rule.rst @@ -0,0 +1,11 @@ +=========================== +default security group rule +=========================== + +A **default security group rule** specifies the template of the security group +rules which will be used by neutron to create rules in every new security group. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: default security group rule * diff --git a/doc/source/cli/command-objects/domain.rst b/doc/source/cli/command-objects/domain.rst new file mode 100644 index 0000000000..81a193497b --- /dev/null +++ b/doc/source/cli/command-objects/domain.rst @@ -0,0 +1,22 @@ +====== +domain +====== + +A **domain** is a collection of **users**, **groups**, and **projects**. Each +**group** and **project** is owned by exactly one **domain**. Applies to +Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: domain create + +.. autoprogram-cliff:: openstack.identity.v3 + :command: domain delete + +.. autoprogram-cliff:: openstack.identity.v3 + :command: domain list + +.. autoprogram-cliff:: openstack.identity.v3 + :command: domain set + +.. autoprogram-cliff:: openstack.identity.v3 + :command: domain show diff --git a/doc/source/cli/command-objects/ec2-credentials-v2.rst b/doc/source/cli/command-objects/ec2-credentials-v2.rst new file mode 100644 index 0000000000..ace3d84ec5 --- /dev/null +++ b/doc/source/cli/command-objects/ec2-credentials-v2.rst @@ -0,0 +1,6 @@ +============================= +ec2 credentials (Identity v2) +============================= + +.. autoprogram-cliff:: openstack.identity.v2 + :command: ec2 credentials * diff --git a/doc/source/cli/command-objects/ec2-credentials-v3.rst b/doc/source/cli/command-objects/ec2-credentials-v3.rst new file mode 100644 index 0000000000..761d428050 --- /dev/null +++ b/doc/source/cli/command-objects/ec2-credentials-v3.rst @@ -0,0 +1,6 @@ +============================= +ec2 credentials (Identity v3) +============================= + +.. autoprogram-cliff:: openstack.identity.v3 + :command: ec2 credentials * diff --git a/doc/source/cli/command-objects/endpoint-v2.rst b/doc/source/cli/command-objects/endpoint-v2.rst new file mode 100644 index 0000000000..7badfd4080 --- /dev/null +++ b/doc/source/cli/command-objects/endpoint-v2.rst @@ -0,0 +1,6 @@ +====================== +endpoint (Identity v2) +====================== + +.. autoprogram-cliff:: openstack.identity.v2 + :command: endpoint * diff --git a/doc/source/cli/command-objects/endpoint-v3.rst b/doc/source/cli/command-objects/endpoint-v3.rst new file mode 100644 index 0000000000..f12063fb0c --- /dev/null +++ b/doc/source/cli/command-objects/endpoint-v3.rst @@ -0,0 +1,24 @@ +====================== +endpoint (Identity v3) +====================== + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint add project + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint create + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint delete + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint list + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint remove project + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint set + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint show diff --git a/doc/source/cli/command-objects/endpoint_group.rst b/doc/source/cli/command-objects/endpoint_group.rst new file mode 100644 index 0000000000..b0d988e17c --- /dev/null +++ b/doc/source/cli/command-objects/endpoint_group.rst @@ -0,0 +1,10 @@ +============== +endpoint group +============== + +A **endpoint group** is used to create groups of endpoints that then +can be used to filter the endpoints that are available to a project. +Applicable to Identity v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: endpoint group * diff --git a/doc/source/cli/command-objects/extension.rst b/doc/source/cli/command-objects/extension.rst new file mode 100644 index 0000000000..1002a5fff0 --- /dev/null +++ b/doc/source/cli/command-objects/extension.rst @@ -0,0 +1,10 @@ +========= +extension +========= + +Many OpenStack server APIs include API extensions that enable +additional functionality. + + +.. autoprogram-cliff:: openstack.common + :command: extension * diff --git a/doc/source/cli/command-objects/federation-domain-project.rst b/doc/source/cli/command-objects/federation-domain-project.rst new file mode 100644 index 0000000000..68db5705b0 --- /dev/null +++ b/doc/source/cli/command-objects/federation-domain-project.rst @@ -0,0 +1,11 @@ +========================= +federation domain/project +========================= + +Identity v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: federation domain * + +.. autoprogram-cliff:: openstack.identity.v3 + :command: federation project * diff --git a/doc/source/cli/command-objects/federation-protocol.rst b/doc/source/cli/command-objects/federation-protocol.rst new file mode 100644 index 0000000000..81b3f9fcd3 --- /dev/null +++ b/doc/source/cli/command-objects/federation-protocol.rst @@ -0,0 +1,10 @@ +=================== +federation protocol +=================== + +A **federation protocol** is used by the Identity service's OS-FEDERATION +extension. It is used by **identity providers** and **mappings**. Applicable to +Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: federation protocol * diff --git a/doc/source/cli/command-objects/flavor.rst b/doc/source/cli/command-objects/flavor.rst new file mode 100644 index 0000000000..ee09b3ace7 --- /dev/null +++ b/doc/source/cli/command-objects/flavor.rst @@ -0,0 +1,8 @@ +====== +flavor +====== + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: flavor * diff --git a/doc/source/cli/command-objects/floating-ip-pool.rst b/doc/source/cli/command-objects/floating-ip-pool.rst new file mode 100644 index 0000000000..ab6f83a993 --- /dev/null +++ b/doc/source/cli/command-objects/floating-ip-pool.rst @@ -0,0 +1,8 @@ +================ +floating ip pool +================ + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip pool * diff --git a/doc/source/cli/command-objects/floating-ip-port-forwarding.rst b/doc/source/cli/command-objects/floating-ip-port-forwarding.rst new file mode 100644 index 0000000000..052ea0cc7f --- /dev/null +++ b/doc/source/cli/command-objects/floating-ip-port-forwarding.rst @@ -0,0 +1,9 @@ +=========================== +floating ip port forwarding +=========================== + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip port forwarding * + diff --git a/doc/source/cli/command-objects/floating-ip.rst b/doc/source/cli/command-objects/floating-ip.rst new file mode 100644 index 0000000000..c781a1edb4 --- /dev/null +++ b/doc/source/cli/command-objects/floating-ip.rst @@ -0,0 +1,26 @@ +=========== +floating ip +=========== + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'floating ip' pulls in + ... pool and ... port forwarding. + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip create + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip list + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip set + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip show + +.. autoprogram-cliff:: openstack.network.v2 + :command: floating ip unset diff --git a/doc/source/cli/command-objects/group.rst b/doc/source/cli/command-objects/group.rst new file mode 100644 index 0000000000..a1071069db --- /dev/null +++ b/doc/source/cli/command-objects/group.rst @@ -0,0 +1,8 @@ +===== +group +===== + +Identity v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: group * diff --git a/doc/source/cli/command-objects/host.rst b/doc/source/cli/command-objects/host.rst new file mode 100644 index 0000000000..acd5a287fe --- /dev/null +++ b/doc/source/cli/command-objects/host.rst @@ -0,0 +1,10 @@ +==== +host +==== + +Compute v2 + +The physical computer running a hypervisor. + +.. autoprogram-cliff:: openstack.compute.v2 + :command: host * diff --git a/doc/source/cli/command-objects/hypervisor-stats.rst b/doc/source/cli/command-objects/hypervisor-stats.rst new file mode 100644 index 0000000000..1f5768f298 --- /dev/null +++ b/doc/source/cli/command-objects/hypervisor-stats.rst @@ -0,0 +1,8 @@ +================ +hypervisor stats +================ + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: hypervisor stats * diff --git a/doc/source/cli/command-objects/hypervisor.rst b/doc/source/cli/command-objects/hypervisor.rst new file mode 100644 index 0000000000..9ae82bf122 --- /dev/null +++ b/doc/source/cli/command-objects/hypervisor.rst @@ -0,0 +1,14 @@ +========== +hypervisor +========== + +Compute v2 + +.. NOTE(efried): have to list these out one by one; 'hypervisor *' pulls in + ... stats. + +.. autoprogram-cliff:: openstack.compute.v2 + :command: hypervisor list + +.. autoprogram-cliff:: openstack.compute.v2 + :command: hypervisor show diff --git a/doc/source/cli/command-objects/identity-provider.rst b/doc/source/cli/command-objects/identity-provider.rst new file mode 100644 index 0000000000..ed85cb7ac8 --- /dev/null +++ b/doc/source/cli/command-objects/identity-provider.rst @@ -0,0 +1,10 @@ +================= +identity provider +================= + +An **identity provider** is used by the Identity service's OS-FEDERATION +extension. It is used by **federation protocols** and **mappings**. Applicable +to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: identity provider * diff --git a/doc/source/cli/command-objects/image-member.rst b/doc/source/cli/command-objects/image-member.rst new file mode 100644 index 0000000000..4b48991cb3 --- /dev/null +++ b/doc/source/cli/command-objects/image-member.rst @@ -0,0 +1,14 @@ +============ +image member +============ + +Image v2 + +.. autoprogram-cliff:: openstack.image.v2 + :command: image add project + +.. autoprogram-cliff:: openstack.image.v2 + :command: image remove project + +.. autoprogram-cliff:: openstack.image.v2 + :command: image member list diff --git a/doc/source/cli/command-objects/image-metadef.rst b/doc/source/cli/command-objects/image-metadef.rst new file mode 100644 index 0000000000..ed36d95f75 --- /dev/null +++ b/doc/source/cli/command-objects/image-metadef.rst @@ -0,0 +1,50 @@ +============= +image metadef +============= + +Image v2 + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef namespace create + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef namespace delete + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef namespace list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef namespace set + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef namespace show + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef resource type list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object create + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object show + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object delete + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object update + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef object property show + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef property create + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef property list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image metadef property show diff --git a/doc/source/cli/command-objects/image-task.rst b/doc/source/cli/command-objects/image-task.rst new file mode 100644 index 0000000000..0021192042 --- /dev/null +++ b/doc/source/cli/command-objects/image-task.rst @@ -0,0 +1,11 @@ +========== +image task +========== + +Image v2 + +.. autoprogram-cliff:: openstack.image.v2 + :command: image task list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image task show diff --git a/doc/source/cli/command-objects/image-v1.rst b/doc/source/cli/command-objects/image-v1.rst new file mode 100644 index 0000000000..4f7edc4322 --- /dev/null +++ b/doc/source/cli/command-objects/image-v1.rst @@ -0,0 +1,6 @@ +======== +image v1 +======== + +.. autoprogram-cliff:: openstack.image.v1 + :command: image * diff --git a/doc/source/cli/command-objects/image-v2.rst b/doc/source/cli/command-objects/image-v2.rst new file mode 100644 index 0000000000..4a2a4d0f90 --- /dev/null +++ b/doc/source/cli/command-objects/image-v2.rst @@ -0,0 +1,32 @@ +===== +image +===== + +Image v2 + +.. autoprogram-cliff:: openstack.image.v2 + :command: image create + +.. autoprogram-cliff:: openstack.image.v2 + :command: image delete + +.. autoprogram-cliff:: openstack.image.v2 + :command: image list + +.. autoprogram-cliff:: openstack.image.v2 + :command: image save + +.. autoprogram-cliff:: openstack.image.v2 + :command: image set + +.. autoprogram-cliff:: openstack.image.v2 + :command: image unset + +.. autoprogram-cliff:: openstack.image.v2 + :command: image show + +.. autoprogram-cliff:: openstack.image.v2 + :command: image stage + +.. autoprogram-cliff:: openstack.image.v2 + :command: image import diff --git a/doc/source/cli/command-objects/implied_role.rst b/doc/source/cli/command-objects/implied_role.rst new file mode 100644 index 0000000000..09532c0b02 --- /dev/null +++ b/doc/source/cli/command-objects/implied_role.rst @@ -0,0 +1,8 @@ +============ +implied role +============ + +Identity v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: implied role * diff --git a/doc/source/cli/command-objects/ip-availability.rst b/doc/source/cli/command-objects/ip-availability.rst new file mode 100644 index 0000000000..94e60459b1 --- /dev/null +++ b/doc/source/cli/command-objects/ip-availability.rst @@ -0,0 +1,8 @@ +=============== +ip availability +=============== + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: ip availability * diff --git a/doc/source/cli/command-objects/keypair.rst b/doc/source/cli/command-objects/keypair.rst new file mode 100644 index 0000000000..f8bce3756b --- /dev/null +++ b/doc/source/cli/command-objects/keypair.rst @@ -0,0 +1,13 @@ +======= +keypair +======= + +The badly named keypair is really the public key of an OpenSSH key pair to be +used for access to created servers. You can also create a private key for +access to a created server by not passing any argument to the keypair create +command. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: keypair * diff --git a/doc/source/cli/command-objects/limit.rst b/doc/source/cli/command-objects/limit.rst new file mode 100644 index 0000000000..784d0cb423 --- /dev/null +++ b/doc/source/cli/command-objects/limit.rst @@ -0,0 +1,10 @@ +===== +limit +===== + +Identity v3 + +Limits are used to specify project-specific limits thresholds of resources. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: limit * diff --git a/doc/source/cli/command-objects/limits.rst b/doc/source/cli/command-objects/limits.rst new file mode 100644 index 0000000000..11d53802c6 --- /dev/null +++ b/doc/source/cli/command-objects/limits.rst @@ -0,0 +1,11 @@ +====== +limits +====== + +The Compute and Block Storage APIs have resource usage limits. + +Block Storage v2, v3; Compute v2 + + +.. autoprogram-cliff:: openstack.common + :command: limits * diff --git a/doc/source/cli/command-objects/local-ip-association.rst b/doc/source/cli/command-objects/local-ip-association.rst new file mode 100644 index 0000000000..824ee4d0e6 --- /dev/null +++ b/doc/source/cli/command-objects/local-ip-association.rst @@ -0,0 +1,11 @@ +============================================= +Local IP Associations (local_ip_associations) +============================================= + +The resource lets users assign Local IPs to user Ports. +This is a sub-resource of the Local IP resource. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: local ip association * diff --git a/doc/source/cli/command-objects/local-ip.rst b/doc/source/cli/command-objects/local-ip.rst new file mode 100644 index 0000000000..c8c5ab470d --- /dev/null +++ b/doc/source/cli/command-objects/local-ip.rst @@ -0,0 +1,12 @@ +===================== +Local IPs (local_ips) +===================== + +Extension that allows users to create a virtual IP that can later be assigned +to multiple ports/VMs (similar to anycast IP) and is guaranteed to only be +reachable within the same physical server/node boundaries + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: local ip * diff --git a/doc/source/cli/command-objects/mapping.rst b/doc/source/cli/command-objects/mapping.rst new file mode 100644 index 0000000000..5653b52bb9 --- /dev/null +++ b/doc/source/cli/command-objects/mapping.rst @@ -0,0 +1,10 @@ +======= +mapping +======= + +A **mapping** is used by the Identity service's OS-FEDERATION +extension. It is used by **federation protocols** and **identity providers**. +Applicable to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: mapping * \ No newline at end of file diff --git a/doc/source/cli/command-objects/module.rst b/doc/source/cli/command-objects/module.rst new file mode 100644 index 0000000000..82269f472d --- /dev/null +++ b/doc/source/cli/command-objects/module.rst @@ -0,0 +1,10 @@ +====== +module +====== + +Internal + +Installed Python modules in the OSC process. + +.. autoprogram-cliff:: openstack.cli + :command: module * diff --git a/doc/source/cli/command-objects/network-agent.rst b/doc/source/cli/command-objects/network-agent.rst new file mode 100644 index 0000000000..7e721db1ea --- /dev/null +++ b/doc/source/cli/command-objects/network-agent.rst @@ -0,0 +1,14 @@ +============= +network agent +============= + +A **network agent** is an agent that handles various tasks used to +implement virtual networks. These agents include neutron-dhcp-agent, +neutron-l3-agent, neutron-metering-agent, and neutron-lbaas-agent, +among others. The agent is available when the alive status of the +agent is "True". + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network agent * diff --git a/doc/source/cli/command-objects/network-auto-allocated-topology.rst b/doc/source/cli/command-objects/network-auto-allocated-topology.rst new file mode 100644 index 0000000000..436836484a --- /dev/null +++ b/doc/source/cli/command-objects/network-auto-allocated-topology.rst @@ -0,0 +1,14 @@ +=============================== +network auto allocated topology +=============================== + +An **auto allocated topology** allows admins to quickly set up external +connectivity for end-users. Only one auto allocated topology is allowed per +project. For more information on how to set up the resources required +for auto allocated topology review :neutron-doc:`the documentation +`. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network auto allocated topology * diff --git a/doc/source/cli/command-objects/network-flavor-profile.rst b/doc/source/cli/command-objects/network-flavor-profile.rst new file mode 100644 index 0000000000..c5e9aa0c13 --- /dev/null +++ b/doc/source/cli/command-objects/network-flavor-profile.rst @@ -0,0 +1,15 @@ +====================== +network flavor profile +====================== + +A **network flavor profile** allows administrators to create, delete, list, +show and update network service profile, which details a framework to enable +operators to configure and users to select from different abstract +representations of a service implementation in the Networking service. +It decouples the logical configuration from its instantiation enabling +operators to create user options according to deployment needs. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor profile * diff --git a/doc/source/cli/command-objects/network-flavor.rst b/doc/source/cli/command-objects/network-flavor.rst new file mode 100644 index 0000000000..6fe7504a0d --- /dev/null +++ b/doc/source/cli/command-objects/network-flavor.rst @@ -0,0 +1,33 @@ +============== +network flavor +============== + +A **network flavor** extension allows the user selection of operator-curated +flavors during resource creations. It allows administrators to create network +service flavors. + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'network flavor' pulls in + ... profile *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor add profile + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor create + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor remove profile + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor set + +.. autoprogram-cliff:: openstack.network.v2 + :command: network flavor show diff --git a/doc/source/cli/command-objects/network-l3-conntrack-helper.rst b/doc/source/cli/command-objects/network-l3-conntrack-helper.rst new file mode 100644 index 0000000000..badbab6337 --- /dev/null +++ b/doc/source/cli/command-objects/network-l3-conntrack-helper.rst @@ -0,0 +1,8 @@ +=========================== +network l3 conntrack helper +=========================== + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network l3 conntrack helper * diff --git a/doc/source/cli/command-objects/network-meter-rule.rst b/doc/source/cli/command-objects/network-meter-rule.rst new file mode 100644 index 0000000000..616c4bc516 --- /dev/null +++ b/doc/source/cli/command-objects/network-meter-rule.rst @@ -0,0 +1,13 @@ +================== +network meter rule +================== + +A **meter rule** sets the rule for +a meter to measure traffic for a specific IP range. +The following uses **meter** and requires the L3 +metering extension. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network meter rule * diff --git a/doc/source/cli/command-objects/network-meter.rst b/doc/source/cli/command-objects/network-meter.rst new file mode 100644 index 0000000000..5752e6f419 --- /dev/null +++ b/doc/source/cli/command-objects/network-meter.rst @@ -0,0 +1,24 @@ +============= +network meter +============= + +A **network meter** allows operators to measure +traffic for a specific IP range. The following commands +are specific to the L3 metering extension. + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'network meter *' pulls in + ... rule *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: network meter create + +.. autoprogram-cliff:: openstack.network.v2 + :command: network meter delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: network meter list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network meter show diff --git a/doc/source/cli/command-objects/network-qos-policy.rst b/doc/source/cli/command-objects/network-qos-policy.rst new file mode 100644 index 0000000000..af7a104070 --- /dev/null +++ b/doc/source/cli/command-objects/network-qos-policy.rst @@ -0,0 +1,11 @@ +================== +network qos policy +================== + +A **Network QoS policy** groups a number of Network QoS rules, applied to a +network or a port. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos policy * diff --git a/doc/source/cli/command-objects/network-qos-rule-type.rst b/doc/source/cli/command-objects/network-qos-rule-type.rst new file mode 100644 index 0000000000..197a86002f --- /dev/null +++ b/doc/source/cli/command-objects/network-qos-rule-type.rst @@ -0,0 +1,11 @@ +===================== +network qos rule type +===================== + +A **Network QoS rule type** is a specific Network QoS rule type available to be +used. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule type * diff --git a/doc/source/cli/command-objects/network-qos-rule.rst b/doc/source/cli/command-objects/network-qos-rule.rst new file mode 100644 index 0000000000..8b715c03ab --- /dev/null +++ b/doc/source/cli/command-objects/network-qos-rule.rst @@ -0,0 +1,28 @@ +================ +network qos rule +================ + +A **Network QoS rule** specifies a rule defined in a Network QoS policy; its +type is defined by the parameter 'type'. Can be assigned, within a Network QoS +policy, to a port or a network. Each Network QoS policy can contain several +rules, each of them + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'network qos rule *' pulls + network qos rule type *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule create + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule set + +.. autoprogram-cliff:: openstack.network.v2 + :command: network qos rule show diff --git a/doc/source/cli/command-objects/network-rbac.rst b/doc/source/cli/command-objects/network-rbac.rst new file mode 100644 index 0000000000..d9e48554d3 --- /dev/null +++ b/doc/source/cli/command-objects/network-rbac.rst @@ -0,0 +1,12 @@ +============ +network rbac +============ + +A **network rbac** is a Role-Based Access Control (RBAC) policy for +network resources. It enables both operators and users to grant access +to network resources for specific projects. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network rbac * diff --git a/doc/source/cli/command-objects/network-segment.rst b/doc/source/cli/command-objects/network-segment.rst new file mode 100644 index 0000000000..2e9143801d --- /dev/null +++ b/doc/source/cli/command-objects/network-segment.rst @@ -0,0 +1,28 @@ +=============== +network segment +=============== + +A **network segment** is an isolated Layer 2 segment within a network. +A network may contain multiple network segments. Depending on the +network configuration, Layer 2 connectivity between network segments +within a network may not be guaranteed. + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'network segment *' pulls + ... range *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment create + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment set + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment show diff --git a/doc/source/cli/command-objects/network-service-provider.rst b/doc/source/cli/command-objects/network-service-provider.rst new file mode 100644 index 0000000000..52d0288dd0 --- /dev/null +++ b/doc/source/cli/command-objects/network-service-provider.rst @@ -0,0 +1,13 @@ +======================== +network service provider +======================== + +A **network service provider** is a particular driver that implements a +networking service + +Network v2 + +.. _network_service_provider_list: + +.. autoprogram-cliff:: openstack.network.v2 + :command: network service provider list diff --git a/doc/source/cli/command-objects/network-trunk.rst b/doc/source/cli/command-objects/network-trunk.rst new file mode 100644 index 0000000000..98fd4b0c4b --- /dev/null +++ b/doc/source/cli/command-objects/network-trunk.rst @@ -0,0 +1,16 @@ +============= +network trunk +============= + +A **network trunk** is a container to group logical ports from different +networks and provide a single trunked vNIC for servers. It consists of +one parent port which is a regular VIF and multiple subports which allow +the server to connect to more networks. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network subport list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network trunk * diff --git a/doc/source/cli/command-objects/network.rst b/doc/source/cli/command-objects/network.rst new file mode 100644 index 0000000000..626b11a928 --- /dev/null +++ b/doc/source/cli/command-objects/network.rst @@ -0,0 +1,33 @@ +======= +network +======= + +A **network** is an isolated Layer 2 networking segment. There are two types +of networks, project and provider networks. Project networks are fully isolated +and are not shared with other projects. Provider networks map to existing +physical networks in the data center and provide external network access for +servers and other resources. Only an OpenStack administrator can create +provider networks. Networks can be connected via routers. + +Compute v2, Network v2 + +.. NOTE(efried): have to list these out one by one; 'network *' pulls in + ... flavor *, ... qos policy *, etc. + +.. autoprogram-cliff:: openstack.network.v2 + :command: network create + +.. autoprogram-cliff:: openstack.network.v2 + :command: network delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: network list + +.. autoprogram-cliff:: openstack.network.v2 + :command: network set + +.. autoprogram-cliff:: openstack.network.v2 + :command: network show + +.. autoprogram-cliff:: openstack.network.v2 + :command: network unset diff --git a/doc/source/cli/command-objects/network_segment_range.rst b/doc/source/cli/command-objects/network_segment_range.rst new file mode 100644 index 0000000000..f40007f385 --- /dev/null +++ b/doc/source/cli/command-objects/network_segment_range.rst @@ -0,0 +1,14 @@ +===================== +network segment range +===================== + +A **network segment range** is a resource for tenant network segment +allocation. +A network segment range exposes the segment range management to be administered +via the Neutron API. In addition, it introduces the ability for the +administrator to control the segment ranges globally or on a per-tenant basis. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: network segment range * diff --git a/doc/source/cli/command-objects/object-store-account.rst b/doc/source/cli/command-objects/object-store-account.rst new file mode 100644 index 0000000000..6beb63aff8 --- /dev/null +++ b/doc/source/cli/command-objects/object-store-account.rst @@ -0,0 +1,15 @@ +==================== +object store account +==================== + +An **object store account** represents the top-level of the hierarchy that +is comprised of **containers** and **objects**. Applies to Object Storage v1. + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object store account set + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object store account show + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object store account unset diff --git a/doc/source/cli/command-objects/object.rst b/doc/source/cli/command-objects/object.rst new file mode 100644 index 0000000000..8b328bd52f --- /dev/null +++ b/doc/source/cli/command-objects/object.rst @@ -0,0 +1,27 @@ +====== +object +====== + +An **object** stores data content, such as documents, images, and so on. They +can also store custom metadata with an object. Applies to Object Storage v1. + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object create + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object delete + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object list + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object save + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object set + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object show + +.. autoprogram-cliff:: openstack.object_store.v1 + :command: object unset diff --git a/doc/source/cli/command-objects/policy.rst b/doc/source/cli/command-objects/policy.rst new file mode 100644 index 0000000000..66bc2545a6 --- /dev/null +++ b/doc/source/cli/command-objects/policy.rst @@ -0,0 +1,9 @@ +====== +policy +====== + +A **policy** is an arbitrarily serialized policy engine rule set to be consumed +by a remote service. Applies to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: policy * diff --git a/doc/source/cli/command-objects/port.rst b/doc/source/cli/command-objects/port.rst new file mode 100644 index 0000000000..3af5272eb2 --- /dev/null +++ b/doc/source/cli/command-objects/port.rst @@ -0,0 +1,12 @@ +==== +port +==== + +A **port** is a connection point for attaching a single device, such as the +NIC of a server, to a network. The port also describes the associated network +configuration, such as the MAC and IP addresses to be used on that port. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: port * diff --git a/doc/source/cli/command-objects/project-cleanup.rst b/doc/source/cli/command-objects/project-cleanup.rst new file mode 100644 index 0000000000..e76e538948 --- /dev/null +++ b/doc/source/cli/command-objects/project-cleanup.rst @@ -0,0 +1,12 @@ +=============== +project cleanup +=============== + +Clean resources associated with a specific project based on OpenStackSDK +implementation + +Block Storage v2, v3; Compute v2; Network v2; DNS v2; Orchestrate v1 + + +.. autoprogram-cliff:: openstack.common + :command: project cleanup diff --git a/doc/source/cli/command-objects/project-v2.rst b/doc/source/cli/command-objects/project-v2.rst new file mode 100644 index 0000000000..502154d37e --- /dev/null +++ b/doc/source/cli/command-objects/project-v2.rst @@ -0,0 +1,6 @@ +===================== +project (Identity v2) +===================== + +.. autoprogram-cliff:: openstack.identity.v2 + :command: project * diff --git a/doc/source/cli/command-objects/project-v3.rst b/doc/source/cli/command-objects/project-v3.rst new file mode 100644 index 0000000000..9bee6ae8cf --- /dev/null +++ b/doc/source/cli/command-objects/project-v3.rst @@ -0,0 +1,6 @@ +===================== +project (Identity v3) +===================== + +.. autoprogram-cliff:: openstack.identity.v3 + :command: project * diff --git a/doc/source/cli/command-objects/quota.rst b/doc/source/cli/command-objects/quota.rst new file mode 100644 index 0000000000..59a8a9bb4e --- /dev/null +++ b/doc/source/cli/command-objects/quota.rst @@ -0,0 +1,11 @@ +===== +quota +===== + +Resource quotas appear in multiple APIs, OpenStackClient presents them as a +single object with multiple properties. + +Block Storage v1, v3; Compute v2; Network v2 + +.. autoprogram-cliff:: openstack.common + :command: quota * diff --git a/doc/source/cli/command-objects/region.rst b/doc/source/cli/command-objects/region.rst new file mode 100644 index 0000000000..86e7ca8ae0 --- /dev/null +++ b/doc/source/cli/command-objects/region.rst @@ -0,0 +1,10 @@ +====== +region +====== + +A **region** is a general division of an OpenStack deployment. You can associate +zero or more sub-regions with a region to create a tree-like structured +hierarchy. Applies to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: region * diff --git a/doc/source/cli/command-objects/registered-limit.rst b/doc/source/cli/command-objects/registered-limit.rst new file mode 100644 index 0000000000..98a5efba9e --- /dev/null +++ b/doc/source/cli/command-objects/registered-limit.rst @@ -0,0 +1,11 @@ +================ +registered limit +================ + +Identity v3 + +Registered limits are used to define default limits for resources within a +deployment. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: registered limit * diff --git a/doc/source/cli/command-objects/request-token.rst b/doc/source/cli/command-objects/request-token.rst new file mode 100644 index 0000000000..ea333c4aba --- /dev/null +++ b/doc/source/cli/command-objects/request-token.rst @@ -0,0 +1,10 @@ +============= +request token +============= + +A **request token** is used by the Identity service's OS-OAUTH1 extension. It +is used by the **consumer** to request **access tokens**. Applicable to +Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: request token * diff --git a/doc/source/cli/command-objects/role-assignment.rst b/doc/source/cli/command-objects/role-assignment.rst new file mode 100644 index 0000000000..aa618d4dd3 --- /dev/null +++ b/doc/source/cli/command-objects/role-assignment.rst @@ -0,0 +1,8 @@ +=============== +role assignment +=============== + +Identity v2, v3 + +.. autoprogram-cliff:: openstack.identity.v3 + :command: role assignment list diff --git a/doc/source/cli/command-objects/role-v2.rst b/doc/source/cli/command-objects/role-v2.rst new file mode 100644 index 0000000000..dc5bac6c65 --- /dev/null +++ b/doc/source/cli/command-objects/role-v2.rst @@ -0,0 +1,6 @@ +================== +role (Identity v2) +================== + +.. autoprogram-cliff:: openstack.identity.v2 + :command: role * diff --git a/doc/source/cli/command-objects/role-v3.rst b/doc/source/cli/command-objects/role-v3.rst new file mode 100644 index 0000000000..e36bef773f --- /dev/null +++ b/doc/source/cli/command-objects/role-v3.rst @@ -0,0 +1,6 @@ +================== +role (Identity v3) +================== + +.. autoprogram-cliff:: openstack.identity.v3 + :command: role * diff --git a/doc/source/cli/command-objects/router-ndp-proxy.rst b/doc/source/cli/command-objects/router-ndp-proxy.rst new file mode 100644 index 0000000000..26c7172623 --- /dev/null +++ b/doc/source/cli/command-objects/router-ndp-proxy.rst @@ -0,0 +1,12 @@ +================= +router ndp proxy +================= + +An **NDP proxy** publishes a internal IPv6 address to public network. With the +**NDP proxy**, the IPv6 address can be accessed from external. It is similar +to **Floating IP** of IPv4 in functionality. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: router ndp proxy * diff --git a/doc/source/cli/command-objects/router.rst b/doc/source/cli/command-objects/router.rst new file mode 100644 index 0000000000..6e8e05d7c0 --- /dev/null +++ b/doc/source/cli/command-objects/router.rst @@ -0,0 +1,12 @@ +====== +router +====== + +A **router** is a logical component that forwards data packets between +networks. It also provides Layer 3 and NAT forwarding to provide external +network access for servers on project networks. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: router * diff --git a/doc/source/cli/command-objects/security-group-rule.rst b/doc/source/cli/command-objects/security-group-rule.rst new file mode 100644 index 0000000000..429bcf270b --- /dev/null +++ b/doc/source/cli/command-objects/security-group-rule.rst @@ -0,0 +1,11 @@ +=================== +security group rule +=================== + +A **security group rule** specifies the network access rules for servers +and other resources on the network. + +Compute v2, Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group rule * diff --git a/doc/source/cli/command-objects/security-group.rst b/doc/source/cli/command-objects/security-group.rst new file mode 100644 index 0000000000..4edc199547 --- /dev/null +++ b/doc/source/cli/command-objects/security-group.rst @@ -0,0 +1,30 @@ +============== +security group +============== + +A **security group** acts as a virtual firewall for servers and other +resources on a network. It is a container for security group rules +which specify the network access rules. + +Compute v2, Network v2 + +.. NOTE(efried): have to list these out one by one; 'security group *' pulls in + ... rule *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group create + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group list + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group set + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group show + +.. autoprogram-cliff:: openstack.network.v2 + :command: security group unset diff --git a/doc/source/cli/command-objects/server-backup.rst b/doc/source/cli/command-objects/server-backup.rst new file mode 100644 index 0000000000..f2a2e2c958 --- /dev/null +++ b/doc/source/cli/command-objects/server-backup.rst @@ -0,0 +1,11 @@ +============= +server backup +============= + +A server backup is a disk image created in the Image store from a running server +instance. The backup command manages the number of archival copies to retain. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server backup create diff --git a/doc/source/cli/command-objects/server-event.rst b/doc/source/cli/command-objects/server-event.rst new file mode 100644 index 0000000000..372cb40073 --- /dev/null +++ b/doc/source/cli/command-objects/server-event.rst @@ -0,0 +1,12 @@ +============ +server event +============ + +Server event are event record for server operations. They consist of: type +(create, delete, reboot and so on), result (success, error), start time, finish +time and so on. These are important for server maintenance. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server event * diff --git a/doc/source/cli/command-objects/server-group.rst b/doc/source/cli/command-objects/server-group.rst new file mode 100644 index 0000000000..741eb4adaf --- /dev/null +++ b/doc/source/cli/command-objects/server-group.rst @@ -0,0 +1,10 @@ +============ +server group +============ + +Server groups provide a mechanism to group servers according to certain policy. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server group * diff --git a/doc/source/cli/command-objects/server-image.rst b/doc/source/cli/command-objects/server-image.rst new file mode 100644 index 0000000000..c013ca49bb --- /dev/null +++ b/doc/source/cli/command-objects/server-image.rst @@ -0,0 +1,11 @@ +============ +server image +============ + +A server image is a disk image created from a running server instance. The +image is created in the Image store. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server image create diff --git a/doc/source/cli/command-objects/server-migration.rst b/doc/source/cli/command-objects/server-migration.rst new file mode 100644 index 0000000000..9db58e3e46 --- /dev/null +++ b/doc/source/cli/command-objects/server-migration.rst @@ -0,0 +1,12 @@ +================ +server migration +================ + +A server migration provides a way to move an instance from one +host to another. There are four types of migration operation +supported: live migration, cold migration, resize and evacuation. + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server migration * diff --git a/doc/source/cli/command-objects/server.rst b/doc/source/cli/command-objects/server.rst new file mode 100644 index 0000000000..cf7df1dae3 --- /dev/null +++ b/doc/source/cli/command-objects/server.rst @@ -0,0 +1,89 @@ +====== +server +====== + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server add * + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server create + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server evacuate + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server delete + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server dump create + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server list + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server lock + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server migrate* + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server pause + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server reboot + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server rebuild + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server remove * + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server rescue + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server resize* + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server restore + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server resume + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server set + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server shelve + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server show + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server ssh + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server start + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server stop + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server suspend + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unlock + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unpause + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unrescue + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unset + +.. autoprogram-cliff:: openstack.compute.v2 + :command: server unshelve diff --git a/doc/source/cli/command-objects/service-provider.rst b/doc/source/cli/command-objects/service-provider.rst new file mode 100644 index 0000000000..47a503278c --- /dev/null +++ b/doc/source/cli/command-objects/service-provider.rst @@ -0,0 +1,10 @@ +================ +service provider +================ + +A **service provider** is used by the Identity service's OS-FEDERATION +extension. It is used by to register another OpenStack Identity service. +Applicable to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service provider * diff --git a/doc/source/cli/command-objects/service-v2.rst b/doc/source/cli/command-objects/service-v2.rst new file mode 100644 index 0000000000..6b22b7eeb6 --- /dev/null +++ b/doc/source/cli/command-objects/service-v2.rst @@ -0,0 +1,6 @@ +===================== +service (Identity v2) +===================== + +.. autoprogram-cliff:: openstack.identity.v2 + :command: service * diff --git a/doc/source/cli/command-objects/service-v3.rst b/doc/source/cli/command-objects/service-v3.rst new file mode 100644 index 0000000000..d4b702067b --- /dev/null +++ b/doc/source/cli/command-objects/service-v3.rst @@ -0,0 +1,18 @@ +===================== +service (Identity v3) +===================== + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service create + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service delete + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service list + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service show + +.. autoprogram-cliff:: openstack.identity.v3 + :command: service set diff --git a/doc/source/cli/command-objects/subnet-pool.rst b/doc/source/cli/command-objects/subnet-pool.rst new file mode 100644 index 0000000000..ce9649dc94 --- /dev/null +++ b/doc/source/cli/command-objects/subnet-pool.rst @@ -0,0 +1,11 @@ +=========== +subnet pool +=========== + +A **subnet pool** contains a collection of prefixes in CIDR notation +that are available for IP address allocation. + +Network v2 + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet pool * diff --git a/doc/source/cli/command-objects/subnet.rst b/doc/source/cli/command-objects/subnet.rst new file mode 100644 index 0000000000..488fc5a2f5 --- /dev/null +++ b/doc/source/cli/command-objects/subnet.rst @@ -0,0 +1,30 @@ +====== +subnet +====== + +A **subnet** is a block of IP addresses and associated configuration state. +Subnets are used to allocate IP addresses when new ports are created on a +network. + +Network v2 + +.. NOTE(efried): have to list these out one by one; 'subnet *' pulls in + subnet pool *. + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet create + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet delete + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet list + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet set + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet show + +.. autoprogram-cliff:: openstack.network.v2 + :command: subnet unset diff --git a/doc/source/cli/command-objects/token-v2.rst b/doc/source/cli/command-objects/token-v2.rst new file mode 100644 index 0000000000..c66302bfb2 --- /dev/null +++ b/doc/source/cli/command-objects/token-v2.rst @@ -0,0 +1,7 @@ +=================== +token (Identity v2) +=================== + + +.. autoprogram-cliff:: openstack.identity.v2 + :command: token * diff --git a/doc/source/cli/command-objects/token-v3.rst b/doc/source/cli/command-objects/token-v3.rst new file mode 100644 index 0000000000..6b2d87a61d --- /dev/null +++ b/doc/source/cli/command-objects/token-v3.rst @@ -0,0 +1,7 @@ +=================== +token (Identity v3) +=================== + + +.. autoprogram-cliff:: openstack.identity.v3 + :command: token * diff --git a/doc/source/cli/command-objects/trust.rst b/doc/source/cli/command-objects/trust.rst new file mode 100644 index 0000000000..738c640c48 --- /dev/null +++ b/doc/source/cli/command-objects/trust.rst @@ -0,0 +1,9 @@ +===== +trust +===== + +A **trust** provide project-specific role delegation between users, with +optional impersonation. Requires the OS-TRUST extension. Applies to Identity v3. + +.. autoprogram-cliff:: openstack.identity.v3 + :command: trust * diff --git a/doc/source/cli/command-objects/usage.rst b/doc/source/cli/command-objects/usage.rst new file mode 100644 index 0000000000..c2bcde0610 --- /dev/null +++ b/doc/source/cli/command-objects/usage.rst @@ -0,0 +1,8 @@ +===== +usage +===== + +Compute v2 + +.. autoprogram-cliff:: openstack.compute.v2 + :command: usage * diff --git a/doc/source/cli/command-objects/user-v2.rst b/doc/source/cli/command-objects/user-v2.rst new file mode 100644 index 0000000000..966bd37620 --- /dev/null +++ b/doc/source/cli/command-objects/user-v2.rst @@ -0,0 +1,7 @@ +================== +user (Identity v2) +================== + + +.. autoprogram-cliff:: openstack.identity.v2 + :command: user * diff --git a/doc/source/cli/command-objects/user-v3.rst b/doc/source/cli/command-objects/user-v3.rst new file mode 100644 index 0000000000..c11ff9a645 --- /dev/null +++ b/doc/source/cli/command-objects/user-v3.rst @@ -0,0 +1,7 @@ +================== +user (Identity v3) +================== + + +.. autoprogram-cliff:: openstack.identity.v3 + :command: user * diff --git a/doc/source/cli/command-objects/versions.rst b/doc/source/cli/command-objects/versions.rst new file mode 100644 index 0000000000..ebebec192a --- /dev/null +++ b/doc/source/cli/command-objects/versions.rst @@ -0,0 +1,8 @@ +======== +versions +======== + +Get a list of every version of every service in a given cloud. + +.. autoprogram-cliff:: openstack.common + :command: versions show diff --git a/doc/source/cli/command-objects/volume-attachment.rst b/doc/source/cli/command-objects/volume-attachment.rst new file mode 100644 index 0000000000..5622444638 --- /dev/null +++ b/doc/source/cli/command-objects/volume-attachment.rst @@ -0,0 +1,8 @@ +================= +volume attachment +================= + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume attachment * diff --git a/doc/source/cli/command-objects/volume-backend.rst b/doc/source/cli/command-objects/volume-backend.rst new file mode 100644 index 0000000000..f47efd1976 --- /dev/null +++ b/doc/source/cli/command-objects/volume-backend.rst @@ -0,0 +1,8 @@ +============== +volume backend +============== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume backend * diff --git a/doc/source/cli/command-objects/volume-backup.rst b/doc/source/cli/command-objects/volume-backup.rst new file mode 100644 index 0000000000..7b036ca0ce --- /dev/null +++ b/doc/source/cli/command-objects/volume-backup.rst @@ -0,0 +1,9 @@ +============= +volume backup +============= + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume backup * + diff --git a/doc/source/cli/command-objects/volume-group-snapshot.rst b/doc/source/cli/command-objects/volume-group-snapshot.rst new file mode 100644 index 0000000000..02a33c1e3c --- /dev/null +++ b/doc/source/cli/command-objects/volume-group-snapshot.rst @@ -0,0 +1,8 @@ +===================== +volume group snapshot +===================== + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group snapshot * diff --git a/doc/source/cli/command-objects/volume-group-type.rst b/doc/source/cli/command-objects/volume-group-type.rst new file mode 100644 index 0000000000..edb88dc7b0 --- /dev/null +++ b/doc/source/cli/command-objects/volume-group-type.rst @@ -0,0 +1,8 @@ +================= +volume group type +================= + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group type * diff --git a/doc/source/cli/command-objects/volume-group.rst b/doc/source/cli/command-objects/volume-group.rst new file mode 100644 index 0000000000..50bc830f90 --- /dev/null +++ b/doc/source/cli/command-objects/volume-group.rst @@ -0,0 +1,23 @@ +============ +volume group +============ + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group create + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group delete + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group list + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group failover + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group set + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume group show diff --git a/doc/source/cli/command-objects/volume-host.rst b/doc/source/cli/command-objects/volume-host.rst new file mode 100644 index 0000000000..acd0866356 --- /dev/null +++ b/doc/source/cli/command-objects/volume-host.rst @@ -0,0 +1,8 @@ +=========== +volume host +=========== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume host * diff --git a/doc/source/cli/command-objects/volume-message.rst b/doc/source/cli/command-objects/volume-message.rst new file mode 100644 index 0000000000..5b1a8acef2 --- /dev/null +++ b/doc/source/cli/command-objects/volume-message.rst @@ -0,0 +1,8 @@ +============== +volume message +============== + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume message * diff --git a/doc/source/cli/command-objects/volume-qos.rst b/doc/source/cli/command-objects/volume-qos.rst new file mode 100644 index 0000000000..82c4d540c7 --- /dev/null +++ b/doc/source/cli/command-objects/volume-qos.rst @@ -0,0 +1,8 @@ +========== +volume qos +========== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume qos * diff --git a/doc/source/cli/command-objects/volume-service.rst b/doc/source/cli/command-objects/volume-service.rst new file mode 100644 index 0000000000..43d455ff5a --- /dev/null +++ b/doc/source/cli/command-objects/volume-service.rst @@ -0,0 +1,8 @@ +============== +volume service +============== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume service * diff --git a/doc/source/cli/command-objects/volume-snapshot.rst b/doc/source/cli/command-objects/volume-snapshot.rst new file mode 100644 index 0000000000..e63e436dff --- /dev/null +++ b/doc/source/cli/command-objects/volume-snapshot.rst @@ -0,0 +1,8 @@ +=============== +volume snapshot +=============== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume snapshot * diff --git a/doc/source/cli/command-objects/volume-transfer-request.rst b/doc/source/cli/command-objects/volume-transfer-request.rst new file mode 100644 index 0000000000..97dac02a0a --- /dev/null +++ b/doc/source/cli/command-objects/volume-transfer-request.rst @@ -0,0 +1,8 @@ +======================= +volume transfer request +======================= + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume transfer request * diff --git a/doc/source/cli/command-objects/volume-type.rst b/doc/source/cli/command-objects/volume-type.rst new file mode 100644 index 0000000000..003ee67306 --- /dev/null +++ b/doc/source/cli/command-objects/volume-type.rst @@ -0,0 +1,8 @@ +=========== +volume type +=========== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume type * diff --git a/doc/source/cli/command-objects/volume.rst b/doc/source/cli/command-objects/volume.rst new file mode 100644 index 0000000000..337bb9fa2b --- /dev/null +++ b/doc/source/cli/command-objects/volume.rst @@ -0,0 +1,34 @@ +====== +volume +====== + +Block Storage v2, v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume create + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume delete + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume list + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume migrate + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume set + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume show + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume unset + +Block Storage v3 + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume summary + +.. autoprogram-cliff:: openstack.volume.v3 + :command: volume revert diff --git a/doc/source/cli/commands.rst b/doc/source/cli/commands.rst new file mode 100644 index 0000000000..653e2a50bd --- /dev/null +++ b/doc/source/cli/commands.rst @@ -0,0 +1,343 @@ +.. _command-structure: + +================= +Command Structure +================= + +OpenStackClient has a consistent and predictable format for all of its commands. + +Commands take the form:: + + openstack [] [] [] + +.. NOTE:: + + All long options names begin with two dashes (``--``) and use a single dash + (``-``) internally between words (``--like-this``). Underscores (``_``) are + not used in option names. + +Global Options +-------------- + +Global options are global in the sense that they apply to every command +invocation regardless of action to be performed. They include authentication +credentials and API version selection. Most global options have a corresponding +environment variable that may also be used to set the value. If both are +present, the command-line option takes priority. The environment variable +names are derived from the option name by dropping the leading dashes (``--``), +converting each embedded dash (``-``) to an underscore (``_``), and converting +to upper case. + +For example, the default value of ``--os-username`` can be set by defining +the environment variable ``OS_USERNAME``. + + +Command Object(s) and Action +---------------------------- + +Commands consist of an object described by one or more words followed by +an action. Commands that require two objects have the primary object ahead +of the action and the secondary object after the action. Any positional +arguments identifying the objects shall appear in the same order as the +objects. In badly formed English it is expressed as "(Take) object1 +(and perform) action (using) object2 (to it)." + +:: + + + +Examples: + +.. code-block:: bash + + $ group add user + + $ volume type list # 'volume type' is a two-word single object + + +Command Arguments and Options +----------------------------- + +Each command may have its own set of options distinct from the global options. +They follow the same style as the global options and always appear between +the command and any positional arguments the command requires. + + +Objects +------- + +The objects consist of one or more words to compose a unique name. +Occasionally when multiple APIs have a common name with common +overlapping purposes there will be options to select which object to use, or +the API resources will be merged, as in the ``quota`` object that has options +referring to both Compute and Volume quotas. + +* ``access token``: (**Identity**) long-lived OAuth-based token +* ``address scope``: (**Network**) a scope of IPv4 or IPv6 addresses +* ``aggregate``: (**Compute**) a grouping of compute hosts +* ``availability zone``: (**Compute**, **Network**, **Volume**) a logical partition of hosts or block storage or network services +* ``block storage cluster``: (**Volume**) clusters of volume services +* ``block storage resource filter``: (**Volume**) filters for volume service resources +* ``catalog``: (**Identity**) service catalog +* ``command``: (**Internal**) installed commands in the OSC process +* ``compute agent``: (**Compute**) a cloud Compute agent available to a hypervisor +* ``compute service``: (**Compute**) a cloud Compute process running on a host +* ``configuration``: (**Internal**) OpenStack client configuration +* ``consistency group``: (**Volume**) a consistency group of volumes +* ``consistency group snapshot``: (**Volume**) a point-in-time copy of a consistency group +* ``console log``: (**Compute**) server console text dump +* ``console url``: (**Compute**) server remote console URL +* ``consumer``: (**Identity**) OAuth-based delegatee +* ``container``: (**Object Storage**) a grouping of objects +* ``credential``: (**Identity**) specific to identity providers +* ``domain``: (**Identity**) a grouping of projects +* ``ec2 credentials``: (**Identity**) AWS EC2-compatible credentials +* ``endpoint``: (**Identity**) the base URL used to contact a specific service +* ``endpoint group``: (**Identity**) group endpoints to be used as filters +* ``extension``: (**Compute**, **Identity**, **Network**, **Volume**) OpenStack server API extensions +* ``federation protocol``: (**Identity**) the underlying protocol used while federating identities +* ``flavor``: (**Compute**) predefined server configurations: ram, root disk and so on +* ``fixed ip``: (**Compute**) - an internal IP address assigned to a server +* ``floating ip``: (**Network**) - a public IP address that can be mapped to a server +* ``floating ip pool``: (**Network**) - a pool of public IP addresses +* ``group``: (**Identity**) a grouping of users +* ``host``: (**Compute**) - the physical computer running compute services +* ``hypervisor``: (**Compute**) the virtual machine manager +* ``hypervisor stats``: (**Compute**) hypervisor statistics over all compute nodes +* ``identity provider``: (**Identity**) a source of users and authentication +* ``image``: (**Image**) a disk image +* ``image member``: (**Image**) a project that is a member of an Image +* ``ip availability``: (**Network**) - details of IP usage of a network +* ``keypair``: (**Compute**) an SSH public key +* ``limits``: (**Compute**, **Volume**) resource usage limits +* ``mapping``: (**Identity**) a definition to translate identity provider attributes to Identity concepts +* ``module``: (**Internal**) - installed Python modules in the OSC process +* ``network``: (**Compute**, **Network**) - a virtual network for connecting servers and other resources +* ``network agent``: (**Network**) - A network agent is an agent that handles various tasks used to implement virtual networks +* ``network auto allocated topology``: (**Network**) - an auto-allocated topology for a project +* ``network flavor``: (**Network**) - allows the user to choose the type of service by a set of advertised service capabilities (e.g., LOADBALANCER, FWAAS, L3, VPN, etc) rather than by a provider type or named vendor +* ``network flavor profile``: (**Network**) - predefined neutron service configurations: driver +* ``network meter``: (**Network**) - allow traffic metering in a network +* ``network meter rule``: (**Network**) - rules for network traffic metering +* ``network rbac``: (**Network**) - an RBAC policy for network resources +* ``network qos rule``: (**Network**) - a QoS rule for network resources +* ``network qos policy``: (**Network**) - a QoS policy for network resources +* ``network qos rule type``: (**Network**) - list of QoS available rule types +* ``network segment``: (**Network**) - a segment of a virtual network +* ``network segment range``: (**Network**) - a segment range for tenant network segment allocation +* ``network service provider``: (**Network**) - a driver providing a network service +* ``object``: (**Object Storage**) a single file in the Object Storage +* ``object store account``: (**Object Storage**) owns a group of Object Storage resources +* ``policy``: (**Identity**) determines authorization +* ``port``: (**Network**) - a virtual port for connecting servers and other resources to a network +* ``project``: (**Identity**) owns a group of resources +* ``quota``: (**Compute**, **Volume**) resource usage restrictions +* ``region``: (**Identity**) a subset of an OpenStack deployment +* ``request token``: (**Identity**) temporary OAuth-based token +* ``role``: (**Identity**) a policy object used to determine authorization +* ``role assignment``: (**Identity**) a relationship between roles, users or groups, and domains or projects +* ``router``: (**Network**) - a virtual router +* ``security group``: (**Compute**, **Network**) - groups of network access rules +* ``security group rule``: (**Compute**, **Network**) - the individual rules that define protocol/IP/port access +* ``server``: (**Compute**) virtual machine instance +* ``server backup``: (**Compute**) backup server disk image by using snapshot method +* ``server dump``: (**Compute**) a dump file of a server created by features like kdump +* ``server event``: (**Compute**) events of a server +* ``server group``: (**Compute**) a grouping of servers +* ``server image``: (**Compute**) saved server disk image +* ``service``: (**Identity**) a cloud service +* ``service provider``: (**Identity**) a resource that consumes assertions from an ``identity provider`` +* ``subnet``: (**Network**) - a contiguous range of IP addresses assigned to a network +* ``subnet pool``: (**Network**) - a pool of subnets +* ``token``: (**Identity**) a bearer token managed by Identity service +* ``trust``: (**Identity**) project-specific role delegation between users, with optional impersonation +* ``usage``: (**Compute**) display host resources being consumed +* ``user``: (**Identity**) individual cloud resources users +* ``user role``: (**Identity**) roles assigned to a user +* ``volume``: (**Volume**) block volumes +* ``volume attachment``: (**Volume**) an attachment of a volumes to a server +* ``volume backup``: (**Volume**) backup for volumes +* ``volume backend capability``: (**Volume**) volume backend storage capabilities +* ``volume backend pool``: (**Volume**) volume backend storage pools +* ``volume backup record``: (**Volume**) volume record that can be imported or exported +* ``volume backend``: (**Volume**) volume backend storage +* ``volume group``: (**Volume**) group of volumes +* ``volume group snapshot``: (**Volume**) a point-in-time copy of a volume group +* ``volume group type``: (**Volume**) deployment-specific types of volumes groups available +* ``volume host``: (**Volume**) the physical computer for volumes +* ``volume message``: (**Volume**) volume API internal messages detailing volume failure messages +* ``volume qos``: (**Volume**) quality-of-service (QoS) specification for volumes +* ``volume snapshot``: (**Volume**) a point-in-time copy of a volume +* ``volume type``: (**Volume**) deployment-specific types of volumes available +* ``volume service``: (**Volume**) services to manage block storage operations +* ``volume transfer request``: (**Volume**) volume owner transfer request + +Plugin Objects +-------------- + +The following are known `Objects` used by OpenStack +:ref:`plugins`. These are listed here to avoid name +conflicts when creating new plugins. For a complete list check out +:ref:`plugin-commands`. + +* ``acl``: (**Key Manager (Barbican)**) +* ``acl user``: (**Key Manager (Barbican)**) +* ``action definition``: (**Workflow Engine (Mistral)**) +* ``action execution``: (**Workflow Engine (Mistral)**) +* ``appcontainer``: (**Application Container (Zun)**) +* ``appcontainer host``: (**Application Container (Zun)**) +* ``appcontainer image``: (**Application Container (Zun)**) +* ``appcontainer network``: (**Application Container (Zun)**) +* ``appcontainer service``: (**Application Container (Zun)**) +* ``baremetal``: (**Baremetal (Ironic)**) +* ``claim``: (**Messaging (Zaqar)**) +* ``coe ca``: (**Container Orchestration Engine (Magnum)**) +* ``coe cluster``: (**Container Orchestration Engine (Magnum)**) +* ``coe cluster template``: (**Container Orchestration Engine (Magnum)**) +* ``coe quotas``: (**Container Orchestration Engine (Magnum)**) +* ``coe service``: (**Container Orchestration Engine (Magnum)**) +* ``coe stats``: (**Container Orchestration Engine (Magnum)**) +* ``cron trigger``: (**Workflow Engine (Mistral)**) +* ``database flavor``: (**Database (Trove)**) +* ``loadbalancer``: (**Load Balancer (Octavia)**) +* ``loadbalancer healthmonitor``: (**Load Balancer (Octavia)**) +* ``loadbalancer l7policy``: (**Load Balancer (Octavia)**) +* ``loadbalancer l7rule``: (**Load Balancer (Octavia)**) +* ``loadbalancer listener``: (**Load Balancer (Octavia)**) +* ``loadbalancer member``: (**Load Balancer (Octavia)**) +* ``loadbalancer pool``: (**Load Balancer (Octavia)**) +* ``message-broker cluster``: (**Message Broker (Cue)**) +* ``messaging``: (**Messaging (Zaqar)**) +* ``messaging flavor``: (**Messaging (Zaqar)**) +* ``network subport``: (**Networking (Neutron)**) +* ``network trunk``: (**Networking (Neutron)**) +* ``orchestration resource``: (**Orchestration (Heat)**) +* ``orchestration template``: (**Orchestration (Heat)**) +* ``pool``: (**Messaging (Zaqar)**) +* ``ptr record``: (**DNS (Designate)**) +* ``queue``: (**Messaging (Zaqar)**) +* ``recordset``: (**DNS (Designate)**) +* ``secret``: (**Key Manager (Barbican)**) +* ``secret container``: (**Key Manager (Barbican)**) +* ``secret order``: (**Key Manager (Barbican)**) +* ``share``: (**Share (Manila)**) +* ``share access``: (**Share (Manila)**) +* ``share availability zone``: (**Share (Manila)**) +* ``share backup``: (**Share (Manila)**) +* ``share export location``: (**Share (Manila)**) +* ``share group``: (**Share (Manila)**) +* ``share group snapshot``: (**Share (Manila)**) +* ``share group type``: (**Share (Manila)**) +* ``share instance``: (**Share (Manila)**) +* ``share limits show``: (**Share (Manila)**) +* ``share lock``: (**Share (Manila)**) +* ``share message``: (**Share (Manila)**) +* ``share migration``: (**Share (Manila)**) +* ``share network``: (**Share (Manila)**) +* ``share quota``: (**Share (Manila)**) +* ``share replica``: (**Share (Manila)**) +* ``share security service``: (**Share (Manila)**) +* ``share server``: (**Share (Manila)**) +* ``share server migration``: (**Share (Manila)**) +* ``share service``: (**Share (Manila)**) +* ``share snapshot``: (**Share (Manila)**) +* ``share snapshot access``: (**Share (Manila)**) +* ``share snapshot export location``: (**Share (Manila)**) +* ``share snapshot instance``: (**Share (Manila)**) +* ``share transfer``: (**Share (Manila)**) +* ``share type``: (**Share (Manila)**) +* ``software config``: (**Orchestration (Heat)**) +* ``software deployment``: (**Orchestration (Heat)**) +* ``stack event``: (**Orchestration (Heat)**) +* ``stack hook``: (**Orchestration (Heat)**) +* ``stack output``: (**Orchestration (Heat)**) +* ``stack resource``: (**Orchestration (Heat)**) +* ``stack snapshot``: (**Orchestration (Heat)**) +* ``stack template``: (**Orchestration (Heat)**) +* ``subscription``: (**Messaging (Zaqar)**) +* ``task execution``: (**Workflow Engine (Mistral)**) +* ``tld``: (**DNS (Designate)**) +* ``workbook``: (**Workflow Engine (Mistral)**) +* ``workflow``: (**Workflow Engine (Mistral)**) +* ``workflow execution``: (**Workflow Engine (Mistral)**) +* ``zone``: (**DNS (Designate)**) +* ``zone blacklist``: (**DNS (Designate)**) +* ``zone export``: (**DNS (Designate)**) +* ``zone import``: (**DNS (Designate)**) +* ``zone transfer``: (**DNS (Designate)**) + + +Actions +------- + +The actions used by OpenStackClient are defined below to provide a consistent +meaning to each action. Many of them have logical opposite actions. +Those actions with an opposite action are noted in parens if applicable. + +* ``authorize`` - authorize a token (used in OAuth) +* ``add`` (``remove``) - add some object to a container object; the command + is built in the order of ``container add object ``, + the positional arguments appear in the same order +* ``create`` (``delete``) - create a new occurrence of the specified object +* ``delete`` (``create``) - delete specific occurrences of the specified objects +* ``expand`` (``shrink``) - increase the capacity of a cluster +* ``failover`` - failover volume host to different backend +* ``issue`` (``revoke``) - issue a token +* ``list`` - display summary information about multiple objects +* ``lock`` (``unlock``) - lock one or more servers so that non-admin user won't be able to execute actions +* ``migrate`` - move a server or a volume to a different host; ``--live`` performs a + live server migration if possible +* ``pause`` (``unpause``) - stop one or more servers and leave them in memory +* ``query`` - Query resources by Elasticsearch query string or json format DSL. +* ``cleanup`` - flexible clean resources associated with a specific project +* ``reboot`` - forcibly reboot a server +* ``rebuild`` - rebuild a server using (most of) the same arguments as in the original create +* ``remove`` (``add``) - remove an object from a group of objects +* ``rescue`` (``unrescue``) - reboot a server in a special rescue mode allowing access to the original disks +* ``resize`` - change a server's flavor or a cluster's capacity +* ``restore`` - restore a heat stack snapshot or restore a server in soft-deleted state +* ``resume`` (``suspend``) - return one or more suspended servers to running state +* ``revoke`` (``issue``) - revoke a token +* ``save`` - download an object locally +* ``set`` (``unset``) - set a property on the object, formerly called metadata +* ``shelve`` (``unshelve``) - shelve one or more servers +* ``show`` - display detailed information about the specific object +* ``shrink`` (``expand``) - reduce the capacity of a cluster +* ``start`` (``stop``) - start one or more servers +* ``stop`` (``start``) - stop one or more servers +* ``suspend`` (``resume``) - stop one or more servers and save to disk freeing memory +* ``unlock`` (``lock``) - unlock one or more servers +* ``unpause`` (``pause``) - return one or more paused servers to running state +* ``unrescue`` (``rescue``) - return a server to normal boot mode +* ``unset`` (``set``) - remove an attribute of the object +* ``unshelve`` (``shelve``) - unshelve one or more servers + + +Implementation +-------------- + +The command structure is designed to support seamless addition of plugin +command modules via Python's *entry points* mechanism. The plugin commands must +be subclasses of Cliff's ``command.Command`` object. See :ref:`plugins` for +more information. + + +Command Entry Points +-------------------- + +Commands are added to the client using ``setuptools`` entry points in ``setup.cfg``. +There is a single common group ``openstack.cli`` for commands that are not versioned, +and a group for each combination of OpenStack API and version that is +supported. For example, to support Identity API v3 there is a group called +``openstack.identity.v3`` that contains the individual commands. The command +entry points have the form:: + + action_object = fully.qualified.module.vXX.object:ActionObject + +For example, the ``list user`` command for the Identity API is identified in +``setup.cfg`` with:: + + openstack.identity.v3 = + # ... + list_user = openstackclient.identity.v3.user:ListUser + # ... diff --git a/doc/source/cli/data/cinder.csv b/doc/source/cli/data/cinder.csv new file mode 100644 index 0000000000..1b199400b4 --- /dev/null +++ b/doc/source/cli/data/cinder.csv @@ -0,0 +1,146 @@ +absolute-limits,limits show --absolute,Lists absolute limits for a user. +api-version,openstack versions show --service volume,Display the server API version information. +availability-zone-list,availability zone list --volume,Lists all availability zones. +attachment-complete,volume attachment complete,Complete an attachment for a cinder volume. (Supported by API versions 3.44 - 3.latest) +attachment-create,volume attachment create,Create an attachment for a cinder volume. (Supported by API versions 3.27 - 3.latest) +attachment-delete,volume attachment delete,Delete an attachment for a cinder volume. (Supported by API versions 3.27 - 3.latest) +attachment-list,volume attachment list,Lists all attachments. (Supported by API versions 3.27 - 3.latest) +attachment-show,volume attachment show,Show detailed information for attachment. (Supported by API versions 3.27 - 3.latest) +attachment-update,volume attachment update,Update an attachment for a cinder volume. (Supported by API versions 3.27 - 3.latest) +backup-create,volume backup create,Creates a volume backup. +backup-delete,volume backup delete,Removes a backup. +backup-export,volume backup record export,Export backup metadata record. +backup-import,volume backup record import,Import backup metadata record. +backup-list,volume backup list,Lists all backups. +backup-reset-state,volume backup set --state,Explicitly updates the backup state. +backup-restore,volume backup restore,Restores a backup. +backup-show,volume backup show,Show backup details. +backup-update,volume backup set,Updates a backup. (Supported by API versions 3.9 - 3.latest) +cgsnapshot-create,consistency group snapshot create,Creates a cgsnapshot. +cgsnapshot-delete,consistency group snapshot delete,Removes one or more cgsnapshots. +cgsnapshot-list,consistency group snapshot list,Lists all cgsnapshots. +cgsnapshot-show,consistency group snapshot show,Shows cgsnapshot details. +cluster-disable,block storage cluster set --disable,Disables clustered services. (Supported by API versions 3.7 - 3.latest) +cluster-enable,block storage cluster set --enable,Enables clustered services. (Supported by API versions 3.7 - 3.latest) +cluster-list,block storage cluster list,Lists clustered services with optional filtering. (Supported by API versions 3.7 - 3.latest) +cluster-show,block storage cluster show,Show detailed information on a clustered service. (Supported by API versions 3.7 - 3.latest) +consisgroup-create,consistency group create,Creates a consistency group. +consisgroup-create-from-src,consistency group create --consistency-group-snapshot,Creates a consistency group from a cgsnapshot or a source CG +consisgroup-delete,consistency group delete,Removes one or more consistency groups. +consisgroup-list,consistency group list,Lists all consistencygroups. +consisgroup-show,consistency group show,Shows details of a consistency group. +consisgroup-update,consistency group set,Updates a consistencygroup. +create,volume create,Creates a volume. +delete,volume delete,Removes one or more volumes. +encryption-type-create,volume type create --encryption-provider --enc..,Creates encryption type for a volume type. Admin only. +encryption-type-delete,volume type delete,Deletes encryption type for a volume type. Admin only. +encryption-type-list,volume type list --encryption-type,Shows encryption type details for volume types. Admin only. +encryption-type-show,volume type list --encryption-show,Shows encryption type details for volume type. Admin only. +encryption-type-update,volume type set --encryption-provider --enc..,Update encryption type information for a volume type (Admin Only). +extend,volume set --size,Attempts to extend size of an existing volume. +extra-specs-list,volume type list --long,Lists current volume types and extra specs. +failover-host,volume host failover,Failover a replicating cinder-volume host. +force-delete,volume delete --force,"Attempts force-delete of volume regardless of state." +freeze-host,volume host set --disable,Freeze and disable the specified cinder-volume host. +get-capabilities,volume backend capability show,Show capabilities of a volume backend. Admin only. +get-pools,volume backend pool list,Show pool information for backends. Admin only. +group-create,volume group create,Creates a group. (Supported by API versions 3.13 - 3.latest) +group-create-from-src,volume group create [--source-group|--group-snapshot],Creates a group from a group snapshot or a source group. (Supported by API versions 3.14 - 3.latest) +group-delete,volume group delete,Removes one or more groups. (Supported by API versions 3.13 - 3.latest) +group-disable-replication,volume group set --disable-replication,Disables replication for group. (Supported by API versions 3.38 - 3.latest) +group-enable-replication,volume group set --enable-replication,Enables replication for group. (Supported by API versions 3.38 - 3.latest) +group-failover-replication,volume group failover,Fails over replication for group. (Supported by API versions 3.38 - 3.latest) +group-list,volume group list,Lists all groups. (Supported by API versions 3.13 - 3.latest) +group-list-replication-targets,volume group list --replication-targets,Lists replication targets for group. (Supported by API versions 3.38 - 3.latest) +group-show,volume group show,Shows details of a group. (Supported by API versions 3.13 - 3.latest) +group-snapshot-create,volume group snapshot create,Creates a group snapshot. (Supported by API versions 3.14 - 3.latest) +group-snapshot-delete,volume group snapshot delete,Removes one or more group snapshots. (Supported by API versions 3.14 - 3.latest) +group-snapshot-list,volume group snapshot list,Lists all group snapshots. (Supported by API versions 3.14 - 3.latest) +group-snapshot-show,volume group snapshot show,Shows group snapshot details. (Supported by API versions 3.14 - 3.latest) +group-specs-list,volume group type list,Lists current group types and specs. (Supported by API versions 3.11 - 3.latest) +group-type-create,volume group type create,Creates a group type. (Supported by API versions 3.11 - 3.latest) +group-type-default,volume group type list --default,List the default group type. (Supported by API versions 3.11 - 3.latest) +group-type-delete,volume group type delete,Deletes group type or types. (Supported by API versions 3.11 - 3.latest) +group-type-key,volume group type set,Sets or unsets group_spec for a group type. (Supported by API versions 3.11 - 3.latest) +group-type-list,volume group type set,Lists available 'group types'. (Admin only will see private types) (Supported by API versions 3.11 - 3.latest) +group-type-show,volume group type show,Show group type details. (Supported by API versions 3.11 - 3.latest) +group-type-update,volume group type set,Updates group type name description and/or is_public. (Supported by API versions 3.11 - 3.latest) +group-update,volume group set,Updates a group. (Supported by API versions 3.13 - 3.latest) +image-metadata,volume set --image-property,Sets or deletes volume image metadata. +image-metadata-show,volume show,Shows volume image metadata. +list,volume list,Lists all volumes. +list-filters,block storage resource filter list,List enabled filters. (Supported by API versions 3.33 - 3.latest) +manage,volume create --remote-source k=v,Manage an existing volume. +manageable-list,block storage volume manageable list,Lists all manageable volumes. (Supported by API versions 3.8 - 3.latest) +message-delete,volume message delete,Removes one or more messages. (Supported by API versions 3.3 - 3.latest) +message-list,volume message list,Lists all messages. (Supported by API versions 3.3 - 3.latest) +message-show,volume message show,Shows message details. (Supported by API versions 3.3 - 3.latest) +metadata,volume set --property k=v / volume unset --property k,Sets or deletes volume metadata. +metadata-show,volume show,Shows volume metadata. +metadata-update-all,volume set --property k=v,Updates volume metadata. +migrate,volume migrate --host --force-copy --lock-volume ,Migrates volume to a new host. +qos-associate,volume qos associate,Associates qos specs with specified volume type. +qos-create,volume qos create,Creates a qos specs. +qos-delete,volume qos delete,Deletes a specified qos specs. +qos-disassociate,volume qos disassociate,Disassociates qos specs from specified volume type. +qos-disassociate-all,volume qos disassociate --all,Disassociates qos specs from all associations. +qos-get-association,volume qos show,Gets all associations for specified qos specs. +qos-key,volume qos set --property k=v / volume qos unset --property k,Sets or unsets specifications for a qos spec +qos-list,volume qos list,Lists qos specs. +qos-show,volume qos show,Shows a specified qos specs. +quota-class-show,quota show --class,Lists quotas for a quota class. +quota-class-update,quota set --class,Updates quotas for a quota class. +quota-defaults,quota show --default,Lists default quotas for a tenant. +quota-delete,quota delete --volume,Delete the quotas for a tenant. +quota-show,quota show,Lists quotas for a tenant. +quota-update,quota set,Updates quotas for a tenant. +quota-usage,quota show --usage,Lists quota usage for a tenant. +rate-limits,limits show --rate,Lists rate limits for a user. +readonly-mode-update,volume set --read-only-mode | --read-write-mode,Updates volume read-only access-mode flag. +rename,volume set --name,Renames a volume. +reset-state,volume set --state,Explicitly updates the volume state. +retype,volume type set --type,Changes the volume type for a volume. +revert-to-snapshot,volume revert,Revert a volume to the specified snapshot. (Supported by API versions 3.40 - 3.latest) +service-disable,volume service set --disable,Disables the service. +service-enable,volume service set --enable,Enables the service. +service-get-log,block storage log level list,(Supported by API versions 3.32 - 3.latest) +service-list,volume service list,Lists all services. Filter by host and service binary. +service-set-log,block storage log level set,(Supported by API versions 3.32 - 3.latest) +set-bootable,volume set --bootable / --not-bootable,Update bootable status of a volume. +show,volume show,Shows volume details. +snapshot-create,volume snapshot create,Creates a snapshot. +snapshot-delete,volume snapshot delete,Remove one or more snapshots. +snapshot-list,volume snapshot list,Lists all snapshots. +snapshot-manage,volume snapshot create --remote-source ,Manage an existing snapshot. +snapshot-manageable-list,block storage snapshot manageable list,Lists all manageable snapshots. (Supported by API versions 3.8 - 3.latest) +snapshot-metadata,volume snapshot set --property k=v / snapshot unset --property k,Sets or deletes snapshot metadata. +snapshot-metadata-show,volume snapshot show,Shows snapshot metadata. +snapshot-metadata-update-all,volume snapshot set --property k=v,Updates snapshot metadata. +snapshot-rename,volume snapshot set --name,Renames a snapshot. +snapshot-reset-state,volume snapshot set --state,Explicitly updates the snapshot state. +snapshot-show,volume snapshot show,Shows snapshot details. +snapshot-unmanage,volume snapshot delete --remote,Stop managing a snapshot. +summary,volume summary,Get volumes summary. (Supported by API versions 3.12 - 3.latest) +thaw-host,volume host set --enable,Thaw and enable the specified cinder-volume host. +transfer-accept,volume transfer accept,Accepts a volume transfer. +transfer-create,volume transfer create,Creates a volume transfer. +transfer-delete,volume transfer delete,Undoes a transfer. +transfer-list,volume transfer list,Lists all transfers. +transfer-show,volume transfer show,Show transfer details. +type-access-add,volume type set --project,Adds volume type access for the given project. +type-access-list,volume type show,Print access information about the given volume type. +type-access-remove,volume type unset --project,Removes volume type access for the given project. +type-create,volume type create,Creates a volume type. +type-default,volume type list --default,List the default volume type. +type-delete,volume type delete,Deletes a specified volume type. +type-key,volume type set --property k=v / volume type unset --property k,Sets or unsets extra_spec for a volume type. +type-list,volume type list,Lists available 'volume types'. +type-show,volume type show,Show volume type details. +type-update,volume type set,"Updates volume type name description and/or is_public." +unmanage,volume delete --remote,Stop managing a volume. +upload-to-image,image create --volume,Uploads volume to Image Service as an image. +version-list,versions show --service block-storage,List all API versions. (Supported by API versions 3.0 - 3.latest) +work-cleanup,block storage cleanup,Request cleanup of services with optional filtering. (Supported by API versions 3.24 - 3.latest) +bash-completion,complete,Prints arguments for bash_completion. +help,help,Shows help about this program or one of its subcommands. +list-extensions,extension list --volume,Lists all available os-api extensions. diff --git a/doc/source/cli/data/glance.csv b/doc/source/cli/data/glance.csv new file mode 100644 index 0000000000..f978962274 --- /dev/null +++ b/doc/source/cli/data/glance.csv @@ -0,0 +1,67 @@ +cache-clear,cached image clear,"Clear all images from cache, queue or both." +cache-delete,cached image delete,Delete image from cache/caching queue. +cache-list,cached image list,Get cache state. +cache-queue,cached image queue,Queue image(s) for caching. +explain,WONTFIX,Describe a specific model. +image-create,image create,Create a new image. +image-create-via-import, image create --import,"EXPERIMENTAL: Create a new image via image import using glance-direct import method. Missing support for web-download, copy-image and glance-download import methods. The OSC command is also missing support for importing image to specified store as well as all stores (--store, --stores, --all-stores) and skip or stop processing if import fails to one of the store (--allow-failure)" +image-deactivate,image set --deactivate,Deactivate specified image. +image-delete,image delete,Delete specified image. +image-download,image save,Download a specific image. +image-import,image import,Initiate the image import taskflow. +image-list,image list,List images you can access. +image-reactivate,image set --activate,Reactivate specified image. +image-show,image show,Describe a specific image. +image-stage,image stage,Upload data for a specific image to staging. +image-tag-delete,image unset --tag ,Delete the tag associated with the given image. +image-tag-update,image set --tag ,Update an image with the given tag. +image-tasks,,Get tasks associated with image. +image-update,image set,Update an existing image. +image-upload,,Upload data for a specific image. +import-info,image import info,Show available import methods from Glance. +location-add,,Add a location (and related metadata) to an image. +location-delete,,Remove locations (and related metadata) from an image. +location-update,,Update metadata of an image's location. +md-namespace-create,image metadef namespace create,Create a new metadata definitions namespace. +md-namespace-delete,image metadef namespace delete,Delete specified metadata definitions namespace with its contents. +md-namespace-import,WONTFIX,Import a metadata definitions namespace from file or standard input. +md-namespace-list,image metadef namespace list,List metadata definitions namespaces. +md-namespace-objects-delete,image metadef object delete,Delete all metadata definitions objects inside a specific namespace. +md-namespace-properties-delete,image metadef property delete,Delete all metadata definitions property inside a specific namespace. +md-namespace-resource-type-list,image metadef resource type association list,List resource types associated to specific namespace. +md-namespace-show,image metadef namespace show,Describe a specific metadata definitions namespace. +md-namespace-tags-delete,,Delete all metadata definitions tags inside a specific namespace. +md-namespace-update,,Update an existing metadata definitions namespace. +md-object-create,image metadef object create,Create a new metadata definitions object inside a namespace. +md-object-show,image metadef object show,Describe a specific metadata definitions object inside a namespace. +md-object-list,image metadef object list,List metadata definitions objects inside a specific namespace. +md-object-delete,image metadef object delete,Delete a specific metadata definitions object inside a namespace. +md-object-property-show,image metadef object property show,Describe a specific metadata definitions property inside an object. +md-object-update,image metadef object update,Update metadata definitions object inside a namespace. +md-property-create,image metadef property create,Create a new metadata definitions property inside a namespace. +md-property-delete,image metadef property delete,Delete a specific metadata definitions property inside a namespace. +md-property-list,image metadef property list,List metadata definitions properties inside a specific namespace. +md-property-show,image metadef property show,Describe a specific metadata definitions property inside a namespace. +md-property-update,image metadef property set,Update metadata definitions property inside a namespace. +md-resource-type-associate,image metadef resource type association create,Associate resource type with a metadata definitions namespace. +md-resource-type-deassociate,image metadef resource type association delete,Deassociate resource type with a metadata definitions namespace. +md-resource-type-list,image metadef resource type list,List available resource type names. +md-tag-create,,Add a new metadata definitions tag inside a namespace. +md-tag-create-multiple,,Create new metadata definitions tags inside a namespace. +md-tag-delete,,Delete a specific metadata definitions tag inside a namespace. +md-tag-list,,List metadata definitions tags inside a specific namespace. +md-tag-show,,Describe a specific metadata definitions tag inside a namespace. +md-tag-update,,Rename a metadata definitions tag inside a namespace. +member-create,image add project,Create member for a given image. +member-delete,image remove project,Delete image member. +member-get,image member get,Show details of an image member +member-list,image member list,Describe sharing permissions by image. +member-update,image set --accept --reject --status,Update the status of a member for a given image. +stores-delete,image delete --store,Delete image from specific store. +stores-info,,Print available backends from Glance. +task-create,WONTFIX,Create a new task. +task-list,image task list,List tasks you can access. +task-show,image task show,Describe a specific task. +usage,,Get quota usage information. +bash-completion,complete,Prints arguments for bash_completion. +help,help,Display help about this program or one of its subcommands. diff --git a/doc/source/cli/data/keystone.csv b/doc/source/cli/data/keystone.csv new file mode 100644 index 0000000000..2a7e7f5690 --- /dev/null +++ b/doc/source/cli/data/keystone.csv @@ -0,0 +1,37 @@ +catalog,catalog show,"List service catalog, possibly filtered by service." +ec2-credentials-create,ec2 credentials create,Create EC2-compatible credentials for user per tenant. +ec2-credentials-delete,ec2 credentials delete,Delete EC2-compatible credentials. +ec2-credentials-get,ec2 credentials show,Display EC2-compatible credentials. +ec2-credentials-list,ec2 credentials list,List EC2-compatible credentials for a user. +endpoint-create,endpoint create,Create a new endpoint associated with a service. +endpoint-delete,endpoint delete,Delete a service endpoint. +endpoint-get,endpoint get,Find endpoint filtered by a specific attribute or service type. +endpoint-list,endpoint list,List configured service endpoints. +password-update,user password set,Update own password. +role-create,role create,Create new role. +role-delete,role delete,Delete role. +role-get,role show,Display role details. +role-list,role list,List all roles. +service-create,service create,Add service to Service Catalog. +service-delete,service delete,Delete service from Service Catalog. +service-get,service show,Display service from Service Catalog. +service-list,service list,List all services in Service Catalog. +tenant-create,project create,Create new tenant. +tenant-delete,project delete,Delete tenant. +tenant-get,project show,Display tenant details. +tenant-list,project list,List all tenants. +tenant-update,project set,"Update tenant name, description, enabled status." +token-get,token issue,Display the current user token. +user-create,user create,Create new user. +user-delete,user delete,Delete user. +user-get,user show,Display user details. +user-list,user list,List users. +user-password-update,user set --password,Update user password. +user-role-add,role add --user --project,Add role to user. +user-role-list,role assignment list --user --project,List roles granted to a user. +user-role-remove,role remove --user --project,Remove role from user. +user-update,user set,"Update user's name, email, and enabled status." +discover,WONTFIX,"Discover Keystone servers, supported API versions and extensions." +bootstrap,WONTFIX,"Grants a new role to a new user on a new tenant, after creating each." +bash-completion,complete,Prints all of the commands and options to stdout. +help,help,Display help about this program or one of its subcommands. diff --git a/doc/source/cli/data/neutron.csv b/doc/source/cli/data/neutron.csv new file mode 100644 index 0000000000..2399ed825f --- /dev/null +++ b/doc/source/cli/data/neutron.csv @@ -0,0 +1,262 @@ +address-scope-create,address scope create,Create an address scope for a given tenant. +address-scope-delete,address scope delete,Delete an address scope. +address-scope-list,address scope list,List address scopes that belong to a given tenant. +address-scope-show,address scope show,Show information about an address scope. +address-scope-update,address scope set,Update an address scope. +agent-delete,network agent delete,Delete a given agent. +agent-list,network agent list,List agents. +agent-show,network agent show,Show information of a given agent. +agent-update,network agent set,Updates the admin status and description for a specified agent. +auto-allocated-topology-delete,network auto allocated topology delete,Delete the auto-allocated topology of a given tenant. +auto-allocated-topology-show,network auto allocated topology create,Show the auto-allocated topology of a given tenant. +availability-zone-list,availability zone list,List availability zones. +bash-completion,complete,Prints all of the commands and options for bash-completion. +bgp-dragent-list-hosting-speaker,bgp speaker show dragents,List Dynamic Routing agents hosting a BGP speaker. +bgp-dragent-speaker-add,bgp dragent add speaker,Add a BGP speaker to a Dynamic Routing agent. +bgp-dragent-speaker-remove,bgp dragent remove speaker,Removes a BGP speaker from a Dynamic Routing agent. +bgp-peer-create,bgp peer create,Create a BGP Peer. +bgp-peer-delete,bgp peer delete,Delete a BGP peer. +bgp-peer-list,bgp peer list,List BGP peers. +bgp-peer-show,bgp peer show,Show information of a given BGP peer. +bgp-peer-update,bgp peer set,Update BGP Peer's information. +bgp-speaker-advertiseroute-list,bgp speaker list advertised routes,List routes advertised by a given BGP speaker. +bgp-speaker-create,bgp speaker create,Create a BGP Speaker. +bgp-speaker-delete,bgp speaker delete,Delete a BGP speaker. +bgp-speaker-list,bgp speaker list,List BGP speakers. +bgp-speaker-list-on-dragent,bgp speaker list --agent,List BGP speakers hosted by a Dynamic Routing agent. +bgp-speaker-network-add,bgp speaker add network,Add a network to the BGP speaker. +bgp-speaker-network-remove,bgp speaker remove network,Remove a network from the BGP speaker. +bgp-speaker-peer-add,bgp speaker add peer,Add a peer to the BGP speaker. +bgp-speaker-peer-remove,bgp speaker remove peer,Remove a peer from the BGP speaker. +bgp-speaker-show,bgp speaker show,Show information of a given BGP speaker. +bgp-speaker-update,bgp speaker set,Update BGP Speaker's information. +dhcp-agent-list-hosting-net,network agent list --network,List DHCP agents hosting a network. +dhcp-agent-network-add,network agent add network,Add a network to a DHCP agent. +dhcp-agent-network-remove,network agent remove network,Remove a network from a DHCP agent. +ext-list,extension list,List all extensions. +ext-show,extension show,Show information of a given resource. +firewall-create,,Create a firewall. +firewall-delete,,Delete a given firewall. +firewall-list,,List firewalls that belong to a given tenant. +firewall-policy-create,,Create a firewall policy. +firewall-policy-delete,,Delete a given firewall policy. +firewall-policy-insert-rule,,Insert a rule into a given firewall policy. +firewall-policy-list,,List firewall policies that belong to a given tenant. +firewall-policy-remove-rule,,Remove a rule from a given firewall policy. +firewall-policy-show,,Show information of a given firewall policy. +firewall-policy-update,,Update a given firewall policy. +firewall-rule-create,,Create a firewall rule. +firewall-rule-delete,,Delete a given firewall rule. +firewall-rule-list,,List firewall rules that belong to a given tenant. +firewall-rule-show,,Show information of a given firewall rule. +firewall-rule-update,,Update a given firewall rule. +firewall-show,,Show information of a given firewall. +firewall-update,,Update a given firewall. +flavor-associate,network flavor add profile,Add a Neutron service flavor with a flavor profile. +flavor-create,network flavor create,Create a Neutron service flavor. +flavor-delete,network flavor delete,Delete a given Neutron service flavor. +flavor-disassociate,network flavor remove profile,Remove a Neutron service flavor from a flavor profile. +flavor-list,network flavor list,List Neutron service flavors. +flavor-profile-create,network flavor profile create,Create a Neutron service flavor profile. +flavor-profile-delete,network flavor profile delete,Delete a given Neutron service flavor profile. +flavor-profile-list,network flavor profile list,List Neutron service flavor profiles. +flavor-profile-show,network flavor profile show,Show information about a given Neutron service flavor profile. +flavor-profile-update,network flavor profile set,Update a given Neutron service flavor profile. +flavor-show,network flavor show,Show information about a given Neutron service flavor. +flavor-update,network flavor set,Update a Neutron service flavor. +floatingip-associate,floating ip set port --fixed-ip,Create a mapping between a floating IP and a fixed IP. +floatingip-create,floating ip create,Create a floating IP for a given tenant. +floatingip-delete,floating ip delete,Delete a given floating IP. +floatingip-disassociate,floating ip unset --port,Remove a mapping from a floating IP to a fixed IP. +floatingip-list,floating ip list,List floating IPs that belong to a given tenant. +floatingip-show,floating ip show,Show information of a given floating IP. +help,help,print detailed help for another command +ipsec-site-connection-create,,Create an IPsec site connection. +ipsec-site-connection-delete,,Delete a given IPsec site connection. +ipsec-site-connection-list,,List IPsec site connections that belong to a given tenant. +ipsec-site-connection-show,,Show information of a given IPsec site connection. +ipsec-site-connection-update,,Update a given IPsec site connection. +l3-agent-list-hosting-router,network agent list --routers,List L3 agents hosting a router. +l3-agent-router-add,network agent add router --agent-type l3,Add a router to a L3 agent. +l3-agent-router-remove,network agent remove router --agent-type l3,Remove a router from a L3 agent. +lb-agent-hosting-pool,,Get loadbalancer agent hosting a pool. +lb-healthmonitor-associate,,Create a mapping between a health monitor and a pool. +lb-healthmonitor-create,,Create a health monitor. +lb-healthmonitor-delete,,Delete a given health monitor. +lb-healthmonitor-disassociate,,Remove a mapping from a health monitor to a pool. +lb-healthmonitor-list,,List health monitors that belong to a given tenant. +lb-healthmonitor-show,,Show information of a given health monitor. +lb-healthmonitor-update,,Update a given health monitor. +lb-member-create,,Create a member. +lb-member-delete,,Delete a given member. +lb-member-list,,List members that belong to a given tenant. +lb-member-show,,Show information of a given member. +lb-member-update,,Update a given member. +lb-pool-create,,Create a pool. +lb-pool-delete,,Delete a given pool. +lb-pool-list,,List pools that belong to a given tenant. +lb-pool-list-on-agent,,List the pools on a loadbalancer agent. +lb-pool-show,,Show information of a given pool. +lb-pool-stats,,Retrieve stats for a given pool. +lb-pool-update,,Update a given pool. +lb-vip-create,,Create a vip. +lb-vip-delete,,Delete a given vip. +lb-vip-list,,List vips that belong to a given tenant. +lb-vip-show,,Show information of a given vip. +lb-vip-update,,Update a given vip. +lbaas-agent-hosting-loadbalancer,,Get lbaas v2 agent hosting a loadbalancer. +lbaas-healthmonitor-create,,LBaaS v2 Create a healthmonitor. +lbaas-healthmonitor-delete,,LBaaS v2 Delete a given healthmonitor. +lbaas-healthmonitor-list,,LBaaS v2 List healthmonitors that belong to a given tenant. +lbaas-healthmonitor-show,,LBaaS v2 Show information of a given healthmonitor. +lbaas-healthmonitor-update,,LBaaS v2 Update a given healthmonitor. +lbaas-l7policy-create,,LBaaS v2 Create L7 policy. +lbaas-l7policy-delete,,LBaaS v2 Delete a given L7 policy. +lbaas-l7policy-list,,LBaaS v2 List L7 policies that belong to a given listener. +lbaas-l7policy-show,,LBaaS v2 Show information of a given L7 policy. +lbaas-l7policy-update,,LBaaS v2 Update a given L7 policy. +lbaas-l7rule-create,,LBaaS v2 Create L7 rule. +lbaas-l7rule-delete,,LBaaS v2 Delete a given L7 rule. +lbaas-l7rule-list,,LBaaS v2 List L7 rules that belong to a given L7 policy. +lbaas-l7rule-show,,LBaaS v2 Show information of a given rule. +lbaas-l7rule-update,,LBaaS v2 Update a given L7 rule. +lbaas-listener-create,,LBaaS v2 Create a listener. +lbaas-listener-delete,,LBaaS v2 Delete a given listener. +lbaas-listener-list,,LBaaS v2 List listeners that belong to a given tenant. +lbaas-listener-show,,LBaaS v2 Show information of a given listener. +lbaas-listener-update,,LBaaS v2 Update a given listener. +lbaas-loadbalancer-create,,LBaaS v2 Create a loadbalancer. +lbaas-loadbalancer-delete,,LBaaS v2 Delete a given loadbalancer. +lbaas-loadbalancer-list,,LBaaS v2 List loadbalancers that belong to a given tenant. +lbaas-loadbalancer-list-on-agent,,List the loadbalancers on a loadbalancer v2 agent. +lbaas-loadbalancer-show,,LBaaS v2 Show information of a given loadbalancer. +lbaas-loadbalancer-stats,,Retrieve stats for a given loadbalancer. +lbaas-loadbalancer-status,,Retrieve status for a given loadbalancer. +lbaas-loadbalancer-update,,LBaaS v2 Update a given loadbalancer. +lbaas-member-create,,LBaaS v2 Create a member. +lbaas-member-delete,,LBaaS v2 Delete a given member. +lbaas-member-list,,LBaaS v2 List members that belong to a given pool. +lbaas-member-show,,LBaaS v2 Show information of a given member. +lbaas-member-update,,LBaaS v2 Update a given member. +lbaas-pool-create,,LBaaS v2 Create a pool. +lbaas-pool-delete,,LBaaS v2 Delete a given pool. +lbaas-pool-list,,LBaaS v2 List pools that belong to a given tenant. +lbaas-pool-show,,LBaaS v2 Show information of a given pool. +lbaas-pool-update,,LBaaS v2 Update a given pool. +meter-label-create,network meter create,Create a metering label for a given tenant. +meter-label-delete,network meter delete,Delete a given metering label. +meter-label-list,network meter list,List metering labels that belong to a given tenant. +meter-label-rule-create,network meter rule create,Create a metering label rule for a given label. +meter-label-rule-delete,network meter rule delete,Delete a given metering label. +meter-label-rule-list,network meter rule list,List metering labels that belong to a given label. +meter-label-rule-show,network meter rule show,Show information of a given metering label rule. +meter-label-show,network meter show,Show information of a given metering label. +net-create,network create,Create a network for a given tenant. +net-delete,network delete,Delete a given network. +net-external-list,network list --external,List external networks that belong to a given tenant. +net-ip-availability-list,ip availability list,List IP usage of networks +net-ip-availability-show,ip availability show,Show IP usage of specific network +net-list,network list,List networks that belong to a given tenant. +net-list-on-dhcp-agent,network list --agent,List the networks on a DHCP agent. +net-show,network show,Show information of a given network. +net-update,network set / network unset,Update network's information. +port-create,port create,Create a port for a given tenant. +port-delete,port delete,Delete a given port. +port-list,port list,List ports that belong to a given tenant. +port-show,port show,Show information of a given port. +port-update,port set / port unset,Update port's information. +purge,,Delete all resources that belong to a given tenant. +qos-available-rule-types,network qos rule type list,List available qos rule types. +qos-bandwidth-limit-rule-create,network qos rule create --type bandwidth-limit,Create a qos bandwidth limit rule. +qos-bandwidth-limit-rule-delete,network qos rule delete --type bandwidth-limit,Delete a given qos bandwidth limit rule. +qos-bandwidth-limit-rule-list,network qos rule list --type bandwidth-limit,List all qos bandwidth limit rules belonging to the specified policy. +qos-bandwidth-limit-rule-show,network qos rule show --type bandwidth-limit,Show information about the given qos bandwidth limit rule. +qos-bandwidth-limit-rule-update,network qos rule update --type bandwidth-limit,Update the given qos bandwidth limit rule. +qos-dscp-marking-rule-create,network qos rule create --type dscp-marking,Create a QoS DSCP marking rule. +qos-dscp-marking-rule-delete,network qos rule delete --type dscp-marking,Delete a given qos dscp marking rule. +qos-dscp-marking-rule-list,network qos rule list --type dscp-marking,List all QoS DSCP marking rules belonging to the specified policy. +qos-dscp-marking-rule-show,network qos rule show --type dscp-marking,Show information about the given qos dscp marking rule. +qos-dscp-marking-rule-update,network qos rule update --type dscp-marking,Update the given QoS DSCP marking rule. +qos-minimum-bandwidth-rule-create,network qos rule create --type minimum-bandwidth,Create a qos minimum bandwidth rule. +qos-minimum-bandwidth-rule-delete,network qos rule delete --type minimum-bandwidth,Delete a given qos minimum bandwidth rule. +qos-minimum-bandwidth-rule-list,network qos rule list --type minimum-bandwidth,List all qos minimum bandwidth rules belonging to the specified policy. +qos-minimum-bandwidth-rule-show,network qos rule show --type minimum-bandwidth,Show information about the given qos minimum bandwidth rule. +qos-minimum-bandwidth-rule-update,network qos rule update --type minimum-bandwidth,Update the given qos minimum bandwidth rule. +qos-policy-create,network qos policy create,Create a qos policy. +qos-policy-delete,network qos policy delete,Delete a given qos policy. +qos-policy-list,network qos policy list,List QoS policies that belong to a given tenant connection. +qos-policy-show,network qos policy show,Show information of a given qos policy. +qos-policy-update,network qos policy set,Update a given qos policy. +quota-default-show,quota show --default,Show default quotas for a given tenant. +quota-delete,quota delete --network,Delete defined quotas of a given tenant. +quota-list,quota list,List quotas of all tenants who have non-default quota values. +quota-show,quota show,Show quotas for a given tenant. +quota-update,quota set,Define tenant's quotas not to use defaults. +rbac-create,network rbac create,Create a RBAC policy for a given tenant. +rbac-delete,network rbac delete,Delete a RBAC policy. +rbac-list,network rbac list,List RBAC policies that belong to a given tenant. +rbac-show,network rbac show,Show information of a given RBAC policy. +rbac-update,network rbac set,Update RBAC policy for given tenant. +router-create,router create,Create a router for a given tenant. +router-delete,router delete,Delete a given router. +router-gateway-clear,router unset,Remove an external network gateway from a router. +router-gateway-set,router set / router unset,Set the external network gateway for a router. +router-interface-add,router add subnet / router add port,Add an internal network interface to a router. +router-interface-delete,router remove subnet / router remove port,Remove an internal network interface from a router. +router-list,router list,List routers that belong to a given tenant. +router-list-on-l3-agent,router list --agents,List the routers on a L3 agent. +router-port-list,port list --router,"List ports that belong to a given tenant, with specified router." +router-show,router show,Show information of a given router. +router-update,router set,Update router's information. +security-group-create,security group create,Create a security group. +security-group-delete,security group delete,Delete a given security group. +security-group-list,security group list,List security groups that belong to a given tenant. +security-group-rule-create,security group rule create,Create a security group rule. +security-group-rule-delete,security group rule delete,Delete a given security group rule. +security-group-rule-list,security group rule list,List security group rules that belong to a given tenant. +security-group-rule-show,security group rule show,Show information of a given security group rule. +security-group-show,security group show,Show information of a given security group. +security-group-update,security group set / security group unset,Update a given security group. +service-provider-list,network service provider list,List service providers. +subnet-create,subnet create,Create a subnet for a given tenant. +subnet-delete,subnet delete,Delete a given subnet. +subnet-list,subnet list,List subnets that belong to a given tenant. +subnet-show,subnet show,Show information of a given subnet. +subnet-update,subnet set / subnet unset,Update subnet's information. +subnetpool-create,subnet pool create,Create a subnetpool for a given tenant. +subnetpool-delete,subnet pool delete,Delete a given subnetpool. +subnetpool-list,subnet pool list,List subnetpools that belong to a given tenant. +subnetpool-show,subnet pool show,Show information of a given subnetpool. +subnetpool-update,subnet pool set / subnet pool unset,Update subnetpool's information. +tag-add,network set --tag,Add a tag into the resource. +tag-remove,network unset --tag,Remove a tag on the resource. +tag-replace,network set --no-tag --tag,Replace all tags on the resource. +vpn-endpoint-group-create,,Create a VPN endpoint group. +vpn-endpoint-group-delete,,Delete a given VPN endpoint group. +vpn-endpoint-group-list,,List VPN endpoint groups that belong to a given tenant. +vpn-endpoint-group-show,,Show a specific VPN endpoint group. +vpn-endpoint-group-update,,Update a given VPN endpoint group. +vpn-ikepolicy-create,,Create an IKE policy. +vpn-ikepolicy-delete,,Delete a given IKE policy. +vpn-ikepolicy-list,,List IKE policies that belong to a tenant. +vpn-ikepolicy-show,,Show information of a given IKE policy. +vpn-ikepolicy-update,,Update a given IKE policy. +vpn-ipsecpolicy-create,,Create an IPsec policy. +vpn-ipsecpolicy-delete,,Delete a given IPsec policy. +vpn-ipsecpolicy-list,,List IPsec policies that belong to a given tenant connection. +vpn-ipsecpolicy-show,,Show information of a given IPsec policy. +vpn-ipsecpolicy-update,,Update a given IPsec policy. +vpn-service-create,,Create a VPN service. +vpn-service-delete,,Delete a given VPN service. +vpn-service-list,,List VPN service configurations that belong to a given tenant. +vpn-service-show,,Show information of a given VPN service. +vpn-service-update,,Update a given VPN service. + +tap-flow-create,tapflow create,Create a tap flow +tap-flow-delete,tapflow delete,Delete a tap flow +tap-flow-list,tapflow list,List all tap flows +tap-flow-show,tapflow show,Show details of the tap flow +tap-service-create,tapservice create,Create a tap service +tap-service-delete,tapservice delete,Delete a tap service +tap-service-list,tapservice list,List all tap services +tap-service-show,tapservice show,Show details of the tap service diff --git a/doc/source/cli/data/nova.csv b/doc/source/cli/data/nova.csv new file mode 100644 index 0000000000..ff691a5193 --- /dev/null +++ b/doc/source/cli/data/nova.csv @@ -0,0 +1,127 @@ +add-secgroup,server add security group,Add a Security Group to a server. +agent-create,compute agent create,Create new agent build. +agent-delete,compute agent delete,Delete existing agent build. +agent-list,compute agent list,List all builds. +agent-modify,compute agent set,Modify existing agent build. +aggregate-add-host,aggregate add host,Add the host to the specified aggregate. +aggregate-cache-images,aggregate cache image,Request images be cached. (Supported by API versions '2.81' - '2.latest') [hint: use '-- os-compute-api-version' flag to show help message for proper version] +aggregate-create,aggregate create,Create a new aggregate with the specified details. +aggregate-delete,aggregate delete,Delete the aggregate. +aggregate-list,aggregate list,Print a list of all aggregates. +aggregate-remove-host,aggregate remove host,Remove the specified host from the specified aggregate. +aggregate-set-metadata,aggregate set / unset,Update the metadata associated with the aggregate. +aggregate-show,aggregate show,Show details of the specified aggregate. +aggregate-update,aggregate set / unset,Update the aggregate's name and optionally availability zone. +availability-zone-list,availability zone list,List all the availability zones. +backup,server backup create,Backup a server by creating a 'backup' type snapshot. +boot,server create,Boot a new server. +clear-password,server set --root-password,Clear the admin password for a server from the metadata server. This action does not actually change the instance server password. +console-log,console log show,Get console log output of a server. +delete,server delete,Immediately shut down and delete specified server(s). +diagnostics,openstack server show --diagnostics,Retrieve server diagnostics. +evacuate,server evacuate,Evacuate server from failed host. +flavor-access-add,flavor set --project,Add flavor access for the given tenant. +flavor-access-list,flavor show,Print access information about the given flavor. +flavor-access-remove,flavor unset,Remove flavor access for the given tenant. +flavor-create,flavor create,Create a new flavor. +flavor-delete,flavor delete,Delete a specific flavor +flavor-key,flavor set / unset --property,Set or unset extra_spec for a flavor. +flavor-list,flavor list,Print a list of available 'flavors' +flavor-show,flavor show,Show details about the given flavor. +flavor-update,flavor set --description,Update the description of an existing flavor. (Supported by API versions '2.55' - '2.latest') [hint: use '--os-compute-api-version' flag to show help message for proper version] +force-delete,server delete,Force delete a server. +get-mks-console,console url show --mks,Get an MKS console to a server. (Supported by API versions '2.8' - '2.latest') [hint: use ' --os-compute-api-version' flag to show help message for proper version] +get-password,WONTFIX,Get the admin password for a server. This operation calls the metadata service to query metadata information and does not read password information from the server itself. +get-rdp-console,console url show --rdp,Get a rdp console to a server. +get-serial-console,console url show --serial,Get a serial console to a server. +get-spice-console,console url show --spice,Get a spice console to a server. +get-vnc-console,console url show --novnc,Get a vnc console to a server. +host-evacuate,WONTFIX,Evacuate all instances from failed host. +host-evacuate-live,WONTFIX,Live migrate all instances off the specified host to other available hosts. +host-meta,WONTFIX,Set or Delete metadata on all instances of a host. +host-servers-migrate,WONTFIX,Cold migrate all instances off the specified host to other available hosts. +hypervisor-list,hypervisor list,List hypervisors. (Supported by API versions '2.0' - '2.latest') +hypervisor-servers,server list --host,List servers belonging to specific hypervisors. +hypervisor-show,hypervisor show,Display the details of the specified hypervisor. +hypervisor-stats,hypervisor stats show,Get hypervisor statistics over all compute nodes. +hypervisor-uptime,hypervisor show,Display the uptime of the specified hypervisor. +image-create,server image create,Create a new image by taking a snapshot of a running server. +instance-action,server event show,Show an action. +instance-action-list,server event list,List actions on a server. +instance-usage-audit-log,WONTFIX,List/Get server usage audits. +interface-attach,server add port / server add floating ip / server add fixed ip,Attach a network interface to a server. +interface-detach,server remove port,Detach a network interface from a server. +interface-list,port list --server,List interfaces attached to a server. +keypair-add,keypair create,Create a new key pair for use with servers. +keypair-delete,keypair delete,Delete keypair given by its name. +keypair-list,keypair list,Print a list of keypairs for a user +keypair-show,keypair show,Show details about the given keypair. +limits,limits show,Print rate and absolute limits. +list,server list,List active servers. +list-secgroup,security group list,List Security Group(s) of a server. +live-migration,server migration list,Migrate running server to a new machine. +live-migration-abort,server migration abort,Abort an on-going live migration. +live-migration-force-comp,server migration force complete,Force on-going live migration to complete. +lock,server lock,Lock a server. +meta,server set --property / unset,Set or delete metadata on a server. +migrate,server migrate,Migrate a server. The new host will be selected by the scheduler. +migration-list,server migration list,Print a list of migrations. +pause,server pause,Pause a server. +quota-class-show,quota show --class,List the quotas for a quota class. +quota-class-update,quota set --class,Update the quotas for a quota class. +quota-defaults,quota list,List the default quotas for a tenant. +quota-delete,quota delete --compute,Delete quota for a tenant/user so their quota will Revert back to default. +quota-show,quota show,List the quotas for a tenant/user. +quota-update,quota set,Update the quotas for a tenant/user. +reboot,server reboot,Reboot a server. +rebuild,server rebuild,"Shutdown, re-image, and re-boot a server." +refresh-network,WONTFIX,Refresh server network information. +remove-secgroup,server remove security group,Remove a Security Group from a server. +rescue,server rescue,Reboots a server into rescue mode. +reset-network,WONTFIX,Reset network of a server. +reset-state,server set --state,Reset the state of a server. +resize,server resize,Resize a server. +resize-confirm,server resize --confirm,Confirm a previous resize. +resize-revert,server resize --revert,Revert a previous resize. +restore,server restore,Restore a soft-deleted server. +resume,server resume,Resume a server. +server-group-create,server group create,Create a new server group with the specified details. +server-group-delete,server group delete,Delete specific server group(s). +server-group-get,server group show,Get a specific server group. +server-group-list,server group list,Print a list of all server groups. +server-migration-list,server migration list,Get the migrations list of specified server. +server-migration-show,server migration show,Get the migration of specified server. +server-tag-add,server set --tag,Add one or more tags to a server. +server-tag-delete,server unset --tag,Delete one or more tags from a server. +server-tag-delete-all,server unset --tag,Delete all tags from a server. +server-tag-list,server list --tag,Get list of tags from a server. +server-tag-set,server set --tag,Set list of tags to a server. +server-topology,openstack server show --topology,Retrieve server topology. (Supported by API versions '2.78' - '2.latest') [hint: use '-- os-compute-api-version' flag to show help message for proper version] +service-delete,compute service delete,Delete the service. +service-disable,compute service set --disable,Disable the service. +service-enable,compute service set --enable,Enable the service. +service-force-down,compute service set --force,Force service to down. +service-list,compute service list,Show a list of all running services. +set-password,server set --root-password,Change the admin password for a server. +shelve,server shelve,Shelve a server. +shelve-offload,shelve --offload,Remove a shelved server from the compute node. +show,server show,Show details about the given server. +ssh,server ssh,SSH into a server. +start,server start,Start the server(s). +stop,server stop,Stop the server(s). +suspend,server suspend,Suspend a server. +trigger-crash-dump,server dump create,Trigger crash dump in an instance. +unlock,server unlock,Unlock a server. +unpause,server unpause,Unpause a server. +unrescue,server unrescue,Restart the server from normal boot disk again. +unshelve,server unshelve,Unshelve a server. +update,server set / unset,Update the name or the description for a server. +usage,usage show,Show usage data for a single tenant. +usage-list,usage list,List usage data for all tenants. +version-list,versions show --service compute,List all API versions. +volume-attach,server add volume,Attach a volume to a server. +volume-attachments,server volume list,List all the volumes attached to a server. +volume-detach,server remove volume,Detach a volume from a server. +volume-update,server volume update,Update volume attachment. +bash-completion,complete,Prints all of the commands and options to stdout so that the nova.bash_completion script doesn't have to hard code them. +help,help,Display help about this program or one of its subcommands. diff --git a/doc/source/cli/data/swift.csv b/doc/source/cli/data/swift.csv new file mode 100644 index 0000000000..87d781e271 --- /dev/null +++ b/doc/source/cli/data/swift.csv @@ -0,0 +1,10 @@ +delete,object delete / container delete,Delete a container or objects within a container. +download,object save / container save,Download objects from containers. +list,object list / container list,Lists the containers for the account or the objects for a container. +post,container create / object set / container set / object store account set,"Updates meta information for the account, container, or object." +copy,,"Copies object, optionally adds meta." +stat,object show / container show / object store account show,"Displays information for the account, container, or object." +upload,object create,Uploads files or directories to the given container. +capabilities,,List cluster capabilities. +tempurl,,Create a temporary URL. +auth,WONTFIX,Display auth related environment variables. diff --git a/doc/source/cli/decoder.rst b/doc/source/cli/decoder.rst new file mode 100644 index 0000000000..16810a4cbd --- /dev/null +++ b/doc/source/cli/decoder.rst @@ -0,0 +1,56 @@ +============= +Mapping Guide +============= + +The following is an incomplete mapping between legacy OpenStack CLIs and +OpenStackClient. Think of it as a magic decoder ring if you were using the +legacy CLIs and want to transition to OpenStack CLI. Command options are only +shown when necessary. + +``cinder CLI`` +-------------- + +.. csv-table:: + :header: "Cinder CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/cinder.csv + +``glance CLI`` +-------------- + +.. csv-table:: + :header: "Glance CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/glance.csv + +``keystone CLI`` +---------------- + +.. csv-table:: + :header: "Keystone CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/keystone.csv + +``neutron CLI`` +--------------- + +.. csv-table:: + :header: "Neutron CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/neutron.csv + +``nova CLI`` +------------ + +.. csv-table:: + :header: "Nova CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/nova.csv + +``swift CLI`` +------------- + +.. csv-table:: + :header: "Swift CLI", "OSC Equivalent", "Description" + :widths: 25, 25, 50 + :file: data/swift.csv diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 0000000000..9cb3b33a73 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,24 @@ +==================== + User Documentation +==================== + +.. toctree:: + :maxdepth: 2 + + Manual Page + command-list + commands + plugin-commands/index + authentication + interactive + decoder + backwards-incompatible + +.. NOTE(efried): Everything must be in a toctree but we don't want these to + show up to the reader. + +.. toctree:: + :glob: + :hidden: + + _hidden/* diff --git a/doc/source/cli/interactive.rst b/doc/source/cli/interactive.rst new file mode 100644 index 0000000000..4822d89f59 --- /dev/null +++ b/doc/source/cli/interactive.rst @@ -0,0 +1,111 @@ +================ +Interactive Mode +================ + +OpenStackClient has an interactive mode, similar to the :program:`virsh(1)` or +:program:`lvm(8)` commands on Linux. This mode is useful for executing a +series of commands without having to reload the CLI, or more importantly, +without having to re-authenticate to the cloud. + +Enter interactive mode by issuing the :command:`openstack` command with no +subcommand. An :code:`(openstack)` prompt will be displayed. Interactive mode +is terminated with :command:`exit`. + +Authentication +============== + +Authentication happens exactly as before, using the same global command line +options and environment variables, except it only happens once. +The credentials are cached and re-used for subsequent commands. This means +that to work with multiple clouds interactive mode must be ended so a +authentication to the second cloud can occur. + +Scripting +========= + +Using interactive mode inside scripts sounds counter-intuitive, but the same +single-authentication benefit can be achieved by passing OSC commands to +the CLI via :code:`stdin`. + +Sample session: + +.. code-block:: bash + + # assume auth credentials are in the environment + $ openstack + (openstack) keypair list + +--------+-------------------------------------------------+ + | Name | Fingerprint | + +--------+-------------------------------------------------+ + | bunsen | a5:da:0c:52:e8:52:42:a3:4f:b8:22:62:7b:e4:e8:89 | + | beaker | 45:9c:50:56:7c:fc:3a:b6:b5:60:02:2f:41:fb:a9:4c | + +--------+-------------------------------------------------+ + (openstack) image list + +--------------------------------------+----------------+ + | ID | Name | + +--------------------------------------+----------------+ + | 78b23835-c800-4d95-9d2a-e4de59a553d8 | OpenWRT r42884 | + | 2e45d43a-7c25-45f1-b012-06ac313e2f6b | Fedora 20 | + | de3a8396-3bae-42de-84bd-f4e398b8c320 | CirrOS | + +--------------------------------------+----------------+ + (openstack) flavor list + +--------------------------------------+----------+--------+--------+-----------+------+-------+-------------+-----------+-------------+ + | ID | Name | RAM | Disk | Ephemeral | Swap | VCPUs | RXTX Factor | Is Public | Extra Specs | + +--------------------------------------+----------+--------+--------+-----------+------+-------+-------------+-----------+-------------+ + | 12594680-56f7-4da2-8322-7266681b3070 | m1.small | 2048 | 20 | 0 | | 1 | | True | | + | 9274f903-0cc7-4a95-9124-1968018e355d | m1.tiny | 512 | 5 | 0 | | 1 | | True | | + +--------------------------------------+----------+--------+--------+-----------+------+-------+-------------+-----------+-------------+ + (openstack) server create --image CirrOS --flavor m1.small --key-name beaker sample-server + +-----------------------------+-------------------------------------------------+ + | Field | Value | + +-----------------------------+-------------------------------------------------+ + | config_drive | | + | created | 2014-11-19T18:08:41Z | + | flavor | m1.small (12594680-56f7-4da2-8322-7266681b3070) | + | id | 3a9a7f82-e902-4948-9245-52b045c76a1d | + | image | CirrOS (de3a8396-3bae-42de-84bd-f4e398b8c320) | + | key_name | bunsen | + | name | sample-server | + | progress | 0 | + | properties | | + | security_groups | [{u'name': u'default'}] | + | status | BUILD | + | tenant_id | 53c93c7952594d9ba16bd7072a165ce8 | + | updated | 2014-11-19T18:08:42Z | + | user_id | 1e4eea54c7124688a8092bec6e2dbee6 | + +-----------------------------+-------------------------------------------------+ + +A similar session can be issued all at once: + +.. code-block:: bash + + $ openstack < keypair list + > flavor show m1.small + > EOF + (openstack) +--------+-------------------------------------------------+ + | Name | Fingerprint | + +--------+-------------------------------------------------+ + | bunsen | a5:da:0c:52:e8:52:42:a3:4f:b8:22:62:7b:e4:e8:89 | + | beaker | 45:9c:50:56:7c:fc:3a:b6:b5:60:02:2f:41:fb:a9:4c | + +--------+-------------------------------------------------+ + (openstack) +----------------------------+--------------------------------------+ + | Field | Value | + +----------------------------+--------------------------------------+ + | OS-FLV-DISABLED:disabled | False | + | OS-FLV-EXT-DATA:ephemeral | 0 | + | disk | 20 | + | id | 12594680-56f7-4da2-8322-7266681b3070 | + | name | m1.small | + | os-flavor-access:is_public | True | + | ram | 2048 | + | swap | | + | vcpus | 1 | + +----------------------------+--------------------------------------+ + +Limitations +=========== + +The obvious limitations to Interactive Mode is that it is not a Domain Specific +Language (DSL), just a simple command processor. That means there are no variables +or flow control. diff --git a/doc/source/cli/man/openstack.rst b/doc/source/cli/man/openstack.rst new file mode 100644 index 0000000000..8f7124dd6d --- /dev/null +++ b/doc/source/cli/man/openstack.rst @@ -0,0 +1,625 @@ +.. _manpage: + +==================== +:program:`openstack` +==================== + +OpenStack Command Line + + +SYNOPSIS +======== + +:program:`openstack` [] [] + +:program:`openstack help` + +:program:`openstack` :option:`--help` + + +DESCRIPTION +=========== + +:program:`openstack` provides a common command-line interface to OpenStack APIs. It is generally +equivalent to the CLIs provided by the OpenStack project client libraries, but with +a distinct and consistent command structure. + + +AUTHENTICATION METHODS +====================== + +:program:`openstack` uses a similar authentication scheme as the OpenStack project CLIs, with +the credential information supplied either as environment variables or as options on the +command line. The primary difference is the use of 'project' in the name of the options +``OS_PROJECT_NAME``/``OS_PROJECT_ID`` over the old tenant-based names. + +:: + + export OS_AUTH_URL= + export OS_PROJECT_NAME= + export OS_USERNAME= + export OS_PASSWORD= # (optional) + +:program:`openstack` can use different types of authentication plugins provided by the keystoneclient library. The following default plugins are available: + +* ``token``: Authentication with a token +* ``password``: Authentication with a username and a password +* ``openid`` : Authentication using the protocol OpenID Connect + +Refer to the keystoneclient library documentation for more details about these plugins and their options, and for a complete list of available plugins. +Please bear in mind that some plugins might not support all of the functionalities of :program:`openstack`; for example the v3unscopedsaml plugin can deliver only unscoped tokens, some commands might not be available through this authentication method. + +Additionally, it is possible to use Keystone's service token to authenticate, by setting the options :option:`--os-token` and :option:`--os-endpoint` (or the environment variables :envvar:`OS_TOKEN` and :envvar:`OS_ENDPOINT` respectively). This method takes precedence over authentication plugins. + +.. NOTE:: + To use the ``v3unscopedsaml`` method, the lxml package will need to be installed. + +AUTHENTICATION USING FEDERATION +------------------------------- + +To use federated authentication, your configuration file needs the following: + +:: + + export OS_PROJECT_NAME= + export OS_PROJECT_DOMAIN_NAME= + export OS_AUTH_URL= + export OS_IDENTITY_API_VERSION=3 + export OS_AUTH_PLUGIN=openid + export OS_AUTH_TYPE=v3oidcpassword + export OS_USERNAME= + export OS_PASSWORD= + export OS_IDENTITY_PROVIDER= + export OS_CLIENT_ID= + export OS_CLIENT_SECRET= + export OS_OPENID_SCOPE= + export OS_PROTOCOL= + export OS_ACCESS_TOKEN_TYPE= + export OS_DISCOVERY_ENDPOINT= + export OS_ACCESS_TOKEN_ENDPOINT= + + +OPTIONS +======= + +:program:`openstack` takes global options that control overall behaviour and command-specific options that control the command operation. Most global options have a corresponding environment variable that may also be used to set the value. If both are present, the command-line option takes priority. The environment variable names are derived from the option name by dropping the leading dashes ('--'), converting each embedded dash ('-') to an underscore ('_'), and converting to upper case. + +:program:`openstack` recognizes the following global options: + +.. option:: --os-cloud + + :program:`openstack` will look for a ``clouds.yaml`` file that contains + a cloud configuration to use for authentication. See CLOUD CONFIGURATION + below for more information. + +.. option:: --os-auth-type + + The authentication plugin type to use when connecting to the Identity service. + + If this option is not set, :program:`openstack` will attempt to guess the + authentication method to use based on the other options. + + If this option is set, its version must match + :option:`--os-identity-api-version` + +.. option:: --os-auth-url + + Authentication URL + +.. option:: --os-endpoint + + Service ENDPOINT, when using a service token for authentication + +.. option:: --os-domain-name + + Domain-level authorization scope (by name) + +.. option:: --os-domain-id + + Domain-level authorization scope (by ID) + +.. option:: --os-project-name + + Project-level authentication scope (by name) + +.. option:: --os-project-id + + Project-level authentication scope (by ID) + +.. option:: --os-project-domain-name + + Domain name containing project + +.. option:: --os-project-domain-id + + Domain ID containing project + +.. option:: --os-username + + Authentication username + +.. option:: --os-password + + Authentication password + +.. option:: --os-token + + Authenticated token or service token + +.. option:: --os-user-domain-name + + Domain name containing user + +.. option:: --os-user-domain-id + + Domain ID containing user + +.. option:: --os-trust-id + + ID of the trust to use as a trustee user + +.. option:: --os-default-domain + + Default domain ID (Default: 'default') + +.. option:: --os-region-name + + Authentication region name + +.. option:: --os-cacert + + CA certificate bundle file + +.. option:: --verify` | :option:`--insecure + + Verify or ignore server certificate (default: verify) + +.. option:: --os-cert + + Client certificate bundle file + +.. option:: --os-key + + Client certificate key file + +.. option:: --os-identity-api-version + + Identity API version (Default: 2.0) + +.. option:: --os-XXXX-api-version + + Additional API version options will be available depending on the installed + API libraries. + +.. option:: --os-interface + + Interface type. Valid options are `public`, `admin` and `internal`. + +.. NOTE:: + If you switch to openstackclient from project specified clients, like: + novaclient, neutronclient and so on, please use `--os-interface` instead of + `--os-endpoint-type`. + +.. option:: --os-profile + + Performance profiling HMAC key for encrypting context data + + This key should be the value of one of the HMAC keys defined in the + configuration files of OpenStack services to be traced. + +.. option:: --os-beta-command + + Enable beta commands which are subject to change + +.. option:: --log-file + + Specify a file to log output. Disabled by default. + +.. option:: -v, --verbose + + Increase verbosity of output. Can be repeated. + +.. option:: -q, --quiet + + Suppress output except warnings and errors + +.. option:: --debug + + Show tracebacks on errors and set verbosity to debug + +.. option:: --help + + Show help message and exit + +.. option:: --timing + + Print API call timing information + +COMMANDS +======== + +To get a list of the available commands:: + + openstack --help + +To get a description of a specific command:: + + openstack help + +Note that the set of commands shown will vary depending on the API versions +that are in effect at that time. For example, to force the display of the +Identity v3 commands:: + + openstack --os-identity-api-version 3 --help + +.. option:: complete + + Print the bash completion functions for the current command set. + +.. option:: help + + Print help for an individual command + +Additional information on the OpenStackClient command structure and arguments +is available in the `OpenStackClient Commands`_ wiki page. + +.. _`OpenStackClient Commands`: https://wiki.openstack.org/wiki/OpenStackClient/Commands + +Command Objects +--------------- + +The list of command objects is growing longer with the addition of OpenStack +project support. The object names may consist of multiple words to compose a +unique name. Occasionally when multiple APIs have a common name with common +overlapping purposes there will be options to select which object to use, or +the API resources will be merged, as in the ``quota`` object that has options +referring to both Compute and Block Storage quotas. + +Command Actions +--------------- + +The actions used by OpenStackClient are defined with specific meaning to provide a consistent behavior for each object. Some actions have logical opposite actions, and those pairs will always match for any object that uses them. + + +CLOUD CONFIGURATION +=================== + +Working with multiple clouds can be simplified by keeping the configuration +information for those clouds in a local file. :program:`openstack` supports +using a ``clouds.yaml`` configuration file. + +Config Files +------------ + +:program:`openstack` will look for a file called clouds.yaml in the following +locations: + +* Current Directory +* ~/.config/openstack +* /etc/openstack + +The first file found wins. + +The keys match the :program:`openstack` global options but without the +``--os-`` prefix: + +:: + + clouds: + devstack: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: demo + username: demo + password: 0penstack + region_name: RegionOne + ds-admin: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: admin + username: admin + password: 0penstack + region_name: RegionOne + infra: + cloud: rackspace + auth: + project_id: 275610 + username: openstack + password: xyzpdq!lazydog + region_name: DFW,ORD,IAD + +In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken +from :file:`clouds-public.yaml`: + +:: + + public-clouds: + rackspace: + auth: + auth_url: 'https://identity.api.rackspacecloud.com/v2.0/' + +Authentication Settings +----------------------- + +OpenStackClient uses the Keystone authentication plugins so the required +auth settings are not always known until the authentication type is +selected. :program:`openstack` will attempt to detect a couple of common +auth types based on the arguments passed in or found in the configuration +file, but if those are incomplete it may be impossible to know which +auth type is intended. The :option:`--os-auth-type` option can always be +used to force a specific type. + +When :option:`--os-token` and :option:`--os-endpoint` are both present the +``token_endpoint`` auth type is selected automatically. If +:option:`--os-auth-url` and :option:`--os-username` are present ``password`` +auth type is selected. + +Logging Settings +---------------- + +:program:`openstack` can record the operation history by logging settings +in configuration file. Recording the user operation, it can identify the +change of the resource and it becomes useful information for troubleshooting. + +See :ref:`configuration` about Logging Settings for more details. + + +NOTES +===== + +The command list displayed in help output reflects the API versions selected. For +example, to see Identity v3 commands ``OS_IDENTITY_API_VERSION`` must be set to ``3``. + + +EXAMPLES +======== + +Show the detailed information for server ``appweb01``:: + + openstack \ + --os-project-name ExampleCo \ + --os-username demo --os-password secret \ + --os-auth-url http://localhost:5000:/v2.0 \ + server show appweb01 + +The same but using openid to authenticate in keystone:: + + openstack \ + --os-project-name ExampleCo \ + --os-auth-url http://localhost:5000:/v2.0 \ + --os-auth-plugin openid \ + --os-auth-type v3oidcpassword \ + --os-username demo-idp \ + --os-password secret-idp \ + --os-identity-provider google \ + --os-client-id the-id-assigned-to-keystone-in-google \ + --os-client-secret 3315162f-2b28-4809-9369-cb54730ac837 \ + --os-openid-scope 'openid email profile'\ + --os-protocol openid \ + --os-access-token-type access_token \ + --os-discovery-endpoint https://accounts.google.com/.well-known/openid-configuration \ + server show appweb01 + +The same command if the auth environment variables (:envvar:`OS_AUTH_URL`, :envvar:`OS_PROJECT_NAME`, +:envvar:`OS_USERNAME`, :envvar:`OS_PASSWORD`) are set:: + + openstack server show appweb01 + +Create a new image:: + + openstack image create \ + --disk-format=qcow2 \ + --container-format=bare \ + --public \ + --copy-from http://somewhere.net/foo.img \ + foo + + +FILES +===== + +:file:`~/.config/openstack/clouds.yaml` + Configuration file used by the :option:`--os-cloud` global option. + +:file:`~/.config/openstack/clouds-public.yaml` + Configuration file containing public cloud provider information such as + authentication URLs and service definitions. The contents of this file + should be public and sharable. ``clouds.yaml`` may contain references + to clouds defined here as shortcuts. + +:file:`~/.openstack` + Placeholder for future local state directory. This directory is intended to be shared among multiple OpenStack-related applications; contents are namespaced with an identifier for the app that owns it. Shared contents (such as :file:`~/.openstack/cache`) have no prefix and the contents must be portable. + + +ENVIRONMENT VARIABLES +===================== + +The following environment variables can be set to alter the behaviour of :program:`openstack`. Most of them have corresponding command-line options that take precedence if set. + +.. envvar:: OS_CLOUD + + The name of a cloud configuration in ``clouds.yaml``. + +.. envvar:: OS_AUTH_PLUGIN + + The authentication plugin to use when connecting to the Identity service, its version must match the Identity API version + +.. envvar:: OS_AUTH_URL + + Authentication URL + +.. envvar:: OS_AUTH_TYPE + + Define the authentication plugin that will be used to handle the + authentication process. One of the following: + + - ``v2password`` + - ``v2token`` + - ``v3password`` + - ``v3token`` + - ``v3oidcclientcredentials`` + - ``v3oidcpassword`` + - ``v3oidcauthorizationcode`` + - ``v3oidcaccesstoken`` + - ``v3totp`` + - ``v3tokenlessauth`` + - ``v3applicationcredential`` + - ``v3multifactor`` + +.. envvar:: OS_ENDPOINT + + Service ENDPOINT (when using the service token) + +.. envvar:: OS_DOMAIN_NAME + + Domain-level authorization scope (name or ID) + +.. envvar:: OS_PROJECT_NAME + + Project-level authentication scope (name or ID) + +.. envvar:: OS_PROJECT_DOMAIN_NAME + + Domain name or ID containing project + +.. envvar:: OS_USERNAME + + Authentication username + +.. envvar:: OS_TOKEN + + Authenticated or service token + +.. envvar:: OS_PASSWORD + + Authentication password + +.. envvar:: OS_USER_DOMAIN_NAME + + Domain name or ID containing user + +.. envvar:: OS_TRUST_ID + + ID of the trust to use as a trustee user + +.. envvar:: OS_DEFAULT_DOMAIN + + Default domain ID (Default: 'default') + +.. envvar:: OS_REGION_NAME + + Authentication region name + +.. envvar:: OS_CACERT + + CA certificate bundle file + +.. envvar:: OS_CERT + + Client certificate bundle file + +.. envvar:: OS_KEY + + Client certificate key file + +.. envvar:: OS_IDENTITY_API_VERSION + + Identity API version (Default: 2.0) + +.. envvar:: OS_XXXX_API_VERSION + + Additional API version options will be available depending on the installed + API libraries. + +.. envvar:: OS_INTERFACE + + Interface type. Valid options are `public`, `admin` and `internal`. + +.. envvar:: OS_PROTOCOL + + Define the protocol that is used to execute the federated authentication + process. It is used in the Keystone authentication URL generation process. + +.. envvar:: OS_IDENTITY_PROVIDER + + Define the identity provider of your federation that will be used. It is + used by the Keystone authentication URL generation process. The available + Identity Providers can be listed using the + :program:`openstack identity provider list` command + +.. envvar:: OS_CLIENT_ID + + Configure the ``CLIENT_ID`` that the CLI will use to authenticate the + application (OpenStack) in the Identity Provider. This value is defined on + the identity provider side. Do not confuse with the user ID. + +.. envvar:: OS_CLIENT_SECRET + + Configure the OS_CLIENT_SECRET that the CLI will use to authenticate the + CLI (OpenStack secret in the identity provider). + +.. envvar:: OS_OPENID_SCOPE + + Configure the attribute scopes that will be claimed by the Service Provider + (SP), in this case OpenStack, from the identity provider. These scopes and + which attributes each scope contains are defined in the identity provider + side. This parameter can receive multiple values separated by space. + +.. envvar:: OS_ACCESS_TOKEN_TYPE + + Define the type of access token that is used in the token introspection + process. + This variable can assume only one of the states ("access_token" or + "id_token"). + +.. envvar:: OS_DISCOVERY_ENDPOINT + + Configure the identity provider's discovery URL. This URL will provide a + discover document that contains metadata describing the identity provider + endpoints. This variable is optional if the variable + ``OS_ACCESS_TOKEN_ENDPOINT`` is defined. + +.. envvar:: OS_ACCESS_TOKEN_ENDPOINT + + Overrides the value presented in the discovery document retrieved from + ``OS_DISCOVERY_ENDPOINT`` URL request. This variable is optional if the + ``OS_DISCOVERY_ENDPOINT`` is configured. + +.. NOTE:: + If you switch to openstackclient from project specified clients, like: + novaclient, neutronclient and so on, please use `OS_INTERFACE` instead of + `OS_ENDPOINT_TYPE`. + +BUGS +==== + +Bug reports are accepted at the python-openstackclient Launchpad project +"https://bugs.launchpad.net/python-openstackclient". + + +AUTHORS +======= + +Please refer to the AUTHORS file distributed with OpenStackClient. + + +COPYRIGHT +========= + +Copyright 2011-2014 OpenStack Foundation and the authors listed in the AUTHORS file. + + +LICENSE +======= + +http://www.apache.org/licenses/LICENSE-2.0 + + +SEE ALSO +======== + +The `OpenStackClient page `_ +in the `OpenStack Docs `_ contains further +documentation. + +The individual OpenStack project CLIs, the OpenStack API references. diff --git a/doc/source/cli/plugin-commands/aodh.rst b/doc/source/cli/plugin-commands/aodh.rst new file mode 100644 index 0000000000..5d8b4332cf --- /dev/null +++ b/doc/source/cli/plugin-commands/aodh.rst @@ -0,0 +1,4 @@ +aodh +---- + +.. autoprogram-cliff:: openstack.alarming.v2 diff --git a/doc/source/cli/plugin-commands/barbican.rst b/doc/source/cli/plugin-commands/barbican.rst new file mode 100644 index 0000000000..224b274f42 --- /dev/null +++ b/doc/source/cli/plugin-commands/barbican.rst @@ -0,0 +1,4 @@ +barbican +-------- + +.. autoprogram-cliff:: openstack.key_manager.v1 diff --git a/doc/source/cli/plugin-commands/cyborg.rst b/doc/source/cli/plugin-commands/cyborg.rst new file mode 100644 index 0000000000..aedaa6b53d --- /dev/null +++ b/doc/source/cli/plugin-commands/cyborg.rst @@ -0,0 +1,4 @@ +cyborg +------ + +.. autoprogram-cliff:: openstack.accelerator.v2 diff --git a/doc/source/cli/plugin-commands/designate.rst b/doc/source/cli/plugin-commands/designate.rst new file mode 100644 index 0000000000..045072b243 --- /dev/null +++ b/doc/source/cli/plugin-commands/designate.rst @@ -0,0 +1,4 @@ +designate +--------- + +.. autoprogram-cliff:: openstack.dns.v2 diff --git a/doc/source/cli/plugin-commands/gnocchi.rst b/doc/source/cli/plugin-commands/gnocchi.rst new file mode 100644 index 0000000000..bbc7f6c8eb --- /dev/null +++ b/doc/source/cli/plugin-commands/gnocchi.rst @@ -0,0 +1,4 @@ +gnocchi +------- + +.. autoprogram-cliff:: openstack.metric.v1 diff --git a/doc/source/cli/plugin-commands/heat.rst b/doc/source/cli/plugin-commands/heat.rst new file mode 100644 index 0000000000..025561425a --- /dev/null +++ b/doc/source/cli/plugin-commands/heat.rst @@ -0,0 +1,4 @@ +heat +---- + +.. autoprogram-cliff:: openstack.orchestration.v1 diff --git a/doc/source/cli/plugin-commands/index.rst b/doc/source/cli/plugin-commands/index.rst new file mode 100644 index 0000000000..2622ee58b3 --- /dev/null +++ b/doc/source/cli/plugin-commands/index.rst @@ -0,0 +1,27 @@ +.. _plugin-commands: + +=============== +Plugin Commands +=============== + +.. toctree:: + :maxdepth: 1 + + aodh + barbican + cyborg + designate + gnocchi + heat + ironic + ironic-inspector + magnum + manila + mistral + neutron + octavia + placement + trove + watcher + zaqar + zun diff --git a/doc/source/cli/plugin-commands/ironic-inspector.rst b/doc/source/cli/plugin-commands/ironic-inspector.rst new file mode 100644 index 0000000000..7ac12618e2 --- /dev/null +++ b/doc/source/cli/plugin-commands/ironic-inspector.rst @@ -0,0 +1,4 @@ +ironic-inspector +---------------- + +.. autoprogram-cliff:: openstack.baremetal_introspection.v1 diff --git a/doc/source/cli/plugin-commands/ironic.rst b/doc/source/cli/plugin-commands/ironic.rst new file mode 100644 index 0000000000..d9254e9bd3 --- /dev/null +++ b/doc/source/cli/plugin-commands/ironic.rst @@ -0,0 +1,4 @@ +ironic +------ + +.. autoprogram-cliff:: openstack.baremetal.v1 diff --git a/doc/source/cli/plugin-commands/magnum.rst b/doc/source/cli/plugin-commands/magnum.rst new file mode 100644 index 0000000000..9b3f9f7e8a --- /dev/null +++ b/doc/source/cli/plugin-commands/magnum.rst @@ -0,0 +1,4 @@ +magnum +------ + +.. autoprogram-cliff:: openstack.container_infra.v1 diff --git a/doc/source/cli/plugin-commands/manila.rst b/doc/source/cli/plugin-commands/manila.rst new file mode 100644 index 0000000000..c42d6065f4 --- /dev/null +++ b/doc/source/cli/plugin-commands/manila.rst @@ -0,0 +1,4 @@ +manila +------ + +.. autoprogram-cliff:: openstack.share.v2 diff --git a/doc/source/cli/plugin-commands/mistral.rst b/doc/source/cli/plugin-commands/mistral.rst new file mode 100644 index 0000000000..5f538d29fa --- /dev/null +++ b/doc/source/cli/plugin-commands/mistral.rst @@ -0,0 +1,4 @@ +mistral +------- + +.. autoprogram-cliff:: openstack.workflow_engine.v2 diff --git a/doc/source/cli/plugin-commands/neutron.rst b/doc/source/cli/plugin-commands/neutron.rst new file mode 100644 index 0000000000..0167931f05 --- /dev/null +++ b/doc/source/cli/plugin-commands/neutron.rst @@ -0,0 +1,4 @@ +neutron +------- + +.. autoprogram-cliff:: openstack.neutronclient.v2 diff --git a/doc/source/cli/plugin-commands/octavia.rst b/doc/source/cli/plugin-commands/octavia.rst new file mode 100644 index 0000000000..640af1ace8 --- /dev/null +++ b/doc/source/cli/plugin-commands/octavia.rst @@ -0,0 +1,4 @@ +octavia +------- + +.. autoprogram-cliff:: openstack.load_balancer.v2 diff --git a/doc/source/cli/plugin-commands/placement.rst b/doc/source/cli/plugin-commands/placement.rst new file mode 100644 index 0000000000..203ecc2992 --- /dev/null +++ b/doc/source/cli/plugin-commands/placement.rst @@ -0,0 +1,4 @@ +placement +--------- + +.. autoprogram-cliff:: openstack.placement.v1 diff --git a/doc/source/cli/plugin-commands/trove.rst b/doc/source/cli/plugin-commands/trove.rst new file mode 100644 index 0000000000..43560d4e2b --- /dev/null +++ b/doc/source/cli/plugin-commands/trove.rst @@ -0,0 +1,4 @@ +trove +----- + +.. autoprogram-cliff:: openstack.database.v1 diff --git a/doc/source/cli/plugin-commands/watcher.rst b/doc/source/cli/plugin-commands/watcher.rst new file mode 100644 index 0000000000..9cf6dfeea0 --- /dev/null +++ b/doc/source/cli/plugin-commands/watcher.rst @@ -0,0 +1,4 @@ +watcher +------- + +.. autoprogram-cliff:: openstack.infra_optim.v1 diff --git a/doc/source/cli/plugin-commands/zaqar.rst b/doc/source/cli/plugin-commands/zaqar.rst new file mode 100644 index 0000000000..6415149029 --- /dev/null +++ b/doc/source/cli/plugin-commands/zaqar.rst @@ -0,0 +1,4 @@ +zaqar +----- + +.. autoprogram-cliff:: openstack.messaging.v2 diff --git a/doc/source/cli/plugin-commands/zun.rst b/doc/source/cli/plugin-commands/zun.rst new file mode 100644 index 0000000000..17baac557a --- /dev/null +++ b/doc/source/cli/plugin-commands/zun.rst @@ -0,0 +1,4 @@ +zun +--- + +.. autoprogram-cliff:: openstack.container.v1 diff --git a/doc/source/conf.py b/doc/source/conf.py index 6331470bc6..6ee3145558 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,9 +1,9 @@ -# -*- coding: utf-8 -*- # -# OpenStack Command Line Client documentation build configuration file, created by -# sphinx-quickstart on Wed May 16 12:05:58 2012. +# OpenStack Command Line Client documentation build configuration file, created +# by sphinx-quickstart on Wed May 16 12:05:58 2012. # -# This file is execfile()d with the current directory set to its containing dir. +# This file is execfile()d with the current directory set to its containing +# dir. # # Note that not all possible configuration values are present in this # autogenerated file. @@ -11,236 +11,280 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- +# -- General configuration ---------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'openstackdocstheme', + 'stevedore.sphinxext', + 'cliff.sphinxext', + 'sphinxcontrib.apidoc', +] -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] +# openstackdocstheme options +openstackdocs_repo_name = 'openstack/python-openstackclient' +openstackdocs_auto_name = False + +# Add project 'foo' to this list to enable the :foo-doc: role +openstackdocs_projects = [ + 'neutron', +] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +# templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. -project = u'OpenStack Command Line Client' -copyright = u'2012, OpenStack' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.1' -# The full version, including alpha/beta/rc tags. -release = '0.1' +project = 'OpenStack Command Line Client' +copyright = '2012-2013 OpenStack Foundation' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['**tests**'] -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'native' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +modindex_common_prefix = ['openstackclient.'] -# -- Options for HTML output --------------------------------------------------- +# -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +# html_theme_path = ["."] +# html_theme = '_theme' +html_theme = 'openstackdocs' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_static_path = ['_static'] # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'OpenStackCommandLineClientdoc' +# Add any paths that contain "extra" files, such as .htaccess or robots.txt +html_extra_path = ['_extra'] -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', +# -- Options for LaTeX output ------------------------------------------------- -# Additional stuff for the LaTeX preamble. -#'preamble': '', +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]) +# . latex_documents = [ - ('index', 'OpenStackCommandLineClient.tex', u'OpenStack Command Line Client Documentation', - u'OpenStack', 'manual'), + ( + 'index', + 'OpenStackCommandLineClient.tex', + 'OpenStack Command Line Client Documentation', + 'OpenStack', + 'manual', + ), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True -# -- Options for manual page output -------------------------------------------- +# -- Options for manual page output ------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'openstackcommandlineclient', u'OpenStack Command Line Client Documentation', - [u'OpenStack'], 1) + ( + 'cli/man/openstack', + 'openstack', + 'OpenStack Command Line Client', + ['OpenStack contributors'], + 1, + ), ] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False -# -- Options for Texinfo output ------------------------------------------------ +# -- Options for Texinfo output ----------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'OpenStackCommandLineClient', u'OpenStack Command Line Client Documentation', - u'OpenStack', 'OpenStackCommandLineClient', 'One line description of project.', - 'Miscellaneous'), + ( + 'index', + 'OpenStackCommandLineClient', + 'OpenStack Command Line Client Documentation', + 'OpenStack', + 'OpenStackCommandLineClient', + 'One line description of project.', + 'Miscellaneous', + ), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' + +# -- Options for cliff.sphinxext plugin --------------------------------------- -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +autoprogram_cliff_application = 'openstack' + +autoprogram_cliff_ignored = [ + '--help', + '--format', + '--column', + '--max-width', + '--fit-width', + '--print-empty', + '--prefix', + '--noindent', + '--quote', +] + +# Prevent cliff from generating "This command is provided by the +# python-openstackclient plugin." +autoprogram_cliff_app_dist_name = 'python-openstackclient' + +# -- Options for sphinxcontrib.apidoc ---------------------------------------- + +apidoc_module_dir = '../../openstackclient' +apidoc_excluded_paths = [ + 'volume/v3', + 'tests', +] +apidoc_output_dir = 'contributor/api' diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000000..b74bb3659b --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,290 @@ +.. _configuration: + +============= +Configuration +============= + +OpenStackClient is primarily configured using command line options and environment +variables. Most of those settings can also be placed into a configuration file to +simplify managing multiple cloud configurations. + +There is a relationship between the global options, environment variables and +keywords used in the configuration files that should make translation between +these three areas simple. + +Most global options have a corresponding environment variable that may also be +used to set the value. If both are present, the command-line option takes priority. +The environment variable names are derived from the option name by dropping the +leading dashes (--), converting each embedded dash (-) to an underscore (_), and +converting to upper case. + +The keyword names in the configurations files are derived from the global option +names by dropping the ``--os-`` prefix if present. + +Global Options +-------------- + +The :ref:`openstack manpage ` lists all of the global +options recognized by OpenStackClient and the default authentication plugins. + +Environment Variables +--------------------- + +The :ref:`openstack manpage ` also lists all of the +environment variables recognized by OpenStackClient and the default +authentication plugins. + +Configuration Files +------------------- + +clouds.yaml +~~~~~~~~~~~ + +:file:`clouds.yaml` is a configuration file that contains everything needed +to connect to one or more clouds. It may contain private information and +is generally considered private to a user. + +OpenStackClient looks for a file called :file:`clouds.yaml` in the following +locations: + +* current directory +* :file:`~/.config/openstack` +* :file:`/etc/openstack` + +The first file found wins. + +The keys match the :program:`openstack` global options but without the +``--os-`` prefix. + +:: + + clouds: + devstack: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: demo + username: demo + password: 0penstack + region_name: RegionOne + ds-admin: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: admin + username: admin + password: 0penstack + region_name: RegionOne + infra: + cloud: rackspace + auth: + project_id: 275610 + username: openstack + password: xyzpdq!lazydog + region_name: DFW,ORD,IAD + interface: internal + +In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken +from :file:`clouds-public.yaml` (see below). + +The first two entries are for two of the default users of the same DevStack +cloud. + +The third entry is for a Rackspace Cloud Servers account. It is equivalent +to the following options if the ``rackspace`` entry in :file:`clouds-public.yaml` +(below) is present: + +:: + + --os-auth-url https://identity.api.rackspacecloud.com/v2.0/ + --os-project-id 275610 + --os-username openstack + --os-password xyzpdq!lazydog + --os-region-name DFW + --os-interface internal + +and can be selected on the command line:: + + openstack --os-cloud infra server list + +Note that multiple regions are listed in the ``rackspace`` entry. An otherwise +identical configuration is created for each region. If ``-os-region-name`` is not +specified on the command line, the first region in the list is used by default. + +The selection of ``interface`` (as seen above in the ``rackspace`` entry) +is optional. For this configuration to work, every service for this cloud +instance must already be configured to support this type of interface. + +If you are using Identity v3 you need to specify the user and the project +domain name as shown in the example below: + +:: + + clouds: + devstack: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: demo + username: demo + password: 0penstack + user_domain_name: Default + project_domain_name: Default + region_name: RegionOne + +clouds-public.yaml +~~~~~~~~~~~~~~~~~~ + +:file:`clouds-public.yaml` is a configuration file that is intended to contain +public information about clouds that are common across a large number of users. +The idea is that :file:`clouds-public.yaml` could easily be shared among users +to simplify public cloud configuration. + +Similar to :file:`clouds.yaml`, OpenStackClient looks for +:file:`clouds-public.yaml` in the following locations: + +* current directory +* :file:`~/.config/openstack` +* :file:`/etc/openstack` + +The first file found wins. + +The keys here are referenced in :file:`clouds.yaml` ``cloud`` keys. Anything +that appears in :file:`clouds.yaml` + +:: + + public-clouds: + rackspace: + auth: + auth_url: 'https://identity.api.rackspacecloud.com/v2.0/' + +Debugging +~~~~~~~~~ +You may find the :ref:`configuration show ` +command helpful to debug configuration issues. It will display your current +configuration. + +Logging Settings +---------------- + +By setting `log_level` or `log_file` in the configuration +:file:`clouds.yaml`, a user may enable additional logging:: + + clouds: + devstack: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: demo + username: demo + password: 0penstack + region_name: RegionOne + operation_log: + logging: TRUE + file: /tmp/openstackclient_demo.log + level: info + ds-admin: + auth: + auth_url: http://192.168.122.10:5000/ + project_name: admin + username: admin + password: 0penstack + region_name: RegionOne + log_file: /tmp/openstackclient_admin.log + log_level: debug + +:dfn:`log_file`: ```` + Full path to logging file. +:dfn:`log_level`: ``error`` | ``info`` | ``debug`` + If log level is not set, ``warning`` will be used. + +If log level is ``info``, the following information is recorded: + +* cloud name +* user name +* project name +* CLI start time (logging start time) +* CLI end time +* CLI arguments +* CLI return value +* and any ``info`` messages. + +If log level is ``debug``, the following information is recorded: + +* cloud name +* user name +* project name +* CLI start time (logging start time) +* CLI end time +* CLI arguments +* CLI return value +* API request header/body +* API response header/body +* and any ``debug`` messages. + +When a command is executed, these logs are saved every time. Recording the user +operations can help to identify resource changes and provide useful information +for troubleshooting. + +If saving the output of a single command use the `--log-file` option instead. + +* `--log-file ` + +The logging level for `--log-file` can be set by using following options. + +* `-v, --verbose` +* `-q, --quiet` +* `--debug` + +Locale and Language Support +--------------------------- + +Full support for languages is included as of OpenStackClient 3.0.0. Here are a +few tips to ensure you have a correct configuration. + +Verify preferred python encoding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please perform the following to diagnose ensure locale settings are correct. +Run python interactively and print the preferred encoding value, e.g.: + +:: + + $ python -c "import locale; print locale.getpreferredencoding()" + +If the value is ``ascii`` or ``ANSI_X3.4-1968`` or any other equivalent name for +ASCII the problem is in your environment. You most likely do not have your LANG +environment variable set correctly. + +Check the LANG environment variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``LANG`` should be of the form: `lang_code`_`[region_code]`.`encoding`. +For example, it may look like: ``en_US.UTF-8`` + +The critical part here is the `encoding` value of ``UTF-8``. Python will look +up locale information and if it finds an encoding value, it will set the +encoding property of stdin, stdout and stderr to the value found in your +environment, if it's not defined in your environment it defaults to ASCII. + +Redirecting output +~~~~~~~~~~~~~~~~~~ + +The above only occurs if stdin, stdout and stderr are attached to a TTY. If +redirecting data the encoding on these streams will default to the default +encoding which is set in the `site.py` of your Python distribution, which +defaults to ASCII. A workaround for this is to set ``PYTHONIOENCODING`` to UTF8. + +:: + + $ PYTHONIOENCODING=utf-8 + +A final note about DevStack +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A common post devstack operation is to source the ``openrc`` file to set up +environment variables. Doing so will unset the default ``LANG`` environment +variable in your terminal, which will cause the preferred python encoding to +be ``ascii``. We recommend either setting these environment variables +independently or using the ``devstack`` or ``devstack-admin`` os-cloud profile. + +:: + + $ openstack project list --os-cloud devstack-admin diff --git a/doc/source/contributor/command-beta.rst b/doc/source/contributor/command-beta.rst new file mode 100644 index 0000000000..40ede67100 --- /dev/null +++ b/doc/source/contributor/command-beta.rst @@ -0,0 +1,108 @@ +.. _command-beta: + +============ +Command Beta +============ + +OpenStackClient releases do not always coincide with OpenStack +releases. This creates challenges when developing new OpenStackClient +commands for the current OpenStack release under development +since there may not be an official release of the REST API +enhancements necessary for the command. In addition, backwards +compatibility may not be guaranteed until an official OpenStack release. +To address these challenges, an OpenStackClient command may +be labeled as a beta command according to the guidelines +below. Such commands may introduce backwards incompatible +changes and may use REST API enhancements not yet released. +This also applies to command options associated with the beta +command object. + +See the examples below on how to label an entire command or +a specific option as a beta by updating the documentation +and implementation. + +The initial release note must label the new command or option +as a beta. No further release notes are required until the command +or option is no longer a beta. At which time, the beta label or +the command or option itself must be removed and a new release note +must be provided. + +Beta Command Example +-------------------- + +Documentation +~~~~~~~~~~~~~ + +The command documentation must label the command as a beta. + +example list +++++++++++++ + +List examples + +.. caution:: This is a beta command and subject to change. + Use global option ``--os-beta-command`` to + enable this command. + +.. program:: example list +.. code:: bash + + openstack example list + +Help +~~~~ + +The command help must label the command as a beta. + +.. code-block:: python + + class ShowExample(command.ShowOne): + """Display example details + + (Caution: This is a beta command and subject to change. + Use global option --os-beta-command to enable + this command) + """ + +Implementation +~~~~~~~~~~~~~~ + +The command must raise a ``CommandError`` exception if beta commands +are not enabled via ``--os-beta-command`` global option. + +.. code-block:: python + + def take_action(self, parsed_args): + self.validate_os_beta_command_enabled() + +Beta Option Example +------------------- + +Documentation +~~~~~~~~~~~~~ + +The option documentation must label the option as a beta. + +.. option:: --example + + Example + + .. caution:: This is a beta command option and subject + to change. Use global option ``--os-beta-command`` + to enable this command option. + +Implementation +~~~~~~~~~~~~~~ + +The option must not be added if beta commands are not +enabled via ``--os-beta-command`` global option. + +.. code-block:: python + + def get_parser(self, prog_name): + if self.app.options.os_beta_command: + parser.add_argument( + '--example', + metavar='', + help=_("Example") + ) diff --git a/doc/source/contributor/command-errors.rst b/doc/source/contributor/command-errors.rst new file mode 100644 index 0000000000..f47dfec7c3 --- /dev/null +++ b/doc/source/contributor/command-errors.rst @@ -0,0 +1,203 @@ +============== +Command Errors +============== + +Handling errors in OpenStackClient commands is fairly straightforward. An +exception is thrown and handled by the application-level caller. + +Note: There are many cases that need to be filled out here. The initial +version of this document considers the general command error handling as well +as the specific case of commands that make multiple REST API calls and how to +handle when one or more of those calls fails. + +General Command Errors +====================== + +The general pattern for handling OpenStackClient command-level errors is to +raise a CommandError exception with an appropriate message. This should include +conditions arising from arguments that are not valid/allowed (that are not otherwise +enforced by ``argparse``) as well as errors arising from external conditions. + +External Errors +--------------- + +External errors are a result of things outside OpenStackClient not being as +expected. + +Example +~~~~~~~ + +This example is taken from ``keypair create`` where the ``--public-key`` option +specifies a file containing the public key to upload. If the file is not found, +the ``IOError`` exception is trapped and a more specific ``CommandError`` +exception is raised that includes the name of the file that was attempted to be +opened. + +.. code-block:: python + + class CreateKeypair(command.ShowOne): + """Create new public key""" + + ## ... + + def take_action(self, parsed_args): + compute_client = self.app.client_manager.compute + + public_key = parsed_args.public_key + if public_key: + try: + with open( + os.path.expanduser(parsed_args.public_key), + "rb" + ) as p: + public_key = p.read() + except IOError as e: + msg = _("Key file %s not found: %s") + raise exceptions.CommandError( + msg % (parsed_args.public_key, e), + ) + + keypair = compute_client.create_keypair( + name=parsed_args.name, + public_key=public_key, + ) + + ## ... + +REST API Errors +=============== + +Most commands make a single REST API call via the supporting client library +or SDK. Errors based on HTML return codes are usually handled well by default, +but in some cases more specific or user-friendly messages need to be logged. +Trapping the exception and raising a CommandError exception with a useful +message is the correct approach. + +Multiple REST API Calls +----------------------- + +Some CLI commands make multiple calls to library APIs and thus REST APIs. +Most of the time these are ``create`` or ``set`` commands that expect to add or +change a resource on the server. When one of these calls fails, the behaviour +of the remainder of the command handler is defined as such: + +* Whenever possible, all API calls will be made. This may not be possible for + specific commands where the subsequent calls are dependent on the results of + an earlier call. + +* Any failure of an API call will be logged for the user + +* A failure of any API call results in a non-zero exit code + +* In the cases of failures in a ``create`` command a follow-up mode needs to + be present that allows the user to attempt to complete the call, or cleanly + remove the partially-created resource and re-try. + +The desired behaviour is for commands to appear to the user as idempotent +whenever possible, i.e. a partial failure in a ``set`` command can be safely +retried without harm. ``create`` commands are a harder problem and may need +to be handled by having the proper options in a set command available to allow +recovery in the case where the primary resource has been created but the +subsequent calls did not complete. + +Example 1 +~~~~~~~~~ + +This example is taken from the ``volume snapshot set`` command where ``--property`` +arguments are set using the volume manager's ``set_metadata()`` method, +``--state`` arguments are set using the ``reset_state()`` method, and the +remaining arguments are set using the ``update()`` method. + +.. code-block:: python + + class SetSnapshot(command.Command): + """Set snapshot properties""" + + ## ... + + def take_action(self, parsed_args): + volume_client = self.app.client_manager.volume + snapshot = utils.find_resource( + volume_client.volume_snapshots, + parsed_args.snapshot, + ) + + kwargs = {} + if parsed_args.name: + kwargs['name'] = parsed_args.name + if parsed_args.description: + kwargs['description'] = parsed_args.description + + result = 0 + if parsed_args.property: + try: + volume_client.volume_snapshots.set_metadata( + snapshot.id, + parsed_args.property, + ) + except SomeException: # Need to define the exceptions to catch here + LOG.error(_("Property set failed")) + result += 1 + + if parsed_args.state: + try: + volume_client.volume_snapshots.reset_state( + snapshot.id, + parsed_args.state, + ) + except SomeException: # Need to define the exceptions to catch here + LOG.error(_("State set failed")) + result += 1 + + try: + volume_client.volume_snapshots.update( + snapshot.id, + **kwargs + ) + except SomeException: # Need to define the exceptions to catch here + LOG.error(_("Update failed")) + result += 1 + + # NOTE(dtroyer): We need to signal the error, and a non-zero return code, + # without aborting prematurely + if result > 0: + raise SomeNonFatalException + +Example 2 +~~~~~~~~~ + +This example is taken from the ``network delete`` command which takes multiple +networks to delete. All networks will be deleted in a loop, which makes +multiple ``delete_network()`` calls. + +.. code-block:: python + + class DeleteNetwork(common.NetworkAndComputeCommand): + """Delete network(s)""" + + def update_parser_common(self, parser): + parser.add_argument( + 'network', + metavar="", + nargs="+", + help=_("Network(s) to delete (name or ID)") + ) + return parser + + def take_action(self, client, parsed_args): + ret = 0 + + for network in parsed_args.network: + try: + obj = client.find_network(network, ignore_missing=False) + client.delete_network(obj) + except Exception: + LOG.error(_("Failed to delete network with name " + "or ID %s."), network) + ret += 1 + + if ret > 0: + total = len(parsed_args.network) + msg = (_("Failed to delete %(ret)s of %(total)s networks.") + % {"ret": ret, "total": total}) + raise exceptions.CommandError(msg) diff --git a/doc/source/contributor/command-logs.rst b/doc/source/contributor/command-logs.rst new file mode 100644 index 0000000000..c203d02aee --- /dev/null +++ b/doc/source/contributor/command-logs.rst @@ -0,0 +1,73 @@ +============ +Command Logs +============ + +Logger usage in OpenStackClient is not exactly the same as those in other +OpenStack projects. The following basic rules should be followed. + +1. OpenStackClient uses python standard logging library instead of oslo.log + so that it will depend on oslo as little as possible. + +2. All logs except debug log need to be translated. The log message strings + that need to be translated should follow the rule of i18n guidelines: + https://docs.openstack.org/oslo.i18n/latest/user/guidelines.html + +3. There are mainly two kinds of logs in OpenStackClient: command specific + log and general log. Use different logger to record them. The examples + below will show the detail. + +Command specific log +==================== + +Command specific logs are those messages that used to record info, warning +and error generated from a specific command. OpenStackClient uses the logger +of the module the command belongs to to record the command specific logs. + +Example +~~~~~~~ + +This example shows how to log command specific logs in OpenStackClient. + +.. code-block:: python + + import logging + + from openstackclient.i18n import _ + + + LOG = logging.getLogger(__name__) # Get the logger of this module + + ## ... + + LOG.error(_("Error message")) + LOG.warning(_("Warning message")) + LOG.info(_("Info message")) + LOG.debug("Debug message") # Debug messages do not need to be translated + + ## ... + +General log +=========== + +General logs are those messages that not specific to any single command. Use +the logger of ``openstackclient.shell`` to record them. In each command class, +we can simply get this logger by ``self.app.log``. + +Example +~~~~~~~ + +This example shows how to log general logs in OpenStackClient. + +.. code-block:: python + + from openstackclient.i18n import _ + + + ## ... + + self.app.log.error(_("Error message")) + self.app.log.warning(_("Warning message")) + self.app.log.info(_("Info message")) + self.app.log.debug("Debug message") # Debug messages do not need to be translated + + ## ... diff --git a/doc/source/contributor/command-options.rst b/doc/source/contributor/command-options.rst new file mode 100644 index 0000000000..845d51f9f2 --- /dev/null +++ b/doc/source/contributor/command-options.rst @@ -0,0 +1,312 @@ +=============== +Command Options +=============== + +OpenStackClient commands all have a set of zero or more options unique to +the command, however there are of course ways in which these options are +common and consistent across all of the commands that include them. + +These are the set of guidelines for OSC developers that help keep the +interface and commands consistent. + +In some cases (like the boolean variables below) we use the same pattern +for defining and using options in all situations. The alternative of only +using it when necessary leads to errors when copy-n-paste is used for a +new command without understanding why or why not that instance is correct. + +The :ref:`hig` describes the guidelines for option names and usage. +In short: + +* All option names shall be GNU-style long names (two leading dashes). +* Some global options may have short names, generally limited to those defined + in support libraries such as `cliff `__. + +General Command Options +======================= + +Boolean Options +--------------- + +Boolean options for any command that sets a resource state, such as 'enabled' +or 'public', shall always have both positive and negative options defined. +The names of those options shall either be a naturally occurring pair of +words (in English) or a positive option and a negative option with `no-` +prepended (such as in the traditional GNU option usage) like `--share` and +`--no-share`. + +In order to handle those APIs that behave differently when a field is set to +`None` and when the field is not present in a passed argument list or dict, +each of the boolean options shall set its own variable to `True` as part of +a mutually exclusive group, rather than the more common configuration of +setting a single destination variable `True` or `False` directly. This allows +us to detect the situation when neither option is present (both variables will +be `False`) and act accordingly for those APIs where this matters. + +This also requires that each of the boolean values be tested in the +`take_action()` method to correctly set (or not) the underlying API field +values. + +.. option:: --enable + + Enable (default) + +.. option:: --disable + + Disable + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this: + +.. code-block:: python + + enable_group = parser.add_mutually_exclusive_group() + enable_group.add_argument( + '--enable', + action='store_true', + help=_('Enable (default)'), + ) + enable_group.add_argument( + '--disable', + action='store_true', + help=_('Disable '), + ) + +An example handler in `take_action()`: + +.. code-block:: python + + # This leaves 'enabled' undefined if neither option is present + if parsed_args.enable: + kwargs['enabled'] = True + if parsed_args.disable: + kwargs['enabled'] = False + +Options with Choices +-------------------- + +Some options have a specific set of values (or choices) that are valid. +These choices may be validated by the CLI. If the underlying API is stable +and the list of choices are unlikely to change then the CLI may validate +the choices. Otherwise, the CLI must defer validation of the choices to +the API. If the option has a default choice then it must be documented. + +Having the CLI validate choices will be faster and may provide a better +error message for the user if an invalid choice is specified +(for example: ``argument --test: invalid choice: 'choice4' (choose from 'choice1', 'choice2', 'choice3')``). +The trade-off is that CLI changes are required in order to take advantage +of new choices. + +Implementation +~~~~~~~~~~~~~~ + +An example parser declaration: + +.. code-block:: python + + choice_option.add_argument( + '--test', + metavar='', + choices=['choice1', 'choice2', 'choice3'], + help=_('Test type (choice1, choice2 or choice3)'), + ) + +Options with Multiple Values +---------------------------- + +Some options can be repeated to build a collection of values for a property. +Adding a value to the collection must be provided via the ``set`` action. +Removing a value from the collection must be provided via an ``unset`` action. +As a convenience, removing all values from the collection may be provided via a +``--no`` option on the ``set`` action and a ``--all`` option on ``unset`` +action. If both ``--no`` option and option are specified, the values specified +on the command would overwrite the collection property instead of appending on +the ``set`` action. The ``--all`` option must be part of a mutually exclusive +group with the related property option on the ``unset`` action, overwrite case +don't exist in ``unset`` action. + +An example behavior for ``set`` action: + +Append: + +.. code-block:: bash + + object set --example-property xxx + +Overwrite: + +.. code-block:: bash + + object set --no-example-property --example-property xxx + +The example below assumes a property that contains a list of unique values. +However, this example can also be applied to other collections using the +appropriate parser action and action implementation (e.g. a dict of key/value +pairs). Implementations will vary depending on how the REST API handles +adding/removing values to/from the collection and whether or not duplicate +values are allowed. + +Implementation +~~~~~~~~~~~~~~ + +An example parser declaration for `set` action: + +.. code-block:: python + + parser.add_argument( + '--no-example-property', + dest='no_example_property', + action='store_true', + help=_('Remove all example properties for this ' + '(specify both --no-example-property and --example-property' + ' to remove the current properties before setting' + ' new properties.)'), + ) + parser.add_argument( + '--example-property', + metavar='', + dest='example_property', + action='append', + help=_('Example property for this ' + '(repeat option to set multiple properties)'), + ) + +Please make `--no-example-property` be shown in front of `--example-property` +in the help, like above, that help make users aware of the processing order. + +An example handler in `take_action()` for `set` action: + +.. code-block:: python + + if parsed_args.no_example_property and parsed_args.example_property: + kwargs['example_property'] = parsed_args.example_property + elif parsed_args.no_example_property: + kwargs['example_property'] = [] + elif parsed_args.example_property: + kwargs['example_property'] = \ + resource_example_property + parsed_args.example_property + +An example parser declaration for `unset` action: + +.. code-block:: python + + example_property_group = parser.add_mutually_exclusive_group() + example_property_group.add_argument( + '--example-property', + metavar='', + dest='example_property', + action='append', + help=_('Example property for this ' + '(repeat option to remove multiple properties)'), + ) + example_property_group.add_argument( + '--all-example-property', + dest='all_example_property', + action='store_true', + help=_('Remove all example properties for this '), + ) + +An example handler in `take_action()` for `unset` action: + +.. code-block:: python + + if parsed_args.example_property: + kwargs['example_property'] = \ + list(set(resource_example_property) - \ + set(parsed_args.example_property)) + if parsed_args.all_example_property: + kwargs['example_property'] = [] + +Required Options +---------------- + +Some options have no default value and the API does not allow them to be +`None`, then these options are always required when users use the command +to which these options belong. + +Required options must be validated by the CLI to avoid omissions. The CLI +validation may provide an error message for the user if a required option +is not specified. +(for example: ``error: argument --test is required``) + +.. option:: --test + + Test option (required) + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this: + +.. code-block:: python + + parser.add_argument( + '--test', + metavar='', + required=True, + help=_('Test option (required)'), + ) + +List Command Options +==================== + +Additional Fields +----------------- + +Most list commands only return a subset of the available fields by default. +Additional fields are available with the `--long` option. All list +commands should allow `--long` even if they return all fields by default. + +.. option:: --long + + List additional fields in output + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this: + +.. code-block:: python + + parser.add_argument( + '--long', + action='store_true', + default=False, + help='List additional fields in output', + ) + +Pagination +---------- + +There are many ways to do pagination, some OpenStack APIs support it, some +don't. OpenStackClient attempts to define a single common way to specify +pagination on the command line. + +.. option:: --marker + + Anchor for paging (name or ID) + +.. option:: --limit + + Limit number of returned (*integer*) + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this: + +.. code-block:: python + + parser.add_argument( + "--marker", + metavar="", + help="Anchor for paging (name or ID)", + ) + + parser.add_argument( + "--limit", + metavar="", + type=int, + help="Limit the number of returned", + ) diff --git a/doc/source/contributor/command-wrappers.rst b/doc/source/contributor/command-wrappers.rst new file mode 100644 index 0000000000..cf4eece23a --- /dev/null +++ b/doc/source/contributor/command-wrappers.rst @@ -0,0 +1,52 @@ +====================== +Command Class Wrappers +====================== + +When we want to deprecate a command, policy says we need to alert the user. +We do this with a message logged at WARNING level before any command output +is emitted. + +OpenStackClient command classes are derived from the ``cliff`` classes. +Cliff uses Python's *entry points* mechanism for dispatching the parsed command +to the respective handler classes. This lends itself to modifying the +command execution at run-time. + +The obvious approach to adding the deprecation message would be to just add +the message to the command class ``take_action()`` method directly. But then +the various deprecations are scattered throughout the code base. If we +instead wrap the deprecated command class with a new class we can put all of +the wrappers into a separate, dedicated module. This also lets us leave the +original class unmodified and puts all of the deprecation bits in one place. + +This is an example of a minimal wrapper around a command class that logs a +deprecation message as a warning to the user then calls the original class. + +* Subclass the deprecated command. + +* Set class attribute ``deprecated`` to ``True`` to signal cliff to not + emit help text for this command. + +* Log the deprecation message at WARNING level and refer to the replacement + for the deprecated command in the log warning message. + +* Change the entry point class in ``setup.cfg`` to point to the new class. + +Example Deprecation Class +------------------------- + +.. code-block:: python + + class ListFooOld(ListFoo): + """List resources""" + + # This notifies cliff to not display the help for this command + deprecated = True + + log = logging.getLogger('deprecated') + + def take_action(self, parsed_args): + self.log.warning( + "%s is deprecated, use 'foobar list'", + getattr(self, 'cmd_name', 'this command'), + ) + return super(ListFooOld, self).take_action(parsed_args) diff --git a/doc/source/contributor/developing.rst b/doc/source/contributor/developing.rst new file mode 100644 index 0000000000..c6573b9ba6 --- /dev/null +++ b/doc/source/contributor/developing.rst @@ -0,0 +1,236 @@ +=============================== +Developing with OpenStackClient +=============================== + +Communication +------------- + +IRC Channel +~~~~~~~~~~~ + +The OpenStackClient team doesn't have regular meetings so if you have +questions or anything you want to discuss, come to our channel: +#openstack-sdks + + +Testing +------- + +Tox prerequisites and installation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Install the prerequisites for Tox: + +* On Ubuntu or Debian: + + .. code-block:: bash + + $ apt-get install gcc gettext python3-dev libxml2-dev libxslt1-dev \ + zlib1g-dev + + You may need to use pip install for some packages. + +* On RHEL or CentOS including Fedora: + + .. code-block:: bash + + $ yum install gcc python3-devel libxml2-devel libxslt-devel + +* On openSUSE or SUSE linux Enterprise: + + .. code-block:: bash + + $ zypper install gcc python3-devel libxml2-devel libxslt-devel + +Install python-tox: + +.. code-block:: bash + + $ pip install tox + +To run the full suite of tests maintained within OpenStackClient. + +.. code-block:: bash + + $ tox + +.. NOTE:: + + The first time you run ``tox``, it will take additional time to build + virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild + your virtualenv in a similar manner. + +To run tests for one or more specific test environments (for example, the most +common configuration of the latest Python version and PEP-8), list the +environments with the ``-e`` option, separated by spaces: + +.. code-block:: bash + + $ tox -e py38,pep8 + +See ``tox.ini`` for the full list of available test environments. + +Running functional tests +~~~~~~~~~~~~~~~~~~~~~~~~ + +OpenStackClient also maintains a set of functional tests that are optimally +designed to be run against OpenStack's gate. Optionally, a developer may +choose to run these tests against any OpenStack deployment, however depending +on the services available, results vary. + +To run the entire suite of functional tests: + +.. code-block:: bash + + $ tox -e functional + +To run a specific functional test: + +.. code-block:: bash + + $ tox -e functional -- --regex tests.functional.compute.v2.test_server + +Running with PDB +~~~~~~~~~~~~~~~~ + +Using PDB breakpoints with ``tox`` and ``testr`` normally does not work since +the tests fail with a `BdbQuit` exception rather than stopping at the +breakpoint. + +To run with PDB breakpoints during testing, use the ``debug`` ``tox`` +environment. For example, passing a test name since you will normally only want +to run the test that hits your breakpoint: + +.. code-block:: bash + + $ tox -e debug openstackclient.tests.identity.v3.test_group + +For reference, the `debug`_ ``tox`` environment implements the instructions + +.. _`debug`: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests + + +Coding Style +------------ + +OpenStackClient uses `flake8`__ along with `hacking`__, an OpenStack-specific +superset of ``flake8`` rules, to enforce coding style. This can be run manually +using ``tox``: + +.. code-block:: bash + + $ tox -e pep8 + +Alternatively, you can use the `pre-commit framework`__ to allow running of +some linters on each commit. This must be enabled locally to function: + +.. code-block:: bash + + $ pip install --user pre-commit + $ pre-commit install --allow-missing-config + +.. __: https://flake8.pycqa.org/en/latest/ +.. __: https://docs.openstack.org/hacking/latest/user/hacking.html +.. __: https://pre-commit.com/ + + +Documentation +------------- + +The documentation is generated with Sphinx using the ``tox`` command. To +create HTML docs, run the commands: + +.. code-block:: bash + + $ tox -e docs + +The resultant HTML will be in the ``doc/build/html`` directory. + + +Release Notes +------------- + +The release notes for a patch should be included in the patch. See the +`Project Team Guide`_ for more information on using reno in OpenStack. + +.. _`Project Team Guide`: http://docs.openstack.org/project-team-guide/release-management.html#managing-release-notes + +If any of the following applies to the patch, a release note is required: + +* The deployer needs to take an action when upgrading +* The plugin interface changes +* A new feature is implemented +* A command or option is removed +* Current behavior is changed +* A security bug is fixed + +Reno is used to generate release notes. Use the commands: + +.. code-block:: bash + + $ tox -e venv -- reno new + +Then edit the sample file that was created and push it with your change. + +To run the commands and see results: + +.. code-block:: bash + + $ git commit # Commit the change because reno scans git log. + + $ tox -e releasenotes + +At last, look at the generated release notes files in ``releasenotes/build/html`` in your browser. + + +Testing new code +---------------- + +If a developer wants to test new code (feature, command or option) that +they have written, OpenStackClient may be installed from source by running +the following commands in the base directory of the project: + +.. code-block:: bash + + $ python setup.py develop + +or + +.. code-block:: bash + + $ pip install -e . + +Standardize Import Format +~~~~~~~~~~~~~~~~~~~~~~~~~ + +More information about Import Format, see `Import Order Guide +`__. + +The import order shows below: + +.. code-block:: none + + {{stdlib imports in human alphabetical order}} + \n + {{third-party lib imports in human alphabetical order}} + \n + {{project imports in human alphabetical order}} + \n + \n + {{begin your code}} + +Example +^^^^^^^ + +.. code-block:: python + + import copy + import fixtures + import os + + from osc_lib.api import auth + from osc_lib import utils + + from openstackclient import shell + from openstackclient.tests import utils + from unittest import mock diff --git a/doc/source/contributor/humaninterfaceguide.rst b/doc/source/contributor/humaninterfaceguide.rst new file mode 100644 index 0000000000..db6d7987b9 --- /dev/null +++ b/doc/source/contributor/humaninterfaceguide.rst @@ -0,0 +1,723 @@ +.. _hig: + +===================== +Human Interface Guide +===================== + +*Note: This page covers the OpenStackClient CLI only but looks familiar +because it was derived from the Horizon HIG.* + +Overview +======== + +What is a HIG? +The Human Interface Guidelines document was created for OpenStack developers +in order to direct the creation of new OpenStackClient command interfaces. + +Personas +======== + +Personas are archetypal users of the system. Keep these types of users in +mind when designing the interface. + +Alice the admin +--------------- + +Alice is an administrator who is responsible for maintaining the OpenStack +cloud installation. She has many years of experience with Linux systems +administration. + +Darren the deployer +------------------- + +Darren is responsible for doing the initial OpenStack deployment on the +host machines. + +Emile the end-user +------------------ + +Emile uses the cloud to do software development inside of the virtual +machines. She uses the command-line tools because she finds it quicker +than using the dashboard. + +Principles +========== + +The principles established in this section define the high-level priorities +to be used when designing and evaluating interactions for the OpenStack +command line interface. Principles are broad in scope and can be considered +the philosophical foundation for the OpenStack experience; while they may +not describe the tactical implementation of design, they should be used +when deciding between multiple courses of design. + +A significant theme for designing for the OpenStack experience concerns +focusing on common uses of the system rather than adding complexity to support +functionality that is rarely used. + +Consistency +----------- + +Consistency between OpenStack experiences will ensure that the command line +interface feels like a single experience instead of a jumble of disparate +products. Fractured experiences only serve to undermine user expectations +about how they should interact with the system, creating an unreliable user +experience. To avoid this, each interaction and visual representation within +the system must be used uniformly and predictably. The architecture and elements +detailed in this document will provide a strong foundation for establishing a +consistent experience. + +Example Review Criteria +~~~~~~~~~~~~~~~~~~~~~~~ + +* Do the command actions adhere to a consistent application of actions? +* Has a new type of command subject or output been introduced? +* Does the design use command elements (options and arguments) as defined? + (See Core Elements.) +* Can any newly proposed command elements (actions or subjects) be accomplished + with existing elements? + +* Does the design adhere to the structural model of the core experience? + (See Core Architecture.) +* Are any data objects displayed or manipulated in a way contradictory to how + they are handled elsewhere in the core experience? + +Simplicity +---------- + +To best support new users and create straight forward interactions, designs +should be as simple as possible. When crafting new commands, designs should +minimize the amount of noise present in output: large amounts of +nonessential data, overabundance of possible actions and so on. Designs should +focus on the intent of the command, requiring only the necessary components +and either removing superfluous elements or making +them accessible through optional arguments. An example of this principle occurs +in OpenStack's use of tables: only the most often used columns are shown by +default. Further data may be accessed through the output control options, +allowing users to specify the types of data that they find useful in their +day-to-day work. + +Example Review Criteria +~~~~~~~~~~~~~~~~~~~~~~~ + +* Can options be used to combine otherwise similar commands? + +* How many of the displayed elements are relevant to the majority of users? +* If multiple actions are required for the user to complete a task, is each + step required or can the process be more efficient? + +User-Centered Design +-------------------- + +Commands should be design based on how a user will interact with the system +and not how the system's backend is organized. While database structures and +APIs may define what is possible, they often do not define good user +experience; consider user goals and the way in which users will want to +interact with their data, then design for these work flows and mold the +interface to the user, not the user to the interface. + +Commands should be discoverable via the interface itself. + +To determine a list of available commands, use the ``-h`` or +``--help`` options: + +.. code-block:: bash + + $ openstack --help + +For help with an individual command, use the ``help`` command: + +.. code-block:: bash + + $ openstack help server create + +Example Review Criteria +~~~~~~~~~~~~~~~~~~~~~~~ + +* How quickly can a user figure out how to accomplish a given task? +* Has content been grouped and ordered according to usage relationships? +* Do work flows support user goals or add complexity? + +Transparency +------------ + +Make sure users understand the current state of their infrastructure and +interactions. For example, users should be able to access information about +the state of each machine/virtual machine easily, without having to actively +seek out this information. Whenever the user initiates an action, make sure +a confirmation is displayed[1] to show that an input has been received. Upon +completion of a process, make sure the user is informed. Ensure that the user +never questions the state of their environment. + +[1] This goes against the common UNIX philosophy of only reporting error +conditions and output that is specifically requested. + +Example Review Criteria +~~~~~~~~~~~~~~~~~~~~~~~ + +* Does the user receive feedback when initiating a process? +* When a process is completed? +* Does the user have quick access to the state of their infrastructure? + + +Architecture +============ + +Command Structure +----------------- + +OpenStackClient has a consistent and predictable format for all of its commands. + +* The top level command name is ``openstack`` +* Sub-commands take the form: + +.. code-block:: bash + + openstack [] [] [] + +Subcommands shall have three distinct parts to its commands (in order that they appear): + +* global options +* command object(s) and action +* command options and arguments + +Output formats: + +* user-friendly tables with headers, etc +* machine-parsable delimited + +.. note:: + + A note on terminology. An **argument** is a positional parameter to the + command. As discussed later, these should be used sparingly in + OpenStackClient. An **option** - also known as a **flag** - is a named + parameter denoted with either a hyphen and a single-letter name (``-r``) or + a double hyphen and a multiple-letter name (``--recursive``). They may or + may not also include a user-specified value (``--file foo.txt`` or + ``--file=foo.txt``). + + For more information on this topic and CLIs in general, refer to the + excellent `Command Line Interface Guidelines website`__. + + .. __: https://clig.dev/#arguments-and-flags + +Global Options +~~~~~~~~~~~~~~ + +Global options are global in the sense that they apply to every command +invocation regardless of action to be performed. They include authentication +credentials and API version selection. Most global options have a corresponding +environment variable that may also be used to set the value. If both are present, +the command-line option takes priority. The environment variable names are derived +from the option name by dropping the leading dashes (``--``), converting each embedded +dash (``-``) to an underscore (``_``), and converting to upper case. + +* Global options shall always have a long option name, certain common options may + also have short names. Short names should be reserved for global options to limit + the potential for duplication and multiple meanings between commands given the + limited set of available short names. + +* All long options names shall begin with two dashes (``--``) and use a single dash + (``-``) internally between words (``--like-this``). Underscores (``_``) shall not + be used in option names. + +* Authentication options conform to the common CLI authentication guidelines in + :ref:`authentication`. + +For example, ``--os-username`` can be set from the environment via +``OS_USERNAME``. + +``--help`` +++++++++++ + +The standard ``--help`` global option displays the documentation for invoking +the program and a list of the available commands on standard output. All other +options and commands are ignored when this is present. The traditional short +form help option (``-h``) is also available. + +``--version`` ++++++++++++++ + +The standard ``--version`` option displays the name and version on standard +output. All other options and commands are ignored when this is present. + +Objects and Actions +~~~~~~~~~~~~~~~~~~~ + +Commands consist of an object, described by one or more words, followed by an +action. :: + + + +For example: + +* ``group create`` +* ``server set`` +* ``volume type list`` + +(note that ``volume type`` is a two-word single object) + +Some commands require two objects. These commands have the primary object ahead of the +action and the secondary object after the action. In badly formed English it is +expressed as "(Take) object-1 (and perform) action (using) object-2 (to it)." :: + + + +For example: + +* ``group add user`` +* ``aggregate add host`` +* ``image remove project`` + +Object names are always specified in command in their singular form. This is +contrary to natural language use. + +``help`` +++++++++ + +The ``help`` command is unique as it appears in front of a normal command +and displays the help text for that command rather than execute it. + +Arguments +~~~~~~~~~ + +Commands that interact with a specific instance of an object should accept a +single argument. This argument should be a name or identifier for the object. +:: + + [] + +For example: + +* ``group create `` +* ``server set `` + +(note that ``volume type`` is a two-word single object) + +For commands that require two objects, the commands should accept two +arguments when interacting with specific instances of the two objects. These +arguments should appear in the same order as the objects. :: + + [ ] + +For example: + +* ``group add user `` +* ``aggregate add host `` +* ``image remove project `` + +Options +~~~~~~~ + +Each command may have its own set of options distinct from the global options. +They follow the same style as the global options and always appear between +the command and any arguments the command requires. + +Command options should only have long names. The small range of available short +names makes it hard for a single short option name to have a consistent meaning +across multiple commands. + +Option Forms +++++++++++++ + +* **datetime**: Datetime options shall accept a value in `ISO-8061`__ format. + For example, you can list servers last modified before a given date using + ``--changes-before``. :: + + server list --changes-before 2020-01-01T12:30:00+00:00 + +* **list**: List options shall be passed via multiple options rather than as + a single delimited option. For example, you can set multiple properties on a + compute flavor using multiple ``--property`` options. :: + + flavor set --property quota:read_bytes_sec=10240000 \ + --property quota:write_bytes_sec=10240000 \ + + +* **boolean**: Boolean options shall use a form of ``--|--`` + (preferred) or ``--