diff --git a/.coveragerc b/.coveragerc index 2651b2ffef..8dc0326549 100644 --- a/.coveragerc +++ b/.coveragerc @@ -1,7 +1,7 @@ [run] branch = True source = openstackclient -omit = openstackclient/openstack/* +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 29b5574ce2..54cdd4fccf 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ *~ .coverage .idea +.stestr/ .testrepository .tox AUTHORS @@ -16,7 +17,7 @@ ChangeLog dist # Doc related doc/build -doc/source/api/ +doc/source/contributor/api/ # Development environment files .project .pydevproject 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/.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/.testr.conf b/.testr.conf deleted file mode 100644 index 90c80c1873..0000000000 --- a/.testr.conf +++ /dev/null @@ -1,9 +0,0 @@ -[DEFAULT] -test_command=OS_STDOUT_CAPTURE=${OS_STDOUT_CAPTURE:-1} \ - OS_STDERR_CAPTURE=${OS_STDERR_CAPTURE:-1} \ - OS_TEST_TIMEOUT=${OS_TEST_TIMEOUT:-60} \ - ${PYTHON:-python} -m subunit.run discover -t ./ ${OS_TEST_PATH:-./openstackclient/tests} $LISTOPT $IDOPTION - -test_id_option=--load-list $IDFILE -test_list_option=--list -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 index de9324ec7f..74b442ef66 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,16 +1,27 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps documented at: +The source repository for this project can be found at: - http://docs.openstack.org/infra/manual/developers.html#development-workflow + https://opendev.org/openstack/python-openstackclient -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: +Pull requests submitted through GitHub are not monitored. - http://docs.openstack.org/infra/manual/developers.html#development-workflow +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: -Pull requests submitted through GitHub will be ignored. + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html -Bugs should be filed on Launchpad, not GitHub: +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.rst b/HACKING.rst index e6c8d07827..432d19f4e4 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -2,11 +2,12 @@ OpenStack Style Commandments ============================ - Step 1: Read the OpenStack Style Commandments - http://docs.openstack.org/developer/hacking/ + https://docs.openstack.org/hacking/latest/ - Step 2: Read on General ------- + - thou shalt not violate causality in our time cone, or else Docstrings @@ -31,7 +32,7 @@ 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. +line indented to the starting line level. :: unnecessarily_long_function_name( 'string one', @@ -39,70 +40,3 @@ line indented to the starting line level. kwarg1=constants.ACTIVE, kwarg2=['a', 'b', 'c'], ) - -Text encoding -------------- - -Note: this section clearly has not been implemented in this project yet, it is -the intention to do so. - -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: - - infile = open('testfile', 'r') - mystring = infile.readline() - myreturnstring = do_some_magic_with(mystring) - outfile.write(myreturnstring) - - RIGHT: - - infile = open('testfile', 'r') - mystring = infile.readline() - mytext = mystring.decode('utf-8') - returntext = do_some_magic_with(mytext) - returnstring = returntext.encode('utf-8') - outfile.write(returnstring) - -Python 3.x Compatibility ------------------------- - -OpenStackClient strives to be Python 3.3 compatible. Common guidelines: - -* Convert print statements to functions: print statements should be converted - to an appropriate log or other output mechanism. -* Use six where applicable: x.iteritems is converted to six.iteritems(x) - for example. - -Running Tests -------------- - -Note: Oh boy, are we behind on writing tests. But they are coming! - -The testing system is based on a combination of tox and testr. If you just -want to run the whole suite, run `tox` and all will be fine. However, if -you'd like to dig in a bit more, you might want to learn some things about -testr itself. A basic walkthrough for OpenStack can be found at -http://wiki.openstack.org/testr diff --git a/README.rst b/README.rst index 340a0ea9eb..af3837a351 100644 --- a/README.rst +++ b/README.rst @@ -3,91 +3,227 @@ OpenStackClient =============== .. image:: https://img.shields.io/pypi/v/python-openstackclient.svg - :target: https://pypi.python.org/pypi/python-openstackclient/ + :target: https://pypi.org/project/python-openstackclient/ :alt: Latest Version -.. image:: https://img.shields.io/pypi/dm/python-openstackclient.svg - :target: https://pypi.python.org/pypi/python-openstackclient/ - :alt: Downloads - -OpenStackClient (aka OSC) is a command-line client for OpenStack that brings -the command set for Compute, Identity, Image, Object Store and Block Storage -APIs together in a single shell with a uniform command structure. +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. The primary goal is to provide a unified shell command structure and a common language to describe operations in OpenStack. -* `PyPi`_ - package installation -* `Online Documentation`_ -* `Launchpad project`_ - release management -* `Blueprints`_ - feature specifications -* `Bugs`_ - issue tracking -* `Source`_ -* `Developer` - getting started as a developer -* `Contributing` - contributing code -* `Testing` - testing code -* IRC: #openstack-sdks on Freenode (irc.freenode.net) -* License: Apache 2.0 - -.. _PyPi: https://pypi.python.org/pypi/python-openstackclient -.. _Online Documentation: http://docs.openstack.org/developer/python-openstackclient/ -.. _Launchpad project: https://launchpad.net/python-openstackclient -.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient -.. _Bugs: https://bugs.launchpad.net/python-openstackclient -.. _Source: https://git.openstack.org/cgit/openstack/python-openstackclient -.. _Developer: http://docs.openstack.org/project-team-guide/project-setup/python.html -.. _Contributing: http://docs.openstack.org/infra/manual/developers.html -.. _Testing: http://docs.openstack.org/developer/python-openstackclient/developing.html#testing - Getting Started =============== -OpenStack Client can be installed from PyPI using pip:: +OpenStack Client can be installed from PyPI using pip: - pip install python-openstackclient +.. code-block:: shell -There are a few variants on getting help. A list of global options and supported -commands is shown with ``--help``:: + python3 -m pip install python-openstackclient - openstack --help +You can use ``--help`` or the ``help`` command to get a list of global options +and supported commands: -There is also a ``help`` command that can be used to get help text for a specific -command:: +.. code-block:: shell + openstack --help openstack help - openstack help server create -Configuration -============= +You can also get help for a specific command: -The CLI is configured via environment variables and command-line -options as listed in http://docs.openstack.org/developer/python-openstackclient/authentication.html. +.. code-block:: shell -Authentication using username/password is most commonly used:: + openstack server create --help + openstack help server create + +You can add support for additional services by installing their clients. For +example, to add support for the DNS service (designate): + +.. code-block:: shell - export OS_AUTH_URL= - export OS_PROJECT_NAME= - export OS_USERNAME= - export OS_PASSWORD= # (optional) + python3 -m pip install python3-designateclient -The corresponding command-line options look very similar:: +A ``Dockerfile`` is provided for your convenience in the repository. You can +use this to build your own container images: - --os-auth-url - --os-project-name - --os-username - [--os-password ] +.. code-block:: shell -If a password is not provided above (in plaintext), you will be interactively -prompted to provide one securely. + git clone https://opendev.org/openstack/python-openstackclient + cd python-openstackclient + podman build . -t example.com/myuser/openstackclient -Authentication may also be performed using an already-acquired token -and a URL pointing directly to the service API that presumably was acquired -from the Service Catalog:: +For more information the available options and commands, refer to the `Users +Guide`__. - export OS_TOKEN= - export OS_URL= +.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html -The corresponding command-line options look very similar:: +Configuration +============= - --os-token - --os-url +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/babel.cfg b/babel.cfg deleted file mode 100644 index efceab818b..0000000000 --- a/babel.cfg +++ /dev/null @@ -1 +0,0 @@ -[python: **.py] 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/ext/apidoc.py b/doc/ext/apidoc.py deleted file mode 100644 index 5e18385a6d..0000000000 --- a/doc/ext/apidoc.py +++ /dev/null @@ -1,43 +0,0 @@ -# Copyright 2014 OpenStack Foundation -# -# 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. - -import os.path as path - -from sphinx import apidoc - - -# NOTE(blk-u): pbr will run Sphinx multiple times when it generates -# documentation. Once for each builder. To run this extension we use the -# 'builder-inited' hook that fires at the beginning of a Sphinx build. -# We use ``run_already`` to make sure apidocs are only generated once -# even if Sphinx is run multiple times. -run_already = False - - -def run_apidoc(app): - global run_already - if run_already: - return - run_already = True - - package_dir = path.abspath(path.join(app.srcdir, '..', '..', - 'openstackclient')) - source_dir = path.join(app.srcdir, 'api') - apidoc.main(['apidoc', package_dir, '-f', - '-H', 'openstackclient Modules', - '-o', source_dir]) - - -def setup(app): - app.connect('builder-inited', run_apidoc) 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/authentication.rst b/doc/source/authentication.rst deleted file mode 100644 index a3986ee414..0000000000 --- a/doc/source/authentication.rst +++ /dev/null @@ -1,144 +0,0 @@ -============== -Authentication -============== - -OpenStackClient leverages `python-keystoneclient`_ authentication -plugins to support a number of different authentication methods. - -.. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/authentication-plugins.html - -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 - (described below as token/endpoint) in that a token and an authentication - URL are supplied and the plugin retrieves a new token. - [Required: ``--os-auth-url``, ``--os-token``] -* **Token/Endpoint**: This is the original token authentication (known as 'token - flow' in the early CLI documentation in the OpenStack wiki). It requires - a token and a direct endpoint that is used in the API call. The difference - from the new Token type is this token is used as-is, no call is made - to the Identity service from the client. This type is most often used to - bootstrap a Keystone server where the token is the ``admin_token`` configured - in ``keystone.conf``. It will also work with other services and a regular - scoped token such as one obtained from a ``token issue`` command. - [Required: ``--os-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-url`` and ``--os-token`` are both present ``token_endpoint`` - is selected - * 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`` 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 diff --git a/doc/source/backwards-incompatible.rst b/doc/source/backwards-incompatible.rst deleted file mode 100644 index da3c1b6417..0000000000 --- a/doc/source/backwards-incompatible.rst +++ /dev/null @@ -1,238 +0,0 @@ -============================== -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 :doc:`command-beta` are exempt from -this backwards incompatible change handling. - -Backwards Incompatible Changes -============================== - -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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.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.openstack.org/#/c/281088/ - -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.openstack.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.openstack.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.openstack.org/#/q/project:openstack/python-openstackclient+AND+message:BackwardsIncompatibleImpact,n,z 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/command-list.rst b/doc/source/cli/command-list.rst similarity index 84% rename from doc/source/command-list.rst rename to doc/source/cli/command-list.rst index c4045b0406..9044f69389 100644 --- a/doc/source/command-list.rst +++ b/doc/source/cli/command-list.rst @@ -1,3 +1,5 @@ +.. _command-list: + ============ Command List ============ 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/interactive.rst b/doc/source/cli/interactive.rst similarity index 100% rename from doc/source/interactive.rst rename to doc/source/cli/interactive.rst 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/command-objects/access-token.rst b/doc/source/command-objects/access-token.rst deleted file mode 100644 index fd22e761f8..0000000000 --- a/doc/source/command-objects/access-token.rst +++ /dev/null @@ -1,42 +0,0 @@ -============ -access token -============ - -Identity v3 - -`Requires: OS-OAUTH1 extension` - -access token create -------------------- - -Create an access token - -.. program:: access token create -.. code:: bash - - os access token create - --consumer-key - --consumer-secret - --request-key - --request-secret - --verifier - -.. option:: --consumer-key - - Consumer key (required) - -.. option:: --consumer-secret - - Consumer secret (required) - -.. option:: --request-key - - Request token to exchange for access token (required) - -.. option:: --request-secret - - Secret associated with (required) - -.. option:: --verifier - - Verifier associated with (required) diff --git a/doc/source/command-objects/address-scope.rst b/doc/source/command-objects/address-scope.rst deleted file mode 100644 index 7481ed53de..0000000000 --- a/doc/source/command-objects/address-scope.rst +++ /dev/null @@ -1,120 +0,0 @@ -============= -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 - -address scope create --------------------- - -Create new address scope - -.. program:: address scope create -.. code:: bash - - os address scope create - [--project [--project-domain ]] - [--ip-version ] - [--share | --no-share] - - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --ip-version - - IP version (4 or 6, default is 4) - -.. option:: --share - - Share the address scope between projects - -.. option:: --no-share - - Do not share the address scope between projects (default) - -.. _address_scope_create-name: -.. describe:: - - New address scope name - -address scope delete --------------------- - -Delete address scope(s) - -.. program:: address scope delete -.. code:: bash - - os address scope delete - [ ...] - -.. _address_scope_delete-address-scope: -.. describe:: - - Address scope(s) to delete (name or ID) - -address scope list ------------------- - -List address scopes - -.. program:: address scope list -.. code:: bash - - os address scope list - -address scope set ------------------ - -Set address scope properties - -.. program:: address scope set -.. code:: bash - - os address scope set - [--name ] - [--share | --no-share] - - -.. option:: --name - - Set address scope name - -.. option:: --share - - Share the address scope between projects - -.. option:: --no-share - - Do not share the address scope between projects - -.. _address_scope_set-address-scope: -.. describe:: - - Address scope to modify (name or ID) - -address scope show ------------------- - -Display address scope details - -.. program:: address scope show -.. code:: bash - - os address scope show - - -.. _address_scope_show-address-scope: -.. describe:: - - Address scope to display (name or ID) diff --git a/doc/source/command-objects/aggregate.rst b/doc/source/command-objects/aggregate.rst deleted file mode 100644 index 25c7041a48..0000000000 --- a/doc/source/command-objects/aggregate.rst +++ /dev/null @@ -1,174 +0,0 @@ -========= -aggregate -========= - -Host aggregates provide a mechanism to group hosts according to certain -criteria. - -Compute v2 - -aggregate add host ------------------- - -Add host to aggregate - -.. program:: aggregate add host -.. code:: bash - - os aggregate add host - - - -.. _aggregate_add_host-aggregate: -.. describe:: - - Aggregate (name or ID) - -.. describe:: - - Host to add to :ref:`\ ` - -aggregate create ----------------- - -Create a new aggregate - -.. program:: aggregate create -.. code:: bash - - os aggregate create - [--zone ] - [--property [...] ] - - -.. option:: --zone - - Availability zone name - -.. option:: --property - - Property to add to this aggregate (repeat option to set multiple properties) - -.. describe:: - - New aggregate name - -aggregate delete ----------------- - -Delete existing aggregate(s) - -.. program:: aggregate delete -.. code:: bash - - os aggregate delete - [ ...] - -.. describe:: - - Aggregate(s) to delete (name or ID) - -aggregate list --------------- - -List all aggregates - -.. program:: aggregate list -.. code:: bash - - os aggregate list - [--long] - -.. option:: --long - - List additional fields in output - -aggregate remove host ---------------------- - -Remove host from aggregate - -.. program:: aggregate remove host -.. code:: bash - - os aggregate remove host - - - -.. _aggregate_remove_host-aggregate: -.. describe:: - - Aggregate (name or ID) - -.. describe:: - - Host to remove from :ref:`\ ` - -aggregate set -------------- - -Set aggregate properties - -.. program:: aggregate set -.. code:: bash - - os aggregate set - [--name ] - [--zone ] - [--property [...] ] - - -.. option:: --name - - Set aggregate name - -.. option:: --zone - - Set availability zone name - -.. option:: --property - - Property to set on :ref:`\ ` - (repeat option to set multiple properties) - -.. _aggregate_set-aggregate: -.. describe:: - - Aggregate to modify (name or ID) - -aggregate show --------------- - -Display aggregate details - -.. program:: aggregate show -.. code:: bash - - os aggregate show - - -.. describe:: - - Aggregate to display (name or ID) - -aggregate unset ---------------- - -Unset aggregate properties - -.. program:: aggregate unset -.. code-block:: bash - - os aggregate unset - [--property [...] ] - - -.. option:: --property - - Property to remove from :ref:`\ ` - (repeat option to remove multiple properties) - -.. _aggregate_unset-aggregate: -.. describe:: - - Aggregate to modify (name or ID) diff --git a/doc/source/command-objects/availability-zone.rst b/doc/source/command-objects/availability-zone.rst deleted file mode 100644 index 149e10811d..0000000000 --- a/doc/source/command-objects/availability-zone.rst +++ /dev/null @@ -1,38 +0,0 @@ -================= -availability zone -================= - -An **availability zone** is a logical partition of cloud block storage, -compute and network services. - -Block Storage v2, Compute v2, Network v2 - -availability zone list ----------------------- - -List availability zones and their status - -.. program availability zone list -.. code:: bash - - os availability zone list - [--compute] - [--network] - [--volume] - [--long] - -.. option:: --compute - - List compute availability zones - -.. option:: --network - - List network availability zones - -.. option:: --volume - - List volume availability zones - -.. option:: --long - - List additional fields in output diff --git a/doc/source/command-objects/backup.rst b/doc/source/command-objects/backup.rst deleted file mode 100644 index d7d96c289c..0000000000 --- a/doc/source/command-objects/backup.rst +++ /dev/null @@ -1,120 +0,0 @@ -====== -backup -====== - -Block Storage v1, v2 - -backup create -------------- - -Create new backup - -.. program:: backup create -.. code:: bash - - os backup create - [--container ] - [--name ] - [--description ] - [--force] - - -.. option:: --container - - Optional backup container name - -.. option:: --name - - Name of the backup - -.. option:: --description - - Description of the backup - -.. option:: --snapshot - - Snapshot to backup (name or ID) - -.. option:: --force - - Allow to back up an in-use volume - -.. _backup_create-backup: -.. describe:: - - Volume to backup (name or ID) - -backup delete -------------- - -Delete backup(s) - -.. program:: backup delete -.. code:: bash - - os backup delete - [--force] - [ ...] - -.. option:: --force - - Allow delete in state other than error or available - - *Volume version 2 only* - -.. _backup_delete-backup: -.. describe:: - - Backup(s) to delete (name or ID) - -backup list ------------ - -List backups - -.. program:: backup list -.. code:: bash - - os backup list - -.. _backup_list-backup: -.. option:: --long - - List additional fields in output - -backup restore --------------- - -Restore backup - -.. program:: backup restore -.. code:: bash - - os backup restore - - - -.. _backup_restore-backup: -.. describe:: - - Backup to restore (name or ID) - -.. describe:: - - Volume to restore to (name or ID) - -backup show ------------ - -Display backup details - -.. program:: backup show -.. code:: bash - - os backup show - - -.. _backup_show-backup: -.. describe:: - - Backup to display (name or ID) diff --git a/doc/source/command-objects/catalog.rst b/doc/source/command-objects/catalog.rst deleted file mode 100644 index 4319fb111f..0000000000 --- a/doc/source/command-objects/catalog.rst +++ /dev/null @@ -1,30 +0,0 @@ -======= -catalog -======= - -Identity v2, v3 - -catalog list ------------- - -List services in the service catalog - -.. program:: catalog list -.. code:: bash - - os catalog list - -catalog show ------------- - -Display service catalog details - -.. program:: catalog show -.. code:: bash - - os catalog show - - -.. describe:: - - Service to display (type or name) diff --git a/doc/source/command-objects/command.rst b/doc/source/command-objects/command.rst deleted file mode 100644 index ac4f851438..0000000000 --- a/doc/source/command-objects/command.rst +++ /dev/null @@ -1,17 +0,0 @@ -======= -command -======= - -Internal - -Installed commands in the OSC process. - -command list ------------- - -List recognized commands by group - -.. program:: command list -.. code:: bash - - os command list diff --git a/doc/source/command-objects/compute-agent.rst b/doc/source/command-objects/compute-agent.rst deleted file mode 100644 index 55540c8d6b..0000000000 --- a/doc/source/command-objects/compute-agent.rst +++ /dev/null @@ -1,99 +0,0 @@ -============= -compute agent -============= - -Compute v2 - -compute agent create --------------------- - -Create compute agent - -.. program:: compute agent create -.. code:: bash - - os compute agent create - - - -.. _compute_agent-create: -.. describe:: - - Type of OS - -.. describe:: - - Type of architecture - -.. describe:: - - Version - -.. describe:: - - URL - -.. describe:: - - MD5 hash - -.. describe:: - - Type of hypervisor - -compute agent delete --------------------- - -Delete compute agent(s) - -.. program:: compute agent delete -.. code:: bash - - os compute agent delete [ ...] - -.. _compute_agent-delete: -.. describe:: - - ID of agent(s) to delete - -compute agent list ------------------- - -List compute agents - -.. program:: compute agent list -.. code:: bash - - os compute agent list [--hypervisor ] - -.. option:: --hypervisor - - Type of hypervisor - -compute agent set ------------------ - -Set compute agent properties - -.. program:: agent set -.. code:: bash - - os compute agent set - - -.. _compute_agent-set: -.. describe:: - - ID of the agent - -.. describe:: - - Version of the agent - -.. describe:: - - URL - -.. describe:: - - MD5 hash diff --git a/doc/source/command-objects/compute-service.rst b/doc/source/command-objects/compute-service.rst deleted file mode 100644 index 57dd2ba556..0000000000 --- a/doc/source/command-objects/compute-service.rst +++ /dev/null @@ -1,92 +0,0 @@ -=============== -compute service -=============== - -Compute v2 - -compute service delete ----------------------- - -Delete compute service(s) - -.. program:: compute service delete -.. code:: bash - - os compute service delete - [ ...] - -.. _compute-service-delete: -.. describe:: - - Compute service(s) to delete (ID only) - -compute service list --------------------- - -List compute services - -.. program:: compute service list -.. code:: bash - - os compute service list - [--host ] - [--service ] - [--long] - -.. _compute-service-list: -.. option:: --host - - List services on specified host (name only) - -.. option:: --service - - List only specified service (name only) - -.. option:: --long - - List additional fields in output - - -compute service set -------------------- - -Set compute service properties - -.. program:: compute service set -.. code:: bash - - os compute service set - [--enable | --disable] - [--disable-reason ] - [--up | --down] - - -.. _compute-service-set: -.. option:: --enable - - Enable service - -.. option:: --disable - - Disable service - -.. option:: --disable-reason - - Reason for disabling the service (in quotes). Should be used with --disable option. - -.. option:: --up - - Force up service - -.. option:: --down - - Force down service - -.. describe:: - - Name of host - -.. describe:: - - Name of service (Binary name) - diff --git a/doc/source/command-objects/configuration.rst b/doc/source/command-objects/configuration.rst deleted file mode 100644 index 7bf054c072..0000000000 --- a/doc/source/command-objects/configuration.rst +++ /dev/null @@ -1,27 +0,0 @@ -============= -configuration -============= - -Available for all services - -configuration show ------------------- - -Show the current openstack client configuration. This command is a little -different from other show commands because it does not take a resource name -or id to show. The command line options, such as --os-cloud, can be used to -show different configurations. - -.. program:: configuration show -.. code:: bash - - os configuration show - [--mask | --unmask] - -.. option:: --mask - - Attempt to mask passwords (default) - -.. option:: --unmask - - Show password in clear text diff --git a/doc/source/command-objects/console-log.rst b/doc/source/command-objects/console-log.rst deleted file mode 100644 index 9eafb61ae2..0000000000 --- a/doc/source/command-objects/console-log.rst +++ /dev/null @@ -1,27 +0,0 @@ -=========== -console log -=========== - -Server console text dump - -Compute v2 - -console log show ----------------- - -Show server's console output - -.. program:: console log show -.. code:: bash - - os console log show - [--lines ] - - -.. option:: --lines - - Number of lines to display from the end of the log (default=all) - -.. describe:: - - Server to show log console log (name or ID) diff --git a/doc/source/command-objects/console-url.rst b/doc/source/command-objects/console-url.rst deleted file mode 100644 index 7993a7bfed..0000000000 --- a/doc/source/command-objects/console-url.rst +++ /dev/null @@ -1,35 +0,0 @@ -=========== -console url -=========== - -Server remote console URL - -Compute v2 - -console url show ----------------- - -Show server's remote console URL - -.. program:: console url show -.. code:: bash - - os console url show - [--novnc | --xvpvnc | --spice] - - -.. option:: --novnc - - Show noVNC console URL (default) - -.. option:: --xvpvnc - - Show xvpvnc console URL - -.. option:: --spice - - Show SPICE console URL - -.. describe:: - - Server to show URL (name or ID) diff --git a/doc/source/command-objects/consumer.rst b/doc/source/command-objects/consumer.rst deleted file mode 100644 index 91294fa20b..0000000000 --- a/doc/source/command-objects/consumer.rst +++ /dev/null @@ -1,83 +0,0 @@ -======== -consumer -======== - -Identity v3 - -`Requires: OS-OAUTH1 extension` - -consumer create ---------------- - -Create new consumer - -.. program:: consumer create -.. code:: bash - - os consumer create - [--description ] - -.. option:: --description - - New consumer description - -consumer delete ---------------- - -Delete consumer - -.. program:: consumer delete -.. code:: bash - - os consumer delete - - -.. describe:: - - Consumer to delete - -consumer list -------------- - -List consumers - -.. program:: consumer list -.. code:: bash - - os consumer list - -consumer set ------------- - -Set consumer properties - -.. program:: consumer set -.. code:: bash - - os consumer set - [--description ] - - -.. option:: --description - - New consumer description - -.. describe:: - - Consumer to modify - -consumer show -------------- - -Display consumer details - -.. program:: consumer show -.. code:: bash - - os consumer show - - -.. _consumer_show-consumer: -.. describe:: - - Consumer to display diff --git a/doc/source/command-objects/container.rst b/doc/source/command-objects/container.rst deleted file mode 100644 index 130a6b3dad..0000000000 --- a/doc/source/command-objects/container.rst +++ /dev/null @@ -1,150 +0,0 @@ -========= -container -========= - -Object Storage v1 - -container create ----------------- - -Create new container - -.. program:: container create -.. code:: bash - - os container create - [ ...] - -.. describe:: - - New container name(s) - -container delete ----------------- - -Delete container - -.. program:: container delete -.. code:: bash - - os container delete - [-r] | [--recursive] - [ ...] - -.. option:: --recursive, -r - - Recursively delete objects in container before container delete - -.. describe:: - - Container(s) to delete - -container list --------------- - -List containers - -.. program:: container list -.. code:: bash - - os container list - [--prefix ] - [--marker ] - [--end-marker ] - [--limit ] - [--long] - [--all] - -.. option:: --prefix - - Filter list using - -.. option:: --marker - - Anchor for paging - -.. option:: --end-marker - - End anchor for paging - -.. option:: --limit - - Limit the number of containers returned - -.. option:: --long - - List additional fields in output - -.. option:: --all - - List all containers (default is 10000) - -container save --------------- - -Save container contents locally - -.. program:: container save -.. code:: bash - - os container save - - -.. describe:: - - Container to save - -container set -------------- - -Set container properties - -.. program:: container set -.. code:: bash - - os container set - [--property [...] ] - [] - -.. option:: --property - - Set a property on this container (repeat option to set multiple properties) - -.. describe:: - - Container to modify - -container show --------------- - -Display container details - -.. program:: container show -.. code:: bash - - os container show - [] - -.. describe:: - - Container to display - -container unset ---------------- - -Unset container properties - -.. program:: container unset -.. code:: bash - - os container unset - [--property ] - [] - -.. option:: --property - - Property to remove from container (repeat option to remove multiple properties) - -.. describe:: - - Container to modify diff --git a/doc/source/command-objects/credential.rst b/doc/source/command-objects/credential.rst deleted file mode 100644 index ed8a00dbd7..0000000000 --- a/doc/source/command-objects/credential.rst +++ /dev/null @@ -1,27 +0,0 @@ -=========== -credential -=========== - -Identity v3 - -credential create ------------------- - -.. ''[consider rolling the ec2 creds into this too]'' - -.. code:: bash - - os credential create - --x509 - [] - [] - -credential show ----------------- - -.. code:: bash - - os credential show - [--token] - [--user] - [--x509 [--root]] diff --git a/doc/source/command-objects/domain.rst b/doc/source/command-objects/domain.rst deleted file mode 100644 index 94473570de..0000000000 --- a/doc/source/command-objects/domain.rst +++ /dev/null @@ -1,115 +0,0 @@ -====== -domain -====== - -Identity v3 - -domain create -------------- - -Create new domain - -.. program:: domain create -.. code:: bash - - os domain create - [--description ] - [--enable | --disable] - [--or-show] - - -.. option:: --description - - New domain description - -.. option:: --enable - - Enable domain (default) - -.. option:: --disable - - Disable domain - -.. option:: --or-show - - Return existing domain - - If the domain already exists, return the existing domain data and do not fail. - -.. describe:: - - New domain name - -domain delete -------------- - -Delete domain - -.. program:: domain delete -.. code:: bash - - os domain delete - - -.. describe:: - - Domain to delete (name or ID) - -domain list ------------ - -List domains - -.. program:: domain list -.. code:: bash - - os domain list - -domain set ----------- - -Set domain properties - -.. program:: domain set -.. code:: bash - - os domain set - [--name ] - [--description ] - [--enable | --disable] - - -.. option:: --name - - New domain name - -.. option:: --description - - New domain description - -.. option:: --enable - - Enable domain - -.. option:: --disable - - Disable domain - -.. describe:: - - Domain to modify (name or ID) - -domain show ------------ - -Display domain details - -.. program:: domain show -.. code:: bash - - os domain show - - -.. describe:: - - Domain to display (name or ID) diff --git a/doc/source/command-objects/ec2-credentials.rst b/doc/source/command-objects/ec2-credentials.rst deleted file mode 100644 index caf7fd6901..0000000000 --- a/doc/source/command-objects/ec2-credentials.rst +++ /dev/null @@ -1,138 +0,0 @@ -=============== -ec2 credentials -=============== - -Identity v2 - -ec2 credentials create ----------------------- - -Create EC2 credentials - -.. program:: ec2 credentials create -.. code-block:: bash - - os ec2 credentials create - [--project ] - [--user ] - [--user-domain ] - [--project-domain ] - -.. option:: --project - - Create credentials in project (name or ID; default: current authenticated project) - -.. option:: --user - - Create credentials for user (name or ID; default: current authenticated user) - -.. option:: --user-domain - - Domain the user belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -The :option:`--project` and :option:`--user` options are typically only -useful for admin users, but may be allowed for other users depending on -the policy of the cloud and the roles granted to the user. - -ec2 credentials delete ----------------------- - -Delete EC2 credentials - -.. program:: ec2 credentials delete -.. code-block:: bash - - os ec2 credentials delete - [--user ] - [--user-domain ] - [ ...] - -.. option:: --user - - Delete credentials for user (name or ID) - -.. option:: --user-domain - - Select user from a specific domain (name or ID) - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -.. _ec2_credentials_delete-access-key: -.. describe:: access-key - - Credentials access key(s) - -The :option:`--user` option is typically only useful for admin users, but -may be allowed for other users depending on the policy of the cloud and -the roles granted to the user. - -ec2 credentials list --------------------- - -List EC2 credentials - -.. program:: ec2 credentials list -.. code-block:: bash - - os ec2 credentials list - [--user ] - [--user-domain ] - -.. option:: --user - - Filter list by (name or ID) - -.. option:: --user-domain - - Select user from a specific domain (name or ID) - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -The :option:`--user` option is typically only useful for admin users, but -may be allowed for other users depending on the policy of the cloud and -the roles granted to the user. - -ec2 credentials show --------------------- - -Display EC2 credentials details - -.. program:: ec2 credentials show -.. code-block:: bash - - os ec2 credentials show - [--user ] - [--user-domain ] - - -.. option:: --user - - Show credentials for user (name or ID) - -.. option:: --user-domain - - Select user from a specific domain (name or ID) - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -.. _ec2_credentials_show-access-key: -.. describe:: access-key - - Credentials access key - -The :option:`--user` option is typically only useful for admin users, but -may be allowed for other users depending on the policy of the cloud and -the roles granted to the user. diff --git a/doc/source/command-objects/endpoint.rst b/doc/source/command-objects/endpoint.rst deleted file mode 100644 index c058c8444e..0000000000 --- a/doc/source/command-objects/endpoint.rst +++ /dev/null @@ -1,196 +0,0 @@ -======== -endpoint -======== - -Identity v2, v3 - -endpoint create ---------------- - -Create new endpoint - -*Identity version 2 only* - -.. program:: endpoint create -.. code:: bash - - os endpoint create - --publicurl - [--adminurl ] - [--internalurl ] - [--region ] - - -.. option:: --publicurl - - New endpoint public URL (required) - -.. option:: --adminurl - - New endpoint admin URL - -.. option:: --internalurl - - New endpoint internal URL - -.. option:: --region - - New endpoint region ID - -.. _endpoint_create-endpoint: -.. describe:: - - Service to be associated with new endpoint (name or ID) - -*Identity version 3 only* - -.. program:: endpoint create -.. code:: bash - - os endpoint create - [--region ] - [--enable | --disable] - - - - -.. option:: --region - - New endpoint region ID - -.. option:: --enable - - Enable endpoint (default) - -.. option:: --disable - - Disable endpoint - -.. describe:: - - Service to be associated with new endpoint(name or ID) - -.. describe:: - - New endpoint interface type (admin, public or internal) - -.. describe:: - - New endpoint URL - -endpoint delete ---------------- - -Delete endpoint(s) - -.. program:: endpoint delete -.. code:: bash - - os endpoint delete - [ ...] - -.. _endpoint_delete-endpoint: -.. describe:: - - Endpoint(s) to delete (ID only) - -endpoint list -------------- - -List endpoints - -.. program:: endpoint list -.. code:: bash - - os endpoint list - [--service ] - [--region ] - [--long] - -.. option:: --service - - Filter by service (name or ID) - - *Identity version 3 only* - -.. option:: --interface - - Filter by interface type (admin, public or internal) - - *Identity version 3 only* - -.. option:: --region - - Filter by region ID - - *Identity version 3 only* - -.. option:: --long - - List additional fields in output - - *Identity version 2 only* - -endpoint set ------------- - -Set endpoint properties - -*Identity version 3 only* - -.. program:: endpoint set -.. code:: bash - - os endpoint set - [--region ] - [--interface ] - [--url ] - [--service ] - [--enable | --disable] - - -.. option:: --region - - New endpoint region ID - -.. option:: --interface - - New endpoint interface type (admin, public or internal) - -.. option:: --url - - New endpoint URL - -.. option:: --service - - New endpoint service (name or ID) - -.. option:: --enable - - Enable endpoint - -.. option:: --disable - - Disable endpoint - -.. _endpoint_set-endpoint: -.. describe:: - - Endpoint to modify (ID only) - -endpoint show -------------- - -Display endpoint details - -.. program:: endpoint show -.. code:: bash - - os endpoint show - - -.. _endpoint_show-endpoint: -.. describe:: - - Endpoint to display (endpoint ID, service ID, service name, service type) diff --git a/doc/source/command-objects/extension.rst b/doc/source/command-objects/extension.rst deleted file mode 100644 index dff30fa137..0000000000 --- a/doc/source/command-objects/extension.rst +++ /dev/null @@ -1,41 +0,0 @@ -========= -extension -========= - -Many OpenStack server APIs include API extensions that enable -additional functionality. - -extension list --------------- - -List API extensions - -.. program:: extension list -.. code:: bash - - os extension list - [--compute] - [--identity] - [--network] - [--volume] - [--long] - -.. option:: --compute - - List extensions for the Compute API - -.. option:: --identity - - List extensions for the Identity API - -.. option:: --network - - List extensions for the Network API - -.. option:: --volume - - List extensions for the Block Storage API - -.. option:: --long - - List additional fields in output diff --git a/doc/source/command-objects/federation-protocol.rst b/doc/source/command-objects/federation-protocol.rst deleted file mode 100644 index 5b4ea48ace..0000000000 --- a/doc/source/command-objects/federation-protocol.rst +++ /dev/null @@ -1,112 +0,0 @@ -=================== -federation protocol -=================== - -Identity v3 - -`Requires: OS-FEDERATION extension` - -federation protocol create --------------------------- - -Create new federation protocol - -.. program:: federation protocol create -.. code:: bash - - os federation protocol create - --identity-provider - --mapping - - -.. option:: --identity-provider - - Identity provider that will support the new federation protocol (name or ID) (required) - -.. option:: --mapping - - Mapping that is to be used (name or ID) (required) - -.. describe:: - - New federation protocol name (must be unique per identity provider) - -federation protocol delete --------------------------- - -Delete federation protocol - -.. program:: federation protocol delete -.. code:: bash - - os federation protocol delete - --identity-provider - - -.. option:: --identity-provider - - Identity provider that supports (name or ID) (required) - -.. describe:: - - Federation protocol to delete (name or ID) - -federation protocol list ------------------------- - -List federation protocols - -.. program:: federation protocol list -.. code:: bash - - os federation protocol list - --identity-provider - -.. option:: --identity-provider - - Identity provider to list (name or ID) (required) - -federation protocol set ------------------------ - -Set federation protocol properties - -.. program:: federation protocol set -.. code:: bash - - os federation protocol set - --identity-provider - [--mapping ] - - -.. option:: --identity-provider - - Identity provider that supports (name or ID) (required) - -.. option:: --mapping - - Mapping that is to be used (name or ID) - -.. describe:: - - Federation protocol to modify (name or ID) - -federation protocol show ------------------------- - -Display federation protocol details - -.. program:: federation protocol show -.. code:: bash - - os federation protocol show - --identity-provider - - -.. option:: --identity-provider - - Identity provider that supports (name or ID) (required) - -.. describe:: - - Federation protocol to display (name or ID) diff --git a/doc/source/command-objects/flavor.rst b/doc/source/command-objects/flavor.rst deleted file mode 100644 index 9ea504c1be..0000000000 --- a/doc/source/command-objects/flavor.rst +++ /dev/null @@ -1,214 +0,0 @@ -====== -flavor -====== - -Compute v2 - -flavor create -------------- - -Create new flavor - -.. program:: flavor create -.. code:: bash - - os flavor create - [--id ] - [--ram ] - [--disk ] - [--ephemeral-disk ] - [--swap ] - [--vcpus ] - [--rxtx-factor ] - [--public | --private] - [--property [...] ] - [--project ] - [--project-domain ] - - -.. option:: --id - - Unique flavor ID; 'auto' creates a UUID (default: auto) - -.. option:: --ram - - Memory size in MB (default 256M) - -.. option:: --disk - - Disk size in GB (default 0G) - -.. option:: --ephemeral-disk - - Ephemeral disk size in GB (default 0G) - -.. option:: --swap - - Swap space size in GB (default 0G) - -.. option:: --vcpus - - Number of vcpus (default 1) - -.. option:: --rxtx-factor - - RX/TX factor (default 1.0) - -.. option:: --public - - Flavor is available to other projects (default) - -.. option:: --private - - Flavor is not available to other projects - -.. option:: --property - - Property to add for this flavor (repeat option to set multiple properties) - -.. option:: --project - - Allow to access private flavor (name or ID) - (Must be used with :option:`--private` option) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. _flavor_create-flavor-name: -.. describe:: - - New flavor name - -flavor delete -------------- - -Delete flavor(s) - -.. program:: flavor delete -.. code:: bash - - os flavor delete - [ ...] - -.. _flavor_delete-flavor: -.. describe:: - - Flavor(s) to delete (name or ID) - -flavor list ------------ - -List flavors - -.. program:: flavor list -.. code:: bash - - os flavor list - [--public | --private | --all] - [--long] - [--marker ] - [--limit ] - -.. option:: --public - - List only public flavors (default) - -.. option:: --private - - List only private flavors - -.. option:: --all - - List all flavors, whether public or private - -.. option:: --long - - List additional fields in output - -.. option:: --marker - - The last flavor ID of the previous page - -.. option:: --limit - - Maximum number of flavors to display - -flavor set ----------- - -Set flavor properties - -.. program:: flavor set -.. code:: bash - - os flavor set - [--property [...] ] - [--project ] - [--project-domain ] - - -.. option:: --property - - Property to add or modify for this flavor (repeat option to set multiple properties) - -.. option:: --project - - Set flavor access to project (name or ID) (admin only) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. describe:: - - Flavor to modify (name or ID) - -flavor show ------------ - -Display flavor details - -.. program:: flavor show -.. code:: bash - - os flavor show - - -.. _flavor_show-flavor: -.. describe:: - - Flavor to display (name or ID) - -flavor unset ------------- - -Unset flavor properties - -.. program:: flavor unset -.. code:: bash - - os flavor unset - [--property [...] ] - [--project ] - [--project-domain ] - - -.. option:: --property - - Property to remove from flavor (repeat option to remove multiple properties) - -.. option:: --project - - Remove flavor access from project (name or ID) (admin only) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. describe:: - - Flavor to modify (name or ID) diff --git a/doc/source/command-objects/floating-ip-pool.rst b/doc/source/command-objects/floating-ip-pool.rst deleted file mode 100644 index 6f074d2d34..0000000000 --- a/doc/source/command-objects/floating-ip-pool.rst +++ /dev/null @@ -1,15 +0,0 @@ -================ -floating ip pool -================ - -Compute v2, Network v2 - -floating ip pool list ---------------------- - -List pools of floating IP addresses - -.. program:: floating ip pool list -.. code:: bash - - os floating ip pool list diff --git a/doc/source/command-objects/group.rst b/doc/source/command-objects/group.rst deleted file mode 100644 index 0f2c5cd10b..0000000000 --- a/doc/source/command-objects/group.rst +++ /dev/null @@ -1,247 +0,0 @@ -===== -group -===== - -Identity v3 - -group add user --------------- - -Add user to group - -.. program:: group add user -.. code:: bash - - os group add user - [--group-domain ] - [--user-domain ] - - - -.. option:: --group-domain - - Domain the group belongs to (name or ID). This can be - used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -.. describe:: - - Group to contain (name or ID) - -.. describe:: - - User to add to (name or ID) - -group contains user -------------------- - -Check user membership in group - -.. program:: group contains user -.. code:: bash - - os group contains user - [--group-domain ] - [--user-domain ] - - - -.. option:: --group-domain - - Domain the group belongs to (name or ID). This can be - used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -.. describe:: - - Group to check (name or ID) - -.. describe:: - - User to check (name or ID) - -group create ------------- - -Create new group - -.. program:: group create -.. code:: bash - - os group create - [--domain ] - [--description ] - [--or-show] - - -.. option:: --domain - - Domain to contain new group (name or ID) - -.. option:: --description - - New group description - -.. option:: --or-show - - Return existing group - - If the group already exists, return the existing group data and do not fail. - -.. describe:: - - New group name - -group delete ------------- - -Delete group - -.. program:: group delete -.. code:: bash - - os group delete - [--domain ] - [ ...] - -.. option:: --domain - - Domain containing group(s) (name or ID) - -.. describe:: - - Group(s) to delete (name or ID) - -group list ----------- - -List groups - -.. program:: group list -.. code:: bash - - os group list - [--domain ] - [--user [--user-domain ]] - [--long] - -.. option:: --domain - - Filter group list by (name or ID) - -.. option:: --user - - Filter group list by (name or ID) - -.. option:: --user-domain - - Domain the user belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -.. option:: --long - - List additional fields in output - -group remove user ------------------ - -Remove user from group - -.. program:: group remove user -.. code:: bash - - os group remove user - [--group-domain ] - [--user-domain ] - - - -.. option:: --group-domain - - Domain the group belongs to (name or ID). This can be - used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). This can be - used in case collisions between user names exist. - - .. versionadded:: 3 - -.. describe:: - - Group containing (name or ID) - -.. describe:: - - User to remove from (name or ID) - -group set ---------- - -Set group properties - -.. program:: group set -.. code:: bash - - os group set - [--domain ] - [--name ] - [--description ] - - -.. option:: --domain - - Domain containing (name or ID) - -.. option:: --name - - New group name - -.. option:: --description - - New group description - -.. describe:: - - Group to modify (name or ID) - -group show ----------- - -Display group details - -.. program:: group show -.. code:: bash - - os group show - [--domain ] - - -.. option:: --domain - - Domain containing (name or ID) - -.. describe:: - - Group to display (name or ID) diff --git a/doc/source/command-objects/host.rst b/doc/source/command-objects/host.rst deleted file mode 100644 index 409b834b8d..0000000000 --- a/doc/source/command-objects/host.rst +++ /dev/null @@ -1,72 +0,0 @@ -==== -host -==== - -Compute v2 - -The physical computer running a hypervisor. - -host list ---------- - -List hosts - -.. program:: host list -.. code:: bash - - os host list - [--zone ] - -.. option:: --zone - - Only return hosts in the availability zone - -host set --------- - -Set host properties - -.. program:: host set -.. code:: bash - - os host set - [--enable | --disable] - [--enable-maintenance | --disable-maintenance] - - -.. _host-set: -.. option:: --enable - - Enable the host - -.. option:: --disable - - Disable the host - -.. _maintenance-set: -.. option:: --enable-maintenance - - Enable maintenance mode for the host - -.. option:: --disable-maintenance - - Disable maintenance mode for the host - -.. describe:: - - Host to modify (name only) - -host show ---------- - -Display host details - -.. program:: host show -.. code:: bash - - os host show - - -.. describe:: - - Name of host diff --git a/doc/source/command-objects/hypervisor-stats.rst b/doc/source/command-objects/hypervisor-stats.rst deleted file mode 100644 index 06edf7a1e9..0000000000 --- a/doc/source/command-objects/hypervisor-stats.rst +++ /dev/null @@ -1,16 +0,0 @@ -================ -hypervisor stats -================ - -Compute v2 - -hypervisor stats show ---------------------- - -Display hypervisor stats details - -.. program:: hypervisor stats show -.. code:: bash - - os hypervisor stats show - diff --git a/doc/source/command-objects/hypervisor.rst b/doc/source/command-objects/hypervisor.rst deleted file mode 100644 index d6d0469b8e..0000000000 --- a/doc/source/command-objects/hypervisor.rst +++ /dev/null @@ -1,36 +0,0 @@ -========== -hypervisor -========== - -Compute v2 - -hypervisor list ---------------- - -List hypervisors - -.. program:: hypervisor list -.. code:: bash - - os hypervisor list - [--matching ] - -.. option:: --matching - - Filter hypervisors using substring - -hypervisor show ---------------- - -Display hypervisor details - -.. program:: hypervisor show -.. code:: bash - - os hypervisor show - - -.. _hypervisor_show-flavor: -.. describe:: - - Hypervisor to display (name or ID) diff --git a/doc/source/command-objects/identity-provider.rst b/doc/source/command-objects/identity-provider.rst deleted file mode 100644 index ca773d811f..0000000000 --- a/doc/source/command-objects/identity-provider.rst +++ /dev/null @@ -1,127 +0,0 @@ -================= -identity provider -================= - -Identity v3 - -`Requires: OS-FEDERATION extension` - -identity provider create ------------------------- - -Create new identity provider - -.. program:: identity provider create -.. code:: bash - - os identity provider create - [--remote-id [...] | --remote-id-file ] - [--description ] - [--enable | --disable] - - -.. option:: --remote-id - - Remote IDs to associate with the Identity Provider - (repeat option to provide multiple values) - -.. option:: --remote-id-file - - Name of a file that contains many remote IDs to associate with the identity - provider, one per line - -.. option:: --description - - New identity provider description - -.. option:: --enable - - Enable the identity provider (default) - -.. option:: --disable - - Disable the identity provider - -.. describe:: - - New identity provider name (must be unique) - -identity provider delete ------------------------- - -Delete identity provider - -.. program:: identity provider delete -.. code:: bash - - os identity provider delete - - -.. describe:: - - Identity provider to delete - -identity provider list ----------------------- - -List identity providers - -.. program:: identity provider list -.. code:: bash - - os identity provider list - -identity provider set ---------------------- - -Set identity provider properties - -.. program:: identity provider set -.. code:: bash - - os identity provider set - [--remote-id [...] | --remote-id-file ] - [--description ] - [--enable | --disable] - - -.. option:: --remote-id - - Remote IDs to associate with the Identity Provider - (repeat option to provide multiple values) - -.. option:: --remote-id-file - - Name of a file that contains many remote IDs to associate with the identity - provider, one per line - -.. option:: --description - - Set identity provider description - -.. option:: --enable - - Enable the identity provider - -.. option:: --disable - - Disable the identity provider - -.. describe:: - - Identity provider to modify - -identity provider show ----------------------- - -Display identity provider details - -.. program:: identity provider show -.. code:: bash - - os identity provider show - - -.. describe:: - - Identity provider to display diff --git a/doc/source/command-objects/image.rst b/doc/source/command-objects/image.rst deleted file mode 100644 index d6451af76e..0000000000 --- a/doc/source/command-objects/image.rst +++ /dev/null @@ -1,528 +0,0 @@ -====== -image -====== - -Image v1, v2 - -image add project ------------------ - -*Only supported for Image v2* - -Associate project with image - -.. program:: image add project -.. code:: bash - - os image add project - [--project-domain ] - - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. describe:: - - Image to share (name or ID). - -.. describe:: - - Project to associate with image (name or ID) - -image create ------------- - -*Image v1, v2* - -Create/upload an image - -.. program:: image create -.. code:: bash - - os image create - [--id ] - [--store ] - [--container-format ] - [--disk-format ] - [--size ] - [--min-disk ] - [--min-ram ] - [--location ] - [--copy-from ] - [--file ] - [--volume ] - [--force] - [--checksum ] - [--protected | --unprotected] - [--public | --private] - [--property [...] ] - [--tag [...] ] - [--project [--project-domain ]] - - -.. option:: --id - - Image ID to reserve - -.. option:: --store - - Upload image to this store - - *Image version 1 only.* - -.. option:: --container-format - - Image container format (default: bare) - -.. option:: --disk-format - - Image disk format (default: raw) - -.. option:: --size - - Image size, in bytes (only used with --location and --copy-from) - - *Image version 1 only.* - -.. option:: --min-disk - - Minimum disk size needed to boot image, in gigabytes - -.. option:: --min-ram - - Minimum RAM size needed to boot image, in megabytes - -.. option:: --location - - Download image from an existing URL - - *Image version 1 only.* - -.. option:: --copy-from - - Copy image from the data store (similar to --location) - - *Image version 1 only.* - -.. option:: --file - - Upload image from local file - -.. option:: --volume - - Create image from a volume - -.. option:: --force - - Force image creation if volume is in use (only meaningful with --volume) - -.. option:: --checksum - - Image hash used for verification - - *Image version 1 only.* - -.. option:: --protected - - Prevent image from being deleted - -.. option:: --unprotected - - Allow image to be deleted (default) - -.. option:: --public - - Image is accessible to the public - -.. option:: --private - - Image is inaccessible to the public (default) - -.. option:: --property - - Set a property on this image (repeat for multiple values) - -.. option:: --tag - - Set a tag on this image (repeat for multiple values) - - .. versionadded:: 2 - -.. option:: --project - - Set an alternate project on this image (name or ID). - Previously known as `--owner`. - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - .. versionadded:: 2 - -.. describe:: - - New image name - -image delete ------------- - -Delete image(s) - -.. program:: image delete -.. code:: bash - - os image delete - - -.. describe:: - - Image(s) to delete (name or ID) - -image list ----------- - -List available images - -.. program:: image list -.. code:: bash - - os image list - [--public | --private | --shared] - [--property ] - [--long] - [--sort [:]] - [--limit ] - [--marker ] - -.. option:: --public - - List only public images - -.. option:: --private - - List only private images - -.. option:: --shared - - List only shared images - - *Image version 2 only.* - -.. option:: --property - - Filter output based on property - -.. option:: --long - - List additional fields in output - -.. option:: --sort [:] - - Sort output by selected keys and directions(asc or desc) (default: asc), - multiple keys and directions can be specified separated by comma - -.. option:: --limit - - Maximum number of images to display. - -.. option:: --marker - - The last image (name or ID) of the previous page. Display list of images - after marker. Display all images if not specified. - -image remove project --------------------- - -*Only supported for Image v2* - -Disassociate project with image - -.. program:: image remove project -.. code:: bash - - os image remove remove - [--project-domain ] - - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. describe:: - - Image to unshare (name or ID). - -.. describe:: - - Project to disassociate with image (name or ID) - -image save ----------- - -Save an image locally - -.. program:: image save -.. code:: bash - - os image save - --file - - -.. option:: --file - - Downloaded image save filename (default: stdout) - -.. describe:: - - Image to save (name or ID) - -image set ---------- - -*Image v1, v2* - -Set image properties - -.. program:: image set -.. code:: bash - - os image set - [--name ] - [--min-disk ] - [--min-ram ] - [--container-format ] - [--disk-format ] - [--size ] - [--protected | --unprotected] - [--public | --private] - [--store ] - [--location ] - [--copy-from ] - [--file ] - [--volume ] - [--force] - [--checksum ] - [--stdin] - [--property [...] ] - [--tag [...] ] - [--architecture ] - [--instance-id ] - [--kernel-id ] - [--os-distro ] - [--os-version ] - [--ramdisk-id ] - [--activate|--deactivate] - [--project [--project-domain ]] - - -.. option:: --name - - New image name - -.. option:: --min-disk - - Minimum disk size needed to boot image, in gigabytes - -.. option:: --min-ram - - Minimum RAM size needed to boot image, in megabytes - -.. option:: --container-format - - Image container format (default: bare) - -.. option:: --disk-format - - Image disk format (default: raw) - -.. option:: --size - - Size of image data (in bytes) - - *Image version 1 only.* - -.. option:: --protected - - Prevent image from being deleted - -.. option:: --unprotected - - Allow image to be deleted (default) - -.. option:: --public - - Image is accessible to the public - -.. option:: --private - - Image is inaccessible to the public (default) - -.. option:: --store - - Upload image to this store - - *Image version 1 only.* - -.. option:: --location - - Download image from an existing URL - - *Image version 1 only.* - -.. option:: --copy-from - - Copy image from the data store (similar to --location) - - *Image version 1 only.* - -.. option:: --file - - Upload image from local file - - *Image version 1 only.* - -.. option:: --volume - - Update image with a volume - - *Image version 1 only.* - -.. option:: --force - - Force image update if volume is in use (only meaningful with --volume) - - *Image version 1 only.* - -.. option:: --checksum - - Image hash used for verification - - *Image version 1 only.* - -.. option:: --stdin - - Allow to read image data from standard input - - *Image version 1 only.* - -.. option:: --property - - Set a property on this image (repeat option to set multiple properties) - - .. versionadded:: 2 - -.. option:: --tag - - Set a tag on this image (repeat for multiple values) - - .. versionadded:: 2 - -.. option:: --architecture - - Operating system architecture - - .. versionadded:: 2 - -.. option:: --instance-id - - ID of server instance used to create this image - - .. versionadded:: 2 - -.. option:: --kernel-id - - ID of kernel image used to boot this disk image - - .. versionadded:: 2 - -.. option:: --os-distro - - Operating system distribution name - - .. versionadded:: 2 - -.. option:: --os-version - - Operating system distribution version - - .. versionadded:: 2 - -.. option:: --ramdisk-id - - ID of ramdisk image used to boot this disk image - - .. versionadded:: 2 - -.. option:: --activate - - Activate the image. - - .. versionadded:: 2 - -.. option:: --deactivate - - Deactivate the image. - - .. versionadded:: 2 - -.. option:: --project - - Set an alternate project on this image (name or ID). - Previously known as `--owner`. - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - .. versionadded:: 2 - -.. describe:: - - Image to modify (name or ID) - -image show ----------- - -Display image details - -.. program:: image show -.. code:: bash - - os image show - - -.. describe:: - - Image to display (name or ID) - -image unset ------------ - -*Only supported for Image v2* - -Unset image tags or properties - -.. program:: image unset -.. code:: bash - - os image set - [--tag ] - [--property ] - - -.. option:: --tag - - Unset a tag on this image (repeat option to unset multiple tags) - -.. option:: --property - - Unset a property on this image (repeat option to unset multiple properties) - -.. describe:: - - Image to modify (name or ID) diff --git a/doc/source/command-objects/ip-availability.rst b/doc/source/command-objects/ip-availability.rst deleted file mode 100644 index f200ab13a6..0000000000 --- a/doc/source/command-objects/ip-availability.rst +++ /dev/null @@ -1,60 +0,0 @@ -=============== -ip availability -=============== - -Network v2 - -ip availability list --------------------- - -List IP availability for network - -This command retrieves information about IP availability. -Useful for admins who need a quick way to check the -IP availability for all associated networks. -List specifically returns total IP capacity and the -number of allocated IP addresses from that pool. - -.. program:: ip availability list -.. code:: bash - - os ip availability list - [--ip-version {4,6}] - [--project ] - -.. option:: --ip-version {4,6} - - List IP availability of given IP version networks - (default is 4) - -.. option:: --project - - List IP availability of given project - (name or ID) - -ip availability show --------------------- - -Show network IP availability details - -This command retrieves information about IP availability. -Useful for admins who need a quick way to -check the IP availability and details for a -specific network. - -This command will return information about -IP availability for the network as a whole, and -return availability information for each individual -subnet within the network as well. - - -.. program:: ip availability show -.. code:: bash - - os ip availability show - - -.. _ip_availability_show-network -.. describe:: - - Show IP availability for a specific network (name or ID) diff --git a/doc/source/command-objects/ip-fixed.rst b/doc/source/command-objects/ip-fixed.rst deleted file mode 100644 index c2447b2890..0000000000 --- a/doc/source/command-objects/ip-fixed.rst +++ /dev/null @@ -1,47 +0,0 @@ -======== -ip fixed -======== - -Compute v2 - -ip fixed add ------------- - -Add fixed IP address to server -(Deprecated, please use ``server add fixed ip`` instead) - -.. program:: ip fixed add -.. code:: bash - - os ip fixed add - - - -.. describe:: - - Network to fetch an IP address from (name or ID) - -.. describe:: - - Server to receive the IP address (name or ID) - -ip fixed remove ---------------- - -Remove fixed IP address from server -(Deprecated, please use ``server remove fixed ip`` instead) - -.. program:: ip fixed remove -.. code:: bash - - os ip fixed remove - - - -.. describe:: - - IP address to remove from server (name only) - -.. describe:: - - Server to remove the IP address from (name or ID) diff --git a/doc/source/command-objects/ip-floating-pool.rst b/doc/source/command-objects/ip-floating-pool.rst deleted file mode 100644 index 310974c619..0000000000 --- a/doc/source/command-objects/ip-floating-pool.rst +++ /dev/null @@ -1,16 +0,0 @@ -================ -ip floating pool -================ - -Compute v2 - -ip floating pool list ---------------------- - -List pools of floating IP addresses -(Deprecated, please use ``floating ip pool list`` instead) - -.. program:: ip floating pool list -.. code:: bash - - os ip floating pool list diff --git a/doc/source/command-objects/ip-floating.rst b/doc/source/command-objects/ip-floating.rst deleted file mode 100644 index 378812d123..0000000000 --- a/doc/source/command-objects/ip-floating.rst +++ /dev/null @@ -1,125 +0,0 @@ -=========== -ip floating -=========== - -Compute v2, Network v2 - -ip floating add ---------------- - -Add floating IP address to server -(Deprecated, please use ``server add floating ip`` instead) - -.. program:: ip floating add -.. code:: bash - - os ip floating add - - - -.. describe:: - - IP address to add to server (name only) - -.. describe:: - - Server to receive the IP address (name or ID) - -ip floating create ------------------- - -Create new floating IP address - -.. program:: ip floating create -.. code:: bash - - os ip floating create - [--subnet ] - [--port ] - [--floating-ip-address ] - [--fixed-ip-address ] - - -.. option:: --subnet - - Subnet on which you want to create the floating IP (name or ID) - (Network v2 only) - -.. option:: --port - - Port to be associated with the floating IP (name or ID) - (Network v2 only) - -.. option:: --floating-ip-address - - Floating IP address - (Network v2 only) - -.. option:: --fixed-ip-address - - Fixed IP address mapped to the floating IP - (Network v2 only) - -.. describe:: - - Network to allocate floating IP from (name or ID) - -ip floating delete ------------------- - -Delete floating IP(s) - -.. program:: ip floating delete -.. code:: bash - - os ip floating delete - [ ...] - -.. describe:: - - Floating IP(s) to delete (IP address or ID) - -ip floating list ----------------- - -List floating IP addresses - -.. program:: ip floating list -.. code:: bash - - os ip floating list - -ip floating remove ------------------- - -Remove floating IP address from server -(Deprecated, please use ``server remove floating ip`` instead) - -.. program:: ip floating remove -.. code:: bash - - os ip floating remove - - - -.. describe:: - - IP address to remove from server (name only) - -.. describe:: - - Server to remove the IP address from (name or ID) - -ip floating show ----------------- - -Display floating IP details - -.. program:: ip floating show -.. code:: bash - - os ip floating show - -.. describe:: - - Floating IP to display (IP address or ID) diff --git a/doc/source/command-objects/keypair.rst b/doc/source/command-objects/keypair.rst deleted file mode 100644 index af50a6511d..0000000000 --- a/doc/source/command-objects/keypair.rst +++ /dev/null @@ -1,73 +0,0 @@ -======= -keypair -======= - -The badly named keypair is really the public key of an OpenSSH key pair to be -used for access to created servers. - -Compute v2 - -keypair create --------------- - -Create new public key - -.. program:: keypair create -.. code:: bash - - os keypair create - [--public-key ] - - -.. option:: --public-key - - Filename for public key to add - -.. describe:: - - New public key name - -keypair delete --------------- - -Delete public key(s) - -.. program:: keypair delete -.. code:: bash - - os keypair delete - [ ...] - -.. describe:: - - Public key(s) to delete (name only) - -keypair list ------------- - -List public key fingerprints - -.. program:: keypair list -.. code:: bash - - os keypair list - -keypair show ------------- - -Display public key details - -.. program:: keypair show -.. code:: bash - - os keypair show - [--public-key] - - -.. option:: --public-key - - Show only bare public key (name only) - -.. describe:: - - Public key to display (name only) diff --git a/doc/source/command-objects/limits.rst b/doc/source/command-objects/limits.rst deleted file mode 100644 index 87a5b33c98..0000000000 --- a/doc/source/command-objects/limits.rst +++ /dev/null @@ -1,40 +0,0 @@ -====== -limits -====== - -The Compute and Block Storage APIs have resource usage limits. - -Compute v2, Block Storage v1 - -limits show ------------ - -Show compute and block storage limits - -.. program:: limits show -.. code:: bash - - os limits show - --absolute [--reserved] | --rate - [--project ] - [--domain ] - -.. option:: --absolute - - Show absolute limits - -.. option:: --rate - - Show rate limits - -.. option:: --reserved - - Include reservations count [only valid with :option:`--absolute`] - -.. option:: --project - - Show limits for a specific project (name or ID) [only valid with --absolute] - -.. option:: --domain - - Domain the project belongs to (name or ID) [only valid with --absolute] diff --git a/doc/source/command-objects/mapping.rst b/doc/source/command-objects/mapping.rst deleted file mode 100644 index 25af474061..0000000000 --- a/doc/source/command-objects/mapping.rst +++ /dev/null @@ -1,91 +0,0 @@ -======= -mapping -======= - -Identity v3 - -`Requires: OS-FEDERATION extension` - -mapping create --------------- - -Create new mapping - -.. program:: mapping create -.. code:: bash - - os mapping create - --rules - - -.. option:: --rules - - Filename that contains a set of mapping rules (required) - -.. _mapping_create-mapping: -.. describe:: - - New mapping name (must be unique) - -mapping delete --------------- - -Delete mapping - -.. program:: mapping delete -.. code:: bash - - os mapping delete - - -.. _mapping_delete-mapping: -.. describe:: - - Mapping to delete - -mapping list ------------- - -List mappings - -.. program:: mapping list -.. code:: bash - - os mapping list - -mapping set ------------ - -Set mapping properties - -.. program:: mapping set -.. code:: bash - - os mapping set - [--rules ] - - -.. option:: --rules - - Filename that contains a new set of mapping rules - -.. _mapping_set-mapping: -.. describe:: - - Mapping to modify - -mapping show ------------- - -Display mapping details - -.. program:: mapping show -.. code:: bash - - os mapping show - - -.. _mapping_show-mapping: -.. describe:: - - Mapping to display diff --git a/doc/source/command-objects/module.rst b/doc/source/command-objects/module.rst deleted file mode 100644 index c3bc137287..0000000000 --- a/doc/source/command-objects/module.rst +++ /dev/null @@ -1,22 +0,0 @@ -====== -module -====== - -Internal - -Installed Python modules in the OSC process. - -module list ------------ - -List module versions - -.. program:: module list -.. code:: bash - - os module list - [--all] - -.. option:: --all - - Show all modules that have version information diff --git a/doc/source/command-objects/network-segment.rst b/doc/source/command-objects/network-segment.rst deleted file mode 100644 index 56a11e1ed4..0000000000 --- a/doc/source/command-objects/network-segment.rst +++ /dev/null @@ -1,54 +0,0 @@ -=============== -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 - -network segment list --------------------- - -List network segments - -.. caution:: This is a beta command and subject to change. - Use global option ``--os-beta-command`` to - enable this command. - -.. program:: network segment list -.. code:: bash - - os network segment list - [--long] - [--network ] - -.. option:: --long - - List additional fields in output - -.. option:: --network - - List network segments that belong to this network (name or ID) - -network segment show --------------------- - -Display network segment details - -.. caution:: This is a beta command and subject to change. - Use global option ``--os-beta-command`` to - enable this command. - -.. program:: network segment show -.. code:: bash - - os network segment show - - -.. _network_segment_show-segment: -.. describe:: - - Network segment to display (ID only) diff --git a/doc/source/command-objects/network.rst b/doc/source/command-objects/network.rst deleted file mode 100644 index 0c472e7f18..0000000000 --- a/doc/source/command-objects/network.rst +++ /dev/null @@ -1,278 +0,0 @@ -======= -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 - -network create --------------- - -Create new network - -.. program:: network create -.. code:: bash - - os network create - [--project [--project-domain ]] - [--enable | --disable] - [--share | --no-share] - [--availability-zone-hint ] - [--external [--default | --no-default] | --internal] - [--provider-network-type ] - [--provider-physical-network ] - [--provider-segment ] - [--transparent-vlan | --no-transparent-vlan] - - -.. option:: --project - - Owner's project (name or ID) - - *Network version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - *Network version 2 only* - -.. option:: --enable - - Enable network (default) - - *Network version 2 only* - -.. option:: --disable - - Disable network - - *Network version 2 only* - -.. option:: --share - - Share the network between projects - -.. option:: --no-share - - Do not share the network between projects - -.. option:: --availability-zone-hint - - Availability Zone in which to create this network - (Network Availability Zone extension required, - repeat option to set multiple availability zones) - - *Network version 2 only* - -.. option:: --subnet - - IPv4 subnet for fixed IPs (in CIDR notation) - - *Compute version 2 only* - -.. option:: --external - - Set this network as an external network - (external-net extension required) - - *Network version 2 only* - -.. option:: --internal - - Set this network as an internal network (default) - - *Network version 2 only* - -.. option:: --default - - Specify if this network should be used as - the default external network - - *Network version 2 only* - -.. option:: --no-default - - Do not use the network as the default external network - (default) - - *Network version 2 only* - -.. option:: --provider-network-type - - The physical mechanism by which the virtual network is implemented. - The supported options are: flat, geneve, gre, local, vlan, vxlan. - - *Network version 2 only* - -.. option:: --provider-physical-network - - Name of the physical network over which the virtual network is implemented - - *Network version 2 only* - -.. option:: --provider-segment - - VLAN ID for VLAN networks or Tunnel ID for GENEVE/GRE/VXLAN networks - - *Network version 2 only* - -.. option:: --transparent-vlan - - Make the network VLAN transparent - - *Network version 2 only* - -.. option:: --no-transparent-vlan - - Do not make the network VLAN transparent - - *Network version 2 only* - -.. _network_create-name: -.. describe:: - - New network name - -network delete --------------- - -Delete network(s) - -.. program:: network delete -.. code:: bash - - os network delete - [ ...] - -.. _network_delete-network: -.. describe:: - - Network(s) to delete (name or ID) - -network list ------------- - -List networks - -.. program:: network list -.. code:: bash - - os network list - [--external] - [--long] - -.. option:: --external - - List external networks - -.. option:: --long - - List additional fields in output - -network set ------------ - -Set network properties - -*Network version 2 only* - -.. program:: network set -.. code:: bash - - os network set - [--name ] - [--enable | --disable] - [--share | --no-share] - [--external [--default | --no-default] | --internal] - [--provider-network-type ] - [--provider-physical-network ] - [--provider-segment ] - [--transparent-vlan | --no-transparent-vlan] - - -.. option:: --name - - Set network name - -.. option:: --enable - - Enable network - -.. option:: --disable - - Disable network - -.. option:: --share - - Share the network between projects - -.. option:: --no-share - - Do not share the network between projects - -.. option:: --external - - Set this network as an external network. - (external-net extension required) - -.. option:: --internal - - Set this network as an internal network - -.. option:: --default - - Set the network as the default external network - -.. option:: --no-default - - Do not use the network as the default external network. - -.. option:: --provider-network-type - - The physical mechanism by which the virtual network is implemented. - The supported options are: flat, gre, local, vlan, vxlan. - -.. option:: --provider-physical-network - - Name of the physical network over which the virtual network is implemented - -.. option:: --provider-segment - - VLAN ID for VLAN networks or Tunnel ID for GRE/VXLAN networks - -.. option:: --transparent-vlan - - Make the network VLAN transparent - -.. option:: --no-transparent-vlan - - Do not make the network VLAN transparent - -.. _network_set-network: -.. describe:: - - Network to modify (name or ID) - -network show ------------- - -Display network details - -.. program:: network show -.. code:: bash - - os network show - - -.. _network_show-network: -.. describe:: - - Network to display (name or ID) diff --git a/doc/source/command-objects/object-store-account.rst b/doc/source/command-objects/object-store-account.rst deleted file mode 100644 index ba37078ed6..0000000000 --- a/doc/source/command-objects/object-store-account.rst +++ /dev/null @@ -1,45 +0,0 @@ -==================== -object store account -==================== - -Object Storage v1 - -object store account set ------------------------- - -Set account properties - -.. program:: object store account set -.. code:: bash - - os object store account set - [--property [...] ] - -.. option:: --property - - Set a property on this account (repeat option to set multiple properties) - -object store account show -------------------------- - -Display account details - -.. program:: object store account show -.. code:: bash - - os object store account show - -object store account unset --------------------------- - -Unset account properties - -.. program:: object store account unset -.. code:: bash - - os object store account unset - [--property ] - -.. option:: --property - - Property to remove from account (repeat option to remove multiple properties) diff --git a/doc/source/command-objects/object.rst b/doc/source/command-objects/object.rst deleted file mode 100644 index 5aaad8a526..0000000000 --- a/doc/source/command-objects/object.rst +++ /dev/null @@ -1,190 +0,0 @@ -====== -object -====== - -Object Storage v1 - -object create -------------- - -Upload object to container - -.. program:: object create -.. code:: bash - - os object create - - [ ...] - -.. describe:: - - Container for new object - -.. describe:: - - Local filename(s) to upload - -object delete -------------- - -Delete object from container - -.. program:: object delete -.. code:: bash - - os object delete - - [ ...] - -.. describe:: - - Delete object(s) from - -.. describe:: - - Object(s) to delete - -object list ------------ - -List objects - -.. program object list -.. code:: bash - - os object list - [--prefix ] - [--delimiter ] - [--marker ] - [--end-marker ] - [--limit ] - [--long] - [--all] - ] - -.. option:: --prefix - - Filter list using - -.. option:: --delimiter - - Roll up items with - -.. option:: --marker - - Anchor for paging - -.. option:: --end-marker - - End anchor for paging - -.. option:: --limit - - Limit number of objects returned - -.. option:: --long - - List additional fields in output - -.. option:: --all - - List all objects in (default is 10000) - -.. describe:: - - Container to list - -object save ------------ - -Save object locally - -.. program:: object save -.. code:: bash - - os object save - [--file ] - [] - [] - -.. option:: --file - - Destination filename (defaults to object name) - -.. describe:: - - Download from - -.. describe:: - - Object to save - -object set ----------- - -Set object properties - -.. program:: object set -.. code:: bash - - os object set - [--property [...] ] - - [] - -.. option:: --property - - Set a property on this object (repeat option to set multiple properties) - -.. describe:: - - Modify from - -.. describe:: - - Object to modify - -object show ------------ - -Display object details - -.. program:: object show -.. code:: bash - - os object show - - - -.. describe:: - - Display from - -.. describe:: - - Object to display - -object unset ------------- - -Unset object properties - -.. program:: object unset -.. code:: bash - - os object unset - [--property ] - - [] - -.. option:: --property - - Property to remove from object (repeat option to remove multiple properties) - -.. describe:: - - Modify from - -.. describe:: - - Object to modify diff --git a/doc/source/command-objects/policy.rst b/doc/source/command-objects/policy.rst deleted file mode 100644 index 195a89f25e..0000000000 --- a/doc/source/command-objects/policy.rst +++ /dev/null @@ -1,95 +0,0 @@ -====== -policy -====== - -Identity v3 - -policy create -------------- - -Create new policy - -.. program:: policy create -.. code:: bash - - os policy create - [--type ] - - -.. option:: --type - - New MIME type of the policy rules file (defaults to application/json) - -.. describe:: - - New serialized policy rules file - -policy delete -------------- - -Delete policy - -.. program:: policy delete -.. code:: bash - - os policy delete - - -.. describe:: - - Policy to delete - -policy list ------------ - -List policies - -.. program:: policy list -.. code:: bash - - os policy list - [--long] - -.. option:: --long - - List additional fields in output - -policy set ----------- - -Set policy properties - -.. program:: policy set -.. code:: bash - - os policy set - [--type ] - [--rules ] - - -.. option:: --type - - New MIME type of the policy rules file - -.. describe:: --rules - - New serialized policy rules file - -.. describe:: - - Policy to modify - -policy show ------------ - -Display policy details - -.. program:: policy show -.. code:: bash - - os policy show - - -.. describe:: - - Policy to display diff --git a/doc/source/command-objects/port.rst b/doc/source/command-objects/port.rst deleted file mode 100644 index 4d7b95b4e3..0000000000 --- a/doc/source/command-objects/port.rst +++ /dev/null @@ -1,246 +0,0 @@ -==== -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 - -port create ------------ - -Create new port - -.. program:: port create -.. code:: bash - - os port create - --network - [--fixed-ip subnet=,ip-address=] - [--device ] - [--device-owner ] - [--vnic-type ] - [--binding-profile ] - [--host ] - [--enable | --disable] - [--mac-address ] - [--project [--project-domain ]] - - -.. option:: --network - - Network this port belongs to (name or ID) - -.. option:: --fixed-ip subnet=,ip-address= - - Desired IP and/or subnet (name or ID) for this port: - subnet=,ip-address= - (repeat option to set multiple fixed IP addresses) - -.. option:: --device - - Port device ID - -.. option:: --device-owner - - Device owner of this port. This is the entity that uses - the port (for example, network:dhcp). - -.. option:: --vnic-type - - VNIC type for this port (direct | direct-physical | macvtap | normal | baremetal, - default: normal) - -.. option:: --binding-profile - - Custom data to be passed as binding:profile. Data may - be passed as = or JSON. - (repeat option to set multiple binding:profile data) - -.. option:: --host - - Allocate port on host ```` (ID only) - -.. option:: --enable - - Enable port (default) - -.. option:: --disable - - Disable port - -.. option:: --mac-address - - MAC address of this port - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. _port_create-name: -.. describe:: - - Name of this port - -port delete ------------ - -Delete port(s) - -.. program:: port delete -.. code:: bash - - os port delete - [ ...] - -.. _port_delete-port: -.. describe:: - - Port(s) to delete (name or ID) - -port list ---------- - -List ports - -.. program:: port list -.. code:: bash - - os port list - [--device-owner ] - [--router ] - -.. option:: --device-owner - - List only ports with the specified device owner. This is - the entity that uses the port (for example, network:dhcp). - -.. option:: --router - - List only ports attached to this router (name or ID) - -port set --------- - -Set port properties - -.. program:: port set -.. code:: bash - - os port set - [--fixed-ip subnet=,ip-address= | --no-fixed-ip] - [--device ] - [--device-owner ] - [--vnic-type ] - [--binding-profile | --no-binding-profile] - [--host ] - [--enable | --disable] - [--name ] - - -.. option:: --fixed-ip subnet=,ip-address= - - Desired IP and/or subnet (name or ID) for this port: - subnet=,ip-address= - (repeat option to set multiple fixed IP addresses) - -.. option:: --no-fixed-ip - - Clear existing information of fixed IP addresses - -.. option:: --device - - Port device ID - -.. option:: --device-owner - - Device owner of this port. This is the entity that uses - the port (for example, network:dhcp). - -.. option:: --vnic-type - - VNIC type for this port (direct | direct-physical | macvtap | normal | baremetal, - default: normal) - -.. option:: --binding-profile - - Custom data to be passed as binding:profile. Data may - be passed as = or JSON. - (repeat option to set multiple binding:profile data) - -.. option:: --no-binding-profile - - Clear existing information of binding:profile - -.. option:: --host - - Allocate port on host ```` (ID only) - -.. option:: --enable - - Enable port - -.. option:: --disable - - Disable port - -.. option:: --name - - Set port name - -.. _port_set-port: -.. describe:: - - Port to modify (name or ID) - -port show ---------- - -Display port details - -.. program:: port show -.. code:: bash - - os port show - - -.. _port_show-port: -.. describe:: - - Port to display (name or ID) - -port unset ----------- - -Unset port properties - -.. program:: port unset -.. code:: bash - - os port unset - [--fixed-ip subnet=,ip-address= [...]] - [--binding-profile [...]] - - -.. option:: --fixed-ip subnet=,ip-address= - - Desired IP and/or subnet (name or ID) which should be removed - from this port: subnet=,ip-address= - (repeat option to unset multiple fixed IP addresses) - -.. option:: --binding-profile - - Desired key which should be removed from binding-profile - (repeat option to unset multiple binding:profile data) - -.. _port_unset-port: -.. describe:: - - Port to modify (name or ID) diff --git a/doc/source/command-objects/project.rst b/doc/source/command-objects/project.rst deleted file mode 100644 index f76f79ff53..0000000000 --- a/doc/source/command-objects/project.rst +++ /dev/null @@ -1,221 +0,0 @@ -======= -project -======= - -Identity v2, v3 - -project create --------------- - -Create new project - -.. program:: project create -.. code:: bash - - os project create - [--domain ] - [--parent ] - [--description ] - [--enable | --disable] - [--property ] - [--or-show] - - -.. option:: --domain - - Domain owning the project (name or ID) - - .. versionadded:: 3 - -.. option:: --parent - - Parent of the project (name or ID) - - .. versionadded:: 3 - -.. option:: --description - - Project description - -.. option:: --enable - - Enable project (default) - -.. option:: --disable - - Disable project - -.. option:: --property - - Add a property to :ref:`\ ` - (repeat option to set multiple properties) - -.. option:: --or-show - - Return existing project - - If the project already exists return the existing project data and do not fail. - -.. _project_create-name: -.. describe:: - - New project name - -project delete --------------- - -Delete project(s) - -.. program:: project delete -.. code:: bash - - os project delete - [--domain ] - [ ...] - -.. option:: --domain - - Domain owning :ref:`\ ` (name or ID) - - .. versionadded:: 3 - -.. _project_delete-project: -.. describe:: - - Project to delete (name or ID) - -project list ------------- - -List projects - -.. program:: project list -.. code:: bash - - os project list - [--domain ] - [--user ] - [--long] - -.. option:: --domain - - Filter projects by :option:`\ <--domain>` (name or ID) - - .. versionadded:: 3 - -.. option:: --user - - Filter projects by :option:`\ <--user>` (name or ID) - - .. versionadded:: 3 - -.. option:: --long - - List additional fields in output - -project set ------------ - -Set project properties - -.. program:: project set -.. code:: bash - - os project set - [--name ] - [--domain ] - [--description ] - [--enable | --disable] - [--property ] - - -.. option:: --name - - Set project name - -.. option:: --domain - - Domain owning :ref:`\ ` (name or ID) - - .. versionadded:: 3 - -.. option:: --description - - Set project description - -.. option:: --enable - - Enable project (default) - -.. option:: --disable - - Disable project - -.. option:: --property - - Set a property on :ref:`\ ` - (repeat option to set multiple properties) - - *Identity version 2 only* - -.. _project_set-project: -.. describe:: - - Project to modify (name or ID) - -project show ------------- - -Display project details - -.. program:: project show -.. code:: bash - - os project show - [--domain ] - - -.. option:: --domain - - Domain owning :ref:`\ ` (name or ID) - - .. versionadded:: 3 - -.. option:: --parents - - Show the project\'s parents as a list - - .. versionadded:: 3 - -.. option:: --children - - Show project\'s subtree (children) as a list - - .. versionadded:: 3 - -.. _project_show-project: -.. describe:: - - Project to display (name or ID) - -project unset -------------- - -Unset project properties - -*Identity version 2 only* - -.. program:: project unset -.. code:: bash - - os project unset - --property [--property ...] - - -.. option:: --property - - Property key to remove from project (repeat option to remove multiple properties) - -.. describe:: - - Project to modify (name or ID) diff --git a/doc/source/command-objects/quota.rst b/doc/source/command-objects/quota.rst deleted file mode 100644 index dc5e362355..0000000000 --- a/doc/source/command-objects/quota.rst +++ /dev/null @@ -1,214 +0,0 @@ -===== -quota -===== - -Resource quotas appear in multiple APIs, OpenStackClient presents them as a single object with multiple properties. - -Block Storage v1, Compute v2, Network v2 - -quota set ---------- - -Set quotas for project - -.. program:: quota set -.. code:: bash - - os quota set - # Compute settings - [--cores ] - [--fixed-ips ] - [--floating-ips ] - [--injected-file-size ] - [--injected-files ] - [--instances ] - [--key-pairs ] - [--properties ] - [--ram ] - - # Block Storage settings - [--gigabytes ] - [--snapshots ] - [--volumes ] - [--volume-type ] - - # Network settings - [--floating-ips ] - [--secgroup-rules ] - [--secgroups ] - [--networks ] - [--subnets ] - [--ports ] - [--routers ] - [--rbac-policies ] - [--vips ] - [--subnetpools ] - [--members ] - [--health-monitors ] - - - -Set quotas for class - -.. code:: bash - - os quota set - --class - # Compute settings - [--cores ] - [--fixed-ips ] - [--floating-ips ] - [--injected-file-size ] - [--injected-files ] - [--instances ] - [--key-pairs ] - [--properties ] - [--ram ] - - # Block Storage settings - [--gigabytes ] - [--snapshots ] - [--volumes ] - - - -.. option:: --class - - Set quotas for ```` - -.. option:: --properties - - New value for the properties quota - -.. option:: --ram - - New value for the ram quota - -.. option:: --secgroup-rules - - New value for the secgroup-rules quota - -.. option:: --instances - - New value for the instances quota - -.. option:: --key-pairs - - New value for the key-pairs quota - -.. option:: --fixed-ips - - New value for the fixed-ips quota - -.. option:: --secgroups - - New value for the secgroups quota - -.. option:: --injected-file-size - - New value for the injected-file-size quota - -.. option:: --floating-ips - - New value for the floating-ips quota - -.. option:: --injected-files - - New value for the injected-files quota - -.. option:: --cores - - New value for the cores quota - -.. option:: --injected-path-size - - New value for the injected-path-size quota - -.. option:: --gigabytes - - New value for the gigabytes quota - -.. option:: --volumes - - New value for the volumes quota - -.. option:: --snapshots - - New value for the snapshots quota - -.. option:: --volume-type - - Set quotas for a specific - -.. option:: --networks - - New value for the networks quota - -.. option:: --subnets - - New value for the subnets quota - -.. option:: --ports - - New value for the ports quota - -.. option:: --routers - - New value for the routers quota - -.. option:: --rbac-policies - - New value for the rbac-policies quota - -.. option:: --vips - - New value for the vips quota - -.. option:: --subnetpools - - New value for the subnetpools quota - -.. option:: --members - - New value for the members quota - -.. option:: --health-monitors - - New value for the health-monitors quota - -quota show ----------- - -Show quotas for project or class - -.. program:: quota show -.. code:: bash - - os quota show - [--default] - [] - - -.. option:: --default - - Show default quotas for :ref:`\ ` - -.. _quota_show-project: -.. describe:: - - Show quotas for this project (name or ID) - -.. code:: bash - - os quota show - --class - [] - -.. option:: --class - - Show quotas for :ref:`\ ` - -.. _quota_show-class: -.. describe:: - - Show quotas for this class (name or ID) diff --git a/doc/source/command-objects/region.rst b/doc/source/command-objects/region.rst deleted file mode 100644 index 1892fc244f..0000000000 --- a/doc/source/command-objects/region.rst +++ /dev/null @@ -1,104 +0,0 @@ -====== -region -====== - -Identity v3 - -region create -------------- - -Create new region - -.. program:: region create -.. code:: bash - - os region create - [--parent-region ] - [--description ] - - -.. option:: --parent-region - - Parent region ID - -.. option:: --description - - New region description - -.. _region_create-region-id: -.. describe:: - - New region ID - -region delete -------------- - -Delete region - -.. program:: region delete -.. code:: bash - - os region delete - - -.. _region_delete-region-id: -.. describe:: - - Region ID to delete - -region list ------------ - -List regions - -.. program:: region list -.. code:: bash - - os region list - [--parent-region ] - -.. option:: --parent-region - - Filter by parent region ID - -region set ----------- - -Set region properties - -.. program:: region set -.. code:: bash - - os region set - [--parent-region ] - [--description ] - - -.. option:: --parent-region - - New parent region ID - -.. option:: --description - - New region description - -.. _region_set-region-id: -.. describe:: - - Region to modify - -region show ------------ - -Display region details - -.. program:: region show -.. code:: bash - - os region show - - -.. _region_show-region-id: -.. describe:: - - Region to display diff --git a/doc/source/command-objects/request-token.rst b/doc/source/command-objects/request-token.rst deleted file mode 100644 index 84081cb17b..0000000000 --- a/doc/source/command-objects/request-token.rst +++ /dev/null @@ -1,57 +0,0 @@ -============= -request token -============= - -Identity v3 - -`Requires: OS-OAUTH1 extension` - -request token authorize ------------------------ - -Authorize a request token - -.. program:: request token authorize -.. code:: bash - - os request token authorize - --request-key - --role - -.. option:: --request-key - - Request token to authorize (ID only) (required) - -.. option:: --role - - Roles to authorize (name or ID) (repeat to set multiple values) (required) - -request token create --------------------- - -Create a request token - -.. program:: request token create -.. code:: bash - - os request token create - --consumer-key - --consumer-secret - --project - [--domain ] - -.. option:: --consumer-key - - Consumer key (required) - -.. option:: --description - - Consumer secret (required) - -.. option:: --project - - Project that consumer wants to access (name or ID) (required) - -.. option:: --domain - - Domain owning (name or ID) diff --git a/doc/source/command-objects/role-assignment.rst b/doc/source/command-objects/role-assignment.rst deleted file mode 100644 index 893ebdc4e9..0000000000 --- a/doc/source/command-objects/role-assignment.rst +++ /dev/null @@ -1,72 +0,0 @@ -=============== -role assignment -=============== - -Identity v3 - -role assignment list --------------------- - -List role assignments - -.. program:: role assignment list -.. code:: bash - - os role assignment list - [--role ] - [--user ] - [--user-domain ] - [--group ] - [--group-domain ] - [--domain ] - [--project ] - [--project-domain ] - [--effective] - [--inherited] - -.. option:: --role - - Role to filter (name or ID) - -.. option:: --user - - User to filter (name or ID) - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - -.. option:: --group - - Group to filter (name or ID) - -.. option:: --group-domain - - Domain the group belongs to (name or ID). - This can be used in case collisions between group names exist. - -.. option:: --domain - - Domain to filter (name or ID) - -.. option:: --project - - Project to filter (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --effective - - Returns only effective role assignments (defaults to False) - -.. option:: --inherited - - Specifies if the role grant is inheritable to the sub projects - -.. option:: --names - - Returns role assignments with names instead of IDs diff --git a/doc/source/command-objects/role.rst b/doc/source/command-objects/role.rst deleted file mode 100644 index 48751ed7bb..0000000000 --- a/doc/source/command-objects/role.rst +++ /dev/null @@ -1,273 +0,0 @@ -==== -role -==== - -Identity v2, v3 - -role add --------- - -Add role to a user or group in a project or domain - -.. program:: role add -.. code:: bash - - os role add - --domain | --project [--project-domain ] - --user [--user-domain ] | --group [--group-domain ] - --inherited - - -.. option:: --domain - - Include (name or ID) - - .. versionadded:: 3 - -.. option:: --project - - Include (name or ID) - -.. option:: --user - - Include (name or ID) - -.. option:: --group - - Include (name or ID) - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -.. option:: --group-domain - - Domain the group belongs to (name or ID). - This can be used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - .. versionadded:: 3 - -.. option:: --inherited - - Specifies if the role grant is inheritable to the sub projects. - - .. versionadded:: 3 - -.. describe:: - - Role to add to : (name or ID) - -role create ------------ - -Create new role - -.. program:: role create -.. code:: bash - - os role create - [--or-show] - - -.. option:: --or-show - - Return existing role - - If the role already exists return the existing role data and do not fail. - -.. describe:: - - New role name - -role delete ------------ - -Delete role(s) - -.. program:: role delete -.. code:: bash - - os role delete - [ ...] - -.. describe:: - - Role to delete (name or ID) - -role list ---------- - -List roles - -.. program:: role list -.. code:: bash - - os role list - --domain | --project [--project-domain ] - --user [--user-domain ] | --group [--group-domain ] - --inherited - -.. option:: --domain - - Filter roles by (name or ID) - - .. versionadded:: 3 - -.. option:: --project - - Filter roles by (name or ID) - - .. versionadded:: 3 - -.. option:: --user - - Filter roles by (name or ID) - - .. versionadded:: 3 - -.. option:: --group - - Filter roles by (name or ID) - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -.. option:: --group-domain - - Domain the group belongs to (name or ID). - This can be used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - .. versionadded:: 3 - -.. option:: --inherited - - Specifies if the role grant is inheritable to the sub projects. - - .. versionadded:: 3 - -role remove ------------ - -Remove role from domain/project : user/group - -.. program:: role remove -.. code:: bash - - os role remove - --domain | --project [--project-domain ] - --user [--user-domain ] | --group [--group-domain ] - --inherited - - -.. option:: --domain - - Include (name or ID) - - .. versionadded:: 3 - -.. option:: --project - - Include (name or ID) - -.. option:: --user - - Include (name or ID) - -.. option:: --group - - Include (name or ID) - - .. versionadded:: 3 - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - - .. versionadded:: 3 - -.. option:: --group-domain - - Domain the group belongs to (name or ID). - This can be used in case collisions between group names exist. - - .. versionadded:: 3 - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - .. versionadded:: 3 - -.. option:: --inherited - - Specifies if the role grant is inheritable to the sub projects. - - .. versionadded:: 3 - -.. describe:: - - Role to remove (name or ID) - -role set --------- - -Set role properties - -.. versionadded:: 3 - -.. program:: role set -.. code:: bash - - os role set - [--name ] - - -.. option:: --name - - Set role name - -.. describe:: - - Role to modify (name or ID) - -role show ---------- - -Display role details - -.. program:: role show -.. code:: bash - - os role show - - -.. describe:: - - Role to display (name or ID) diff --git a/doc/source/command-objects/router.rst b/doc/source/command-objects/router.rst deleted file mode 100644 index bbdca054eb..0000000000 --- a/doc/source/command-objects/router.rst +++ /dev/null @@ -1,266 +0,0 @@ -====== -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 - -router add port ---------------- - -Add a port to a router - -.. program:: router add port -.. code:: bash - - os router add port - - - -.. _router_add_port: - -.. describe:: - - Router to which port will be added (name or ID) - -.. describe:: - - Port to be added (name or ID) - -router add subnet ------------------ - -Add a subnet to a router - -.. program:: router add subnet -.. code:: bash - - os router add subnet - - - -.. _router_add_subnet: - -.. describe:: - - Router to which subnet will be added (name or ID) - -.. describe:: - - Subnet to be added (name or ID) - -router create -------------- - -Create new router - -.. program:: router create -.. code:: bash - - os router create - [--project [--project-domain ]] - [--enable | --disable] - [--distributed] - [--availability-zone-hint ] - - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --enable - - Enable router (default) - -.. option:: --disable - - Disable router - -.. option:: --distributed - - Create a distributed router - -.. option:: --availability-zone-hint - - Availability Zone in which to create this router - (Router Availability Zone extension required, - repeat option to set multiple availability zones) - -.. _router_create-name: -.. describe:: - - New router name - -router delete -------------- - -Delete router(s) - -.. program:: router delete -.. code:: bash - - os router delete - [ ...] - -.. _router_delete-router: -.. describe:: - - Router(s) to delete (name or ID) - -router list ------------ - -List routers - -.. program:: router list -.. code:: bash - - os router list - [--long] - -.. option:: --long - - List additional fields in output - -router remove port ------------------- - -Remove a port from a router - -.. program:: router remove port -.. code:: bash - - os router remove port - - - -.. _router_remove_port: - -.. describe:: - - Router from which port will be removed (name or ID) - -.. describe:: - - Port to be removed and deleted (name or ID) - -router remove subnet --------------------- - -Remove a subnet from a router - -.. program:: router remove subnet -.. code:: bash - - os router remove subnet - - - -.. _router_remove_subnet: - -.. describe:: - - Router from which subnet will be removed (name or ID) - -.. describe:: - - Subnet to be removed (name or ID) - -router set ----------- - -Set router properties - -.. program:: router set -.. code:: bash - - os router set - [--name ] - [--enable | --disable] - [--distributed | --centralized] - [--route destination=,gateway= | --no-route] - - -.. option:: --name - - Set router name - -.. option:: --enable - - Enable router - -.. option:: --disable - - Disable router - -.. option:: --distributed - - Set router to distributed mode (disabled router only) - -.. option:: --centralized - - Set router to centralized mode (disabled router only) - -.. option:: --route destination=,gateway= - - Routes associated with the router - destination: destination subnet (in CIDR notation) - gateway: nexthop IP address - (repeat option to set multiple routes) - -.. option:: --no-route - - Clear routes associated with the router - -.. _router_set-router: -.. describe:: - - Router to modify (name or ID) - -router show ------------ - -Display router details - -.. program:: router show -.. code:: bash - - os router show - - -.. _router_show-router: -.. describe:: - - Router to display (name or ID) - -router unset ------------- - -Unset router properties - -.. program:: router unset -.. code:: bash - - os router unset - [--route destination=,gateway=] - - -.. option:: --route destination=,gateway= - - Routes to be removed from the router - destination: destination subnet (in CIDR notation) - gateway: nexthop IP address - (repeat option to unset multiple routes) - -.. _router_unset-router: -.. describe:: - - Router to modify (name or ID) diff --git a/doc/source/command-objects/security-group-rule.rst b/doc/source/command-objects/security-group-rule.rst deleted file mode 100644 index 5284b2dc22..0000000000 --- a/doc/source/command-objects/security-group-rule.rst +++ /dev/null @@ -1,162 +0,0 @@ -=================== -security group rule -=================== - -A **security group rule** specifies the network access rules for servers -and other resources on the network. - -Compute v2, Network v2 - -security group rule create --------------------------- - -Create a new security group rule - -.. program:: security group rule create -.. code:: bash - - os security group rule create - [--src-ip | --src-group ] - [--dst-port | [--icmp-type [--icmp-code ]]] - [--protocol ] - [--ingress | --egress] - [--ethertype ] - [--project [--project-domain ]] - - -.. option:: --src-ip - - Source IP address block - (may use CIDR notation; default for IPv4 rule: 0.0.0.0/0) - -.. option:: --src-group - - Source security group (name or ID) - -.. option:: --dst-port - - Destination port, may be a single port or a starting and - ending port range: 137:139. Required for IP protocols TCP - and UDP. Ignored for ICMP IP protocols. - -.. option:: --icmp-type - - ICMP type for ICMP IP protocols - - *Network version 2 only* - -.. option:: --icmp-code - - ICMP code for ICMP IP protocols - - *Network version 2 only* - -.. option:: --protocol - - IP protocol (icmp, tcp, udp; default: tcp) - - *Compute version 2* - - IP protocol (ah, dccp, egp, esp, gre, icmp, igmp, - ipv6-encap, ipv6-frag, ipv6-icmp, ipv6-nonxt, - ipv6-opts, ipv6-route, ospf, pgm, rsvp, sctp, tcp, - udp, udplite, vrrp and integer representations [0-255]; - default: tcp) - - *Network version 2* - -.. option:: --ingress - - Rule applies to incoming network traffic (default) - - *Network version 2 only* - -.. option:: --egress - - Rule applies to outgoing network traffic - - *Network version 2 only* - -.. option:: --ethertype - - Ethertype of network traffic - (IPv4, IPv6; default: based on IP protocol) - - *Network version 2 only* - -.. option:: --project - - Owner's project (name or ID) - - *Network version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - *Network version 2 only* - -.. describe:: - - Create rule in this security group (name or ID) - -security group rule delete --------------------------- - -Delete security group rule(s) - -.. program:: security group rule delete -.. code:: bash - - os security group rule delete - [ ...] - -.. describe:: - - Security group rule(s) to delete (ID only) - -security group rule list ------------------------- - -List security group rules - -.. program:: security group rule list -.. code:: bash - - os security group rule list - [--all-projects] - [--long] - [] - -.. option:: --all-projects - - Display information from all projects (admin only) - - *Network version 2 ignores this option and will always display information* - *for all projects (admin only).* - -.. option:: --long - - List additional fields in output - - *Compute version 2 does not have additional fields to display.* - -.. describe:: - - List all rules in this security group (name or ID) - -security group rule show ------------------------- - -Display security group rule details - -.. program:: security group rule show -.. code:: bash - - os security group rule show - - -.. describe:: - - Security group rule to display (ID only) diff --git a/doc/source/command-objects/security-group.rst b/doc/source/command-objects/security-group.rst deleted file mode 100644 index ba054554df..0000000000 --- a/doc/source/command-objects/security-group.rst +++ /dev/null @@ -1,116 +0,0 @@ -============== -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 - -security group create ---------------------- - -Create a new security group - -.. program:: security group create -.. code:: bash - - os security group create - [--description ] - [--project [--project-domain ]] - - -.. option:: --description - - Security group description - -.. option:: --project - - Owner's project (name or ID) - - *Network version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - - *Network version 2 only* - -.. describe:: - - New security group name - -security group delete ---------------------- - -Delete security group(s) - -.. program:: security group delete -.. code:: bash - - os security group delete - [ ...] - -.. describe:: - - Security group(s) to delete (name or ID) - -security group list -------------------- - -List security groups - -.. program:: security group list -.. code:: bash - - os security group list - [--all-projects] - -.. option:: --all-projects - - Display information from all projects (admin only) - - *Network version 2 ignores this option and will always display information* - *for all projects (admin only).* - -security group set ------------------- - -Set security group properties - -.. program:: security group set -.. code:: bash - - os security group set - [--name ] - [--description ] - - -.. option:: --name - - New security group name - -.. option:: --description - - New security group description - -.. describe:: - - Security group to modify (name or ID) - -security group show -------------------- - -Display security group details - -.. program:: security group show -.. code:: bash - - os security group show - - -.. describe:: - - Security group to display (name or ID) diff --git a/doc/source/command-objects/server-backup.rst b/doc/source/command-objects/server-backup.rst deleted file mode 100644 index 23e17d5f5d..0000000000 --- a/doc/source/command-objects/server-backup.rst +++ /dev/null @@ -1,44 +0,0 @@ -============= -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 - -server backup create --------------------- - -Create a server backup image - -.. program:: server create -.. code:: bash - - os server backup create - [--name ] - [--type ] - [--rotate ] - [--wait] - - -.. option:: --name - - Name of the backup image (default: server name) - -.. option:: --type - - Used to populate the ``backup_type`` property of the backup - image (default: empty) - -.. option:: --rotate - - Number of backup images to keep (default: 1) - -.. option:: --wait - - Wait for operation to complete - -.. describe:: - - Server to back up (name or ID) diff --git a/doc/source/command-objects/server-group.rst b/doc/source/command-objects/server-group.rst deleted file mode 100644 index 414f49b1aa..0000000000 --- a/doc/source/command-objects/server-group.rst +++ /dev/null @@ -1,80 +0,0 @@ -============ -server group -============ - -Server group provides a mechanism to group servers according to certain policy. - -Compute v2 - -server group create -------------------- - -Create a new server group - -.. program:: server group create -.. code-block:: bash - - os server group create - --policy [--policy ] ... - - -.. option:: --policy - - Add a policy to :ref:`\ ` - (repeat option to add multiple policies) - -.. _server_group_create-name: -.. describe:: - - New server group name - -server group delete -------------------- - -Delete existing server group(s) - -.. program:: server group delete -.. code-block:: bash - - os server group delete - [ ...] - -.. describe:: - - Server group(s) to delete (name or ID) - (repeat to delete multiple server groups) - -server group list ------------------ - -List all server groups - -.. program:: server group list -.. code-block:: bash - - os server group list - [--all-projects] - [--long] - -.. option:: --all-projects - - Display information from all projects (admin only) - -.. option:: --long - - List additional fields in output - -server group show ------------------ - -Display server group details - -.. program:: server group show -.. code-block:: bash - - os server group show - - -.. describe:: - - Server group to display (name or ID) diff --git a/doc/source/command-objects/server-image.rst b/doc/source/command-objects/server-image.rst deleted file mode 100644 index eb44e47e07..0000000000 --- a/doc/source/command-objects/server-image.rst +++ /dev/null @@ -1,33 +0,0 @@ -============ -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 - -server image create -------------------- - -Create a new server disk image from an existing server - -.. program:: server image create -.. code:: bash - - os server image create - [--name ] - [--wait] - - -.. option:: --name - - Name of new disk image (default: server name) - -.. option:: --wait - - Wait for operation to complete - -.. describe:: - - Server to create image (name or ID) diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst deleted file mode 100644 index f099c271c9..0000000000 --- a/doc/source/command-objects/server.rst +++ /dev/null @@ -1,874 +0,0 @@ -====== -server -====== - -Compute v2 - -server add fixed ip -------------------- - -Add fixed IP address to server - -.. program:: server add fixed ip -.. code:: bash - - os server add fixed ip - - - -.. describe:: - - Server (name or ID) to receive the fixed IP address - -.. describe:: - - Network (name or ID) to allocate the fixed IP address from - -server add floating ip ----------------------- - -Add floating IP address to server - -.. program:: server add floating ip -.. code:: bash - - os server add floating ip - - - -.. describe:: - - Server (name or ID) to receive the floating IP address - -.. describe:: - - Floating IP address (IP address only) to assign to server - -server add security group -------------------------- - -Add security group to server - -.. program:: server add security group -.. code:: bash - - os server add security group - - - -.. describe:: - - Server (name or ID) - -.. describe:: - - Security group to add (name or ID) - -server add volume ------------------ - -Add volume to server - -.. program:: server add volume -.. code:: bash - - os server add volume - [--device ] - - - -.. option:: --device - - Server internal device name for volume - -.. describe:: - - Server (name or ID) - -.. describe:: - - Volume to add (name or ID) - -server create -------------- - -Create a new server - -.. program:: server create -.. code:: bash - - os server create - --image | --volume - --flavor - [--security-group [...] ] - [--key-name ] - [--property [...] ] - [--file ] [...] ] - [--user-data ] - [--availability-zone ] - [--block-device-mapping [...] ] - [--nic [...] ] - [--hint [...] ] - [--config-drive |True ] - [--min ] - [--max ] - [--wait] - - -.. option:: --image - - Create server from this image (name or ID) - -.. option:: --volume - - Create server from this volume (name or ID) - -.. option:: --flavor - - Create server with this flavor (name or ID) - -.. option:: --security-group - - Security group to assign to this server (name or ID) - (repeat option to set multiple groups) - -.. option:: --key-name - - Keypair to inject into this server (optional extension) - -.. option:: --property - - Set a property on this server - (repeat option to set multiple values) - -.. option:: --file - - File to inject into image before boot - (repeat option to set multiple files) - -.. option:: --user-data - - User data file to serve from the metadata server - -.. option:: --availability-zone - - Select an availability zone for the server - -.. option:: --block-device-mapping - - Map block devices; map is ::: (optional extension) - -.. option:: --nic - - Create a NIC on the server. Specify option multiple times to create - multiple NICs. Either net-id or port-id must be provided, but not both. - net-id: attach NIC to network with this UUID, - port-id: attach NIC to port with this UUID, - v4-fixed-ip: IPv4 fixed address for NIC (optional), - v6-fixed-ip: IPv6 fixed address for NIC (optional). - -.. option:: --hint - - Hints for the scheduler (optional extension) - -.. option:: --config-drive |True - - Use specified volume as the config drive, or 'True' to use an ephemeral drive - -.. option:: --min - - Minimum number of servers to launch (default=1) - -.. option:: --max - - Maximum number of servers to launch (default=1) - -.. option:: --wait - - Wait for build to complete - -.. describe:: - - New server name - -server delete -------------- - -Delete server(s) - -.. program:: server delete -.. code:: bash - - os server delete - [ ...] [--wait] - -.. option:: --wait - - Wait for delete to complete - -.. describe:: - - Server(s) to delete (name or ID) - -server dump create ------------------- -Create a dump file in server(s) - -Trigger crash dump in server(s) with features like kdump in Linux. It will -create a dump file in the server(s) dumping the server(s)' memory, and also -crash the server(s). OSC sees the dump file (server dump) as a kind of -resource. - -.. program:: server dump create -.. code:: bash - - os server dump create - [ ...] - -.. describe:: - - Server(s) to create dump file (name or ID) - -server list ------------ - -List servers - -.. code:: bash - - os server list - [--reservation-id ] - [--ip ] - [--ip6 ] - [--name ] - [--instance-name ] - [--status ] - [--flavor ] - [--image ] - [--host ] - [--all-projects] - [--project [--project-domain ]] - [--long] - [--marker ] - [--limit ] - -.. option:: --reservation-id - - Only return instances that match the reservation - -.. option:: --ip - - Regular expression to match IP addresses - -.. option:: --ip6 - - Regular expression to match IPv6 addresses - -.. option:: --name - - Regular expression to match names - -.. option:: --instance-name - - Regular expression to match instance name (admin only) - -.. option:: --status - - Search by server status - -.. option:: --flavor - - Search by flavor (name or ID) - -.. option:: --image - - Search by image (name or ID) - -.. option:: --host - - Search by hostname - -.. option:: --all-projects - - Include all projects (admin only) - -.. option:: --project - - Search by project (admin only) (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --user - - Search by user (admin only) (name or ID) - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - This can be used in case collisions between user names exist. - -.. option:: --long - - List additional fields in output - -.. option:: --marker - - The last server (name or ID) of the previous page. Display list of servers - after marker. Display all servers if not specified. - -.. option:: --limit - - Maximum number of servers to display. If limit equals -1, all servers will - be displayed. If limit is greater than 'osapi_max_limit' option of Nova - API, 'osapi_max_limit' will be used instead. - -server lock ------------ - -Lock server(s). A non-admin user will not be able to execute actions - -.. program:: server lock -.. code:: bash - - os server lock - [ ...] - -.. describe:: - - Server(s) to lock (name or ID) - -server migrate --------------- - -Migrate server to different host - -.. program:: server migrate -.. code:: bash - - os server migrate - --live - [--shared-migration | --block-migration] - [--disk-overcommit | --no-disk-overcommit] - [--wait] - - -.. option:: --live - - Target hostname - -.. option:: --shared-migration - - Perform a shared live migration (default) - -.. option:: --block-migration - - Perform a block live migration - -.. option:: --disk-overcommit - - Allow disk over-commit on the destination host - -.. option:: --no-disk-overcommit - - Do not over-commit disk on the destination host (default) - -.. option:: --wait - - Wait for resize to complete - -.. describe:: - - Server to migrate (name or ID) - -server pause ------------- - -Pause server(s) - -.. program:: server pause -.. code:: bash - - os server pause - [ ...] - -.. describe:: - - Server(s) to pause (name or ID) - -server reboot -------------- - -Perform a hard or soft server reboot - -.. program:: server reboot -.. code:: bash - - os server reboot - [--hard | --soft] - [--wait] - - -.. option:: --hard - - Perform a hard reboot - -.. option:: --soft - - Perform a soft reboot - -.. option:: --wait - - Wait for reboot to complete - -.. describe:: - - Server (name or ID) - -server rebuild --------------- - -Rebuild server - -.. program:: server rebuild -.. code:: bash - - os server rebuild - [--image ] - [--password ] - [--wait] - - -.. option:: --image - - Recreate server from the specified image (name or ID). Defaults to the - currently used one. - -.. option:: --password - - Set the password on the rebuilt instance - -.. option:: --wait - - Wait for rebuild to complete - -.. describe:: - - Server (name or ID) - -server remove fixed ip ----------------------- - -Remove fixed IP address from server - -.. program:: server remove fixed ip -.. code:: bash - - os server remove fixed ip - - - -.. describe:: - - Server (name or ID) to remove the fixed IP address from - -.. describe:: - - Fixed IP address (IP address only) to remove from the server - -server remove floating ip -------------------------- - -Remove floating IP address from server - -.. program:: server remove floating ip -.. code:: bash - - os server remove floating ip - - - -.. describe:: - - Server (name or ID) to remove the floating IP address from - -.. describe:: - - Floating IP address (IP address only) to remove from server - -server remove security group ----------------------------- - -Remove security group from server - -.. program:: server remove security group -.. code:: bash - - os server remove security group - - - -.. describe:: - - Name or ID of server to use - -.. describe:: - - Name or ID of security group to remove from server - -server remove volume --------------------- - -Remove volume from server - -.. program:: server remove volume -.. code:: bash - - os server remove volume - - - -.. describe:: - - Server (name or ID) - -.. describe:: - - Volume to remove (name or ID) - -server rescue -------------- - -Put server in rescue mode - -.. program:: server rescue -.. code:: bash - - os server rescue - - -.. describe:: - - Server (name or ID) - -server resize -------------- - -Scale server to a new flavor - -.. program:: server resize -.. code:: bash - - os server resize - --flavor - [--wait] - - - os server resize - --confirm | --revert - - -.. option:: --flavor - - Resize server to specified flavor - -.. option:: --confirm - - Confirm server resize is complete - -.. option:: --revert - - Restore server state before resize - -.. option:: --wait - - Wait for resize to complete - -.. describe:: - - Server (name or ID) - -A resize operation is implemented by creating a new server and copying -the contents of the original disk into a new one. It is also a two-step -process for the user: the first is to perform the resize, the second is -to either confirm (verify) success and release the old server, or to declare -a revert to release the new server and restart the old one. - -server restore --------------- - -Restore server(s) from soft-deleted state - -.. program:: server restore -.. code:: bash - - os server restore - [ ...] - -.. describe:: - - Server(s) to restore (name or ID) - -server resume -------------- - -Resume server(s) - -.. program:: server resume -.. code:: bash - - os server resume - [ ...] - -.. describe:: - - Server(s) to resume (name or ID) - -server set ----------- - -Set server properties - -.. program:: server set -.. code:: bash - - os server set - --name - --property - [--property ] ... - --root-password - --state - - -.. option:: --name - - New server name - -.. option:: --root-password - - Set new root password (interactive only) - -.. option:: --property - - Property to add/change for this server - (repeat option to set multiple properties) - -.. option:: --state - - New server state (valid value: active, error) - -.. describe:: - - Server (name or ID) - -server shelve -------------- - -Shelve server(s) - -.. program:: server shelve -.. code:: bash - - os server shelve - [ ...] - -.. describe:: - - Server(s) to shelve (name or ID) - -server show ------------ - -Show server details - -.. program:: server show -.. code:: bash - - os server show - [--diagnostics] - - -.. option:: --diagnostics - - Display server diagnostics information - -.. describe:: - - Server (name or ID) - -server ssh ----------- - -SSH to server - -.. program:: server ssh -.. code:: bash - - os server ssh - [--login ] - [--port ] - [--identity ] - [--option ] - [--public | --private | --address-type ] - - -.. option:: --login - - Login name (ssh -l option) - -.. option:: --port - - Destination port (ssh -p option) - -.. option:: --identity - - Private key file (ssh -i option) - -.. option:: --option - - Options in ssh_config(5) format (ssh -o option) - -.. option:: --public - - Use public IP address - -.. option:: --private - - Use private IP address - -.. option:: --address-type - - Use other IP address (public, private, etc) - -.. describe:: - - Server (name or ID) - -server start ------------- - -Start server(s) - -.. program:: server start -.. code:: bash - - os server start - [ ...] - -.. describe:: - - Server(s) to start (name or ID) - -server stop ------------ - -Stop server(s) - -.. program:: server stop -.. code:: bash - - os server stop - [ ...] - -.. describe:: - - Server(s) to stop (name or ID) - -server suspend --------------- - -Suspend server(s) - -.. program:: server suspend -.. code:: bash - - os server suspend - [ ...] - -.. describe:: - - Server(s) to suspend (name or ID) - -server unlock -------------- - -Unlock server(s) - -.. program:: server unlock -.. code:: bash - - os server unlock - [ ...] - -.. describe:: - - Server(s) to unlock (name or ID) - -server unpause --------------- - -Unpause server(s) - -.. program:: server unpause -.. code:: bash - - os server unpause - [ ...] - -.. describe:: - - Server(s) to unpause (name or ID) - -server unrescue ---------------- - -Restore server from rescue mode - -.. program:: server unrescue -.. code:: bash - - os server unrescue - - -.. describe:: - - Server (name or ID) - -server unset ------------- - -Unset server properties - -.. program:: server unset -.. code:: bash - - os server unset - --property - [--property ] ... - - -.. option:: --property - - Property key to remove from server - (repeat option to remove multiple values) - -.. describe:: - - Server (name or ID) - -server unshelve ---------------- - -Unshelve server(s) - -.. program:: server unshelve -.. code:: bash - - os server unshelve - [ ...] - -.. describe:: - - Server(s) to unshelve (name or ID) diff --git a/doc/source/command-objects/service-provider.rst b/doc/source/command-objects/service-provider.rst deleted file mode 100644 index 963493b4a2..0000000000 --- a/doc/source/command-objects/service-provider.rst +++ /dev/null @@ -1,125 +0,0 @@ -================ -service provider -================ - -Identity v3 - -`Requires: OS-FEDERATION extension` - -service provider create ------------------------ - -Create new service provider - -.. program:: service provider create -.. code:: bash - - os service provider create - [--description ] - [--enable | --disable] - --auth-url - --service-provider-url - - -.. option:: --auth-url - - Authentication URL of remote federated service provider (required) - -.. option:: --service-provider-url - - A service URL where SAML assertions are being sent (required) - -.. option:: --description - - New service provider description - -.. option:: --enable - - Enable the service provider (default) - -.. option:: --disable - - Disable the service provider - -.. describe:: - - New service provider name (must be unique) - -service provider delete ------------------------ - -Delete service provider - -.. program:: service provider delete -.. code:: bash - - os service provider delete - - -.. describe:: - - Service provider to delete - -service provider list ---------------------- - -List service providers - -.. program:: service provider list -.. code:: bash - - os service provider list - -service provider set --------------------- - -Set service provider properties - -.. program:: service provider set -.. code:: bash - - os service provider set - [--enable | --disable] - [--description ] - [--auth-url ] - [--service-provider-url ] - - -.. option:: --service-provider-url - - New service provider URL, where SAML assertions are sent - -.. option:: --auth-url - - New Authentication URL of remote federated service provider - -.. option:: --description - - New service provider description - -.. option:: --enable - - Enable the service provider - -.. option:: --disable - - Disable the service provider - -.. describe:: - - Service provider to modify - -service provider show ---------------------- - -Display service provider details - -.. program:: service provider show -.. code:: bash - - os service provider show - - -.. describe:: - - Service provider to display diff --git a/doc/source/command-objects/service.rst b/doc/source/command-objects/service.rst deleted file mode 100644 index b5ec2d9962..0000000000 --- a/doc/source/command-objects/service.rst +++ /dev/null @@ -1,143 +0,0 @@ -======= -service -======= - -Identity v2, v3 - -service create --------------- - -Create new service - -.. program:: service create -.. code-block:: bash - - os service create - [--name ] - [--description ] - [--enable | --disable] - - -.. option:: --name - - New service name - -.. option:: --description - - New service description - -.. option:: --enable - - Enable service (default) - - *Identity version 3 only* - -.. option:: --disable - - Disable service - - *Identity version 3 only* - -.. _service_create-type: -.. describe:: - - New service type (compute, image, identity, volume, etc) - -service delete --------------- - -Delete service(s) - -.. program:: service delete -.. code-block:: bash - - os service delete - [ ...] - -.. _service_delete-type: -.. describe:: - - Service(s) to delete (type, name or ID) - -service list ------------- - -List services - -.. program:: service list -.. code-block:: bash - - os service list - [--long] - -.. option:: --long - - List additional fields in output - -Returns service fields ID, Name and Type. :option:`--long` adds Description -and Enabled (*Identity version 3 only*) to the output. - -service set ------------ - -Set service properties - -* Identity version 3 only* - -.. program:: service set -.. code-block:: bash - - os service set - [--type ] - [--name ] - [--description ] - [--enable | --disable] - - -.. option:: --type - - New service type (compute, image, identity, volume, etc) - -.. option:: --name - - New service name - -.. option:: --description - - New service description - -.. option:: --enable - - Enable service - -.. option:: --disable - - Disable service - -.. _service_set-service: -.. describe:: - - Service to modify (type, name or ID) - -service show ------------- - -Display service details - -.. program:: service show -.. code-block:: bash - - os service show - [--catalog] - - -.. option:: --catalog - - Show service catalog information - - *Identity version 2 only* - -.. _service_show-service: -.. describe:: - - Service to display (type, name or ID) diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/command-objects/snapshot.rst deleted file mode 100644 index 8ac0b6b869..0000000000 --- a/doc/source/command-objects/snapshot.rst +++ /dev/null @@ -1,154 +0,0 @@ -======== -snapshot -======== - -Block Storage v1, v2 - -snapshot create ---------------- - -Create new snapshot - -.. program:: snapshot create -.. code:: bash - - os snapshot create - [--name ] - [--description ] - [--force] - [--property [...] ] - - -.. option:: --name - - Name of the snapshot - -.. option:: --description - - Description of the snapshot - -.. option:: --force - - Create a snapshot attached to an instance. Default is False - -.. option:: --property - - Set a property to this snapshot (repeat option to set multiple properties) - - *Volume version 2 only* - -.. _snapshot_create-snapshot: -.. describe:: - - Volume to snapshot (name or ID) - -snapshot delete ---------------- - -Delete snapshot(s) - -.. program:: snapshot delete -.. code:: bash - - os snapshot delete - [ ...] - -.. _snapshot_delete-snapshot: -.. describe:: - - Snapshot(s) to delete (name or ID) - -snapshot list -------------- - -List snapshots - -.. program:: snapshot list -.. code:: bash - - os snapshot list - [--all-projects] - -.. option:: --all-projects - - Include all projects (admin only) - -.. option:: --long - - List additional fields in output - -snapshot set ------------- - -Set snapshot properties - -.. program:: snapshot set -.. code:: bash - - os snapshot set - [--name ] - [--description ] - [--property [...] ] - [--state ] - - -.. _snapshot_restore-snapshot: -.. option:: --name - - New snapshot name - -.. option:: --description - - New snapshot description - -.. option:: --property - - Property to add or modify for this snapshot (repeat option to set multiple properties) - -.. option:: --state - - New snapshot state. - Valid values are "available", "error", "creating", - "deleting", and "error_deleting". - - *Volume version 2 only* - -.. describe:: - - Snapshot to modify (name or ID) - -snapshot show -------------- - -Display snapshot details - -.. program:: snapshot show -.. code:: bash - - os snapshot show - - -.. _snapshot_show-snapshot: -.. describe:: - - Snapshot to display (name or ID) - -snapshot unset --------------- - -Unset snapshot properties - -.. program:: snapshot unset -.. code:: bash - - os snapshot unset - [--property ] - - -.. option:: --property - - Property to remove from snapshot (repeat option to remove multiple properties) - -.. describe:: - - Snapshot to modify (name or ID) diff --git a/doc/source/command-objects/subnet-pool.rst b/doc/source/command-objects/subnet-pool.rst deleted file mode 100644 index 005b83579b..0000000000 --- a/doc/source/command-objects/subnet-pool.rst +++ /dev/null @@ -1,209 +0,0 @@ -=========== -subnet pool -=========== - -A **subnet pool** contains a collection of prefixes in CIDR notation -that are available for IP address allocation. - -Network v2 - -subnet pool create ------------------- - -Create subnet pool - -.. program:: subnet pool create -.. code:: bash - - os subnet pool create - [--default-prefix-length ] - [--min-prefix-length ] - [--max-prefix-length ] - [--project [--project-domain ]] - [--address-scope ] - [--default | --no-default] - [--share | --no-share] - --pool-prefix [...] - - -.. option:: --default-prefix-length - - Set subnet pool default prefix length - -.. option:: --min-prefix-length - - Set subnet pool minimum prefix length - -.. option:: --max-prefix-length - - Set subnet pool maximum prefix length - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be used in case - collisions between project names exist. - -.. option:: --address-scope - - Set address scope associated with the subnet pool (name or ID), - prefixes must be unique across address scopes - -.. option:: --default - - Set this as a default subnet pool - -.. option:: --no-default - - Set this as a non-default subnet pool - -.. option:: --share - - Set this subnet pool as shared - -.. option:: --no-share - - Set this subnet pool as not shared - -.. describe:: --pool-prefix - - Set subnet pool prefixes (in CIDR notation) - (repeat option to set multiple prefixes) - -.. _subnet_pool_create-name: -.. describe:: - - Name of the new subnet pool - -subnet pool delete ------------------- - -Delete subnet pool(s) - -.. program:: subnet pool delete -.. code:: bash - - os subnet pool delete - [ ...] - -.. _subnet_pool_delete-subnet-pool: -.. describe:: - - Subnet pool(s) to delete (name or ID) - -subnet pool list ----------------- - -List subnet pools - -.. program:: subnet pool list -.. code:: bash - - os subnet pool list - [--long] - -.. option:: --long - - List additional fields in output - -subnet pool set ---------------- - -Set subnet pool properties - -.. program:: subnet pool set -.. code:: bash - - os subnet pool set - [--name ] - [--pool-prefix [...]] - [--default-prefix-length ] - [--min-prefix-length ] - [--max-prefix-length ] - [--address-scope | --no-address-scope] - [--default | --no-default] - - -.. option:: --name - - Set subnet pool name - -.. option:: --pool-prefix - - Set subnet pool prefixes (in CIDR notation) - (repeat option to set multiple prefixes) - -.. option:: --default-prefix-length - - Set subnet pool default prefix length - -.. option:: --min-prefix-length - - Set subnet pool minimum prefix length - -.. option:: --max-prefix-length - - Set subnet pool maximum prefix length - -.. option:: --address-scope - - Set address scope associated with the subnet pool (name or ID), - prefixes must be unique across address scopes - -.. option:: --no-address-scope - - Remove address scope associated with the subnet pool - -.. option:: --default - - Set this as a default subnet pool - -.. option:: --no-default - - Set this as a non-default subnet pool - -.. _subnet_pool_set-subnet-pool: -.. describe:: - - Subnet pool to modify (name or ID) - -subnet pool show ----------------- - -Display subnet pool details - -.. program:: subnet pool show -.. code:: bash - - os subnet pool show - - -.. _subnet_pool_show-subnet-pool: -.. describe:: - - Subnet pool to display (name or ID) - -subnet pool unset ------------------ - -Unset subnet pool properties - -.. program:: subnet pool unset -.. code:: bash - - os subnet pool unset - [--pool-prefix [...]] - - -.. option:: --pool-prefix - - Remove subnet pool prefixes (in CIDR notation). - (repeat option to unset multiple prefixes). - -.. _subnet_pool_unset-subnet-pool: -.. describe:: - - Subnet pool to modify (name or ID) diff --git a/doc/source/command-objects/subnet.rst b/doc/source/command-objects/subnet.rst deleted file mode 100644 index f0d5e90aa7..0000000000 --- a/doc/source/command-objects/subnet.rst +++ /dev/null @@ -1,276 +0,0 @@ -====== -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 - -subnet create -------------- - -Create new subnet - -.. program:: subnet create -.. code:: bash - - os subnet create - [--project [--project-domain ]] - [--subnet-pool | --use-default-subnet-pool [--prefix-length ]] - [--subnet-range ] - [--allocation-pool start=,end=] - [--dhcp | --no-dhcp] - [--dns-nameserver ] - [--gateway ] - [--host-route destination=,gateway=] - [--ip-version {4,6}] - [--ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}] - [--ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}] - [--network-segment ] - --network - - -.. option:: --project - - Owner's project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --subnet-pool - - Subnet pool from which this subnet will obtain a CIDR (name or ID) - -.. option:: --use-default-subnet-pool - - Use default subnet pool for ``--ip-version`` - -.. option:: --prefix-length - - Prefix length for subnet allocation from subnet pool - -.. option:: --subnet-range - - Subnet range in CIDR notation - (required if ``--subnet-pool`` is not specified, optional otherwise) - -.. option:: --allocation-pool start=,end= - - Allocation pool IP addresses for this subnet e.g.: - ``start=192.168.199.2,end=192.168.199.254`` - (repeat option to add multiple IP addresses) - -.. option:: --dhcp - - Enable DHCP (default) - -.. option:: --no-dhcp - - Disable DHCP - -.. option:: --dns-nameserver - - DNS server for this subnet (repeat option to set multiple DNS servers) - -.. option:: --gateway - - Specify a gateway for the subnet. The three options are: - : Specific IP address to use as the gateway, - 'auto': Gateway address should automatically be chosen from - within the subnet itself, 'none': This subnet will not use - a gateway, e.g.: ``--gateway 192.168.9.1``, ``--gateway auto``, - ``--gateway none`` (default is 'auto'). - -.. option:: --host-route destination=,gateway= - - Additional route for this subnet e.g.: - ``destination=10.10.0.0/16,gateway=192.168.71.254`` - destination: destination subnet (in CIDR notation) - gateway: nexthop IP address - (repeat option to add multiple routes) - -.. option:: --ip-version {4,6} - - IP version (default is 4). Note that when subnet pool is specified, - IP version is determined from the subnet pool and this option - is ignored. - -.. option:: --ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac} - - IPv6 RA (Router Advertisement) mode, - valid modes: [dhcpv6-stateful, dhcpv6-stateless, slaac] - -.. option:: --ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac} - - IPv6 address mode, valid modes: [dhcpv6-stateful, dhcpv6-stateless, slaac] - -.. option:: --network-segment - - Network segment to associate with this subnet (ID only) - - .. caution:: This is a beta command option and subject - to change. Use global option ``--os-beta-command`` - to enable this command option. - -.. option:: --network - - Network this subnet belongs to (name or ID) - -.. _subnet_create-name: -.. describe:: - - Name of subnet to create - -subnet delete -------------- - -Delete subnet(s) - -.. program:: subnet delete -.. code:: bash - - os subnet delete - [ ...] - -.. _subnet_delete-subnet: -.. describe:: - - Subnet(s) to delete (name or ID) - -subnet list ------------ - -List subnets - -.. program:: subnet list -.. code:: bash - - os subnet list - [--long] - -.. option:: --long - - List additional fields in output - -.. option:: --ip-version {4, 6} - - List only subnets of given IP version in output. - Allowed values for IP version are 4 and 6. - -subnet set ----------- - -Set subnet properties - -.. program:: subnet set -.. code:: bash - - os subnet set - [--allocation-pool start=,end=] - [--dhcp | --no-dhcp] - [--dns-nameserver ] - [--gateway ] - [--host-route destination=,gateway=] - [--name ] - - -.. option:: --allocation-pool start=,end= - - Allocation pool IP addresses for this subnet e.g.: - ``start=192.168.199.2,end=192.168.199.254`` - (repeat option to add multiple IP addresses) - -.. option:: --dhcp - - Enable DHCP - -.. option:: --no-dhcp - - Disable DHCP - -.. option:: --dns-nameserver - - DNS server for this subnet (repeat option to set multiple DNS servers) - -.. option:: --gateway - - Specify a gateway for the subnet. The options are: - : Specific IP address to use as the gateway, - 'none': This subnet will not use a gateway, - e.g.: ``--gateway 192.168.9.1``, ``--gateway none``. - -.. option:: --host-route destination=,gateway= - - Additional route for this subnet e.g.: - ``destination=10.10.0.0/16,gateway=192.168.71.254`` - destination: destination subnet (in CIDR notation) - gateway: nexthop IP address - (repeat option to add multiple routes) - -.. option:: --name - - Updated name of the subnet - -.. _subnet_set-subnet: -.. describe:: - - Subnet to modify (name or ID) - - -subnet show ------------ - -Display subnet details - -.. program:: subnet show -.. code:: bash - - os subnet show - - -.. _subnet_show-subnet: -.. describe:: - - Subnet to display (name or ID) - -subnet unset ------------- - -Unset subnet properties - -.. program:: subnet unset -.. code:: bash - - os subnet unset - [--allocation-pool start=,end= [...]] - [--dns-nameserver [...]] - [--host-route destination=,gateway= [...]] - - -.. option:: --dns-nameserver - - DNS server to be removed from this subnet - (repeat option to unset multiple DNS servers) - -.. option:: --allocation-pool start=,end= - - Allocation pool to be removed from this subnet e.g.: - ``start=192.168.199.2,end=192.168.199.254`` - (repeat option to unset multiple Allocation pools) - -.. option:: --host-route destination=,gateway= - - Route to be removed from this subnet e.g.: - ``destination=10.10.0.0/16,gateway=192.168.71.254`` - destination: destination subnet (in CIDR notation) - gateway: nexthop IP address - (repeat option to unset multiple host routes) - -.. _subnet_unset-subnet: -.. describe:: - - subnet to modify (name or ID) diff --git a/doc/source/command-objects/token.rst b/doc/source/command-objects/token.rst deleted file mode 100644 index 5e7c7b2686..0000000000 --- a/doc/source/command-objects/token.rst +++ /dev/null @@ -1,30 +0,0 @@ -===== -token -===== - -Identity v2, v3 - -token issue ------------ - -Issue new token - -.. program:: token issue -.. code:: bash - - os token issue - -token revoke ------------- - -Revoke existing token - -.. program:: token revoke -.. code:: bash - - os token revoke - - -.. describe:: - - Token to be deleted diff --git a/doc/source/command-objects/trust.rst b/doc/source/command-objects/trust.rst deleted file mode 100644 index cb44c6b6cd..0000000000 --- a/doc/source/command-objects/trust.rst +++ /dev/null @@ -1,102 +0,0 @@ -===== -trust -===== - -Identity v3 - -trust create ------------- - -Create new trust - -.. program:: trust create -.. code:: bash - - os trust create - --project - --role - [--impersonate] - [--expiration ] - [--project-domain ] - [--trustor-domain ] - [--trustee-domain ] - - - -.. option:: --project - - Project being delegated (name or ID) (required) - -.. option:: --role - - Roles to authorize (name or ID) (repeat option to set multiple values, required) - -.. option:: --impersonate - - Tokens generated from the trust will represent (defaults to False) - -.. option:: --expiration - - Sets an expiration date for the trust (format of YYYY-mm-ddTHH:MM:SS) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). This can be - used in case collisions between user names exist. - -.. option:: --trustor-domain - - Domain that contains (name or ID) - -.. option:: --trustee-domain - - Domain that contains (name or ID) - -.. describe:: - - User that is delegating authorization (name or ID) - -.. describe:: - - User that is assuming authorization (name or ID) - - -trust delete ------------- - -Delete trust(s) - -.. program:: trust delete -.. code:: bash - - os trust delete - [ ...] - -.. describe:: - - Trust(s) to delete - -trust list ----------- - -List trusts - -.. program:: trust list -.. code:: bash - - os trust list - -trust show ----------- - -Display trust details - -.. program:: trust show -.. code:: bash - - os trust show - - -.. describe:: - - Trust to display diff --git a/doc/source/command-objects/usage.rst b/doc/source/command-objects/usage.rst deleted file mode 100644 index 0c866086dd..0000000000 --- a/doc/source/command-objects/usage.rst +++ /dev/null @@ -1,50 +0,0 @@ -===== -usage -===== - -Compute v2 - -usage list ----------- - -List resource usage per project - -.. program:: usage list -.. code:: bash - - os usage list - --start - --end - -.. option:: --start - - Usage range start date, ex 2012-01-20 (default: 4 weeks ago) - -.. option:: --end - - Usage range end date, ex 2012-01-20 (default: tomorrow) - -usage show ----------- - -Show resource usage for a single project - -.. program:: usage show -.. code:: bash - - os usage show - --project - --start - --end - -.. option:: --project - - Name or ID of project to show usage for - -.. option:: --start - - Usage range start date, ex 2012-01-20 (default: 4 weeks ago) - -.. option:: --end - - Usage range end date, ex 2012-01-20 (default: tomorrow) diff --git a/doc/source/command-objects/user-role.rst b/doc/source/command-objects/user-role.rst deleted file mode 100644 index 8283f91110..0000000000 --- a/doc/source/command-objects/user-role.rst +++ /dev/null @@ -1,27 +0,0 @@ -========= -user role -========= - -Identity v2 - -user role list --------------- - -List user-role assignments - -*Removed in version 3.* - -.. program:: user role list -.. code:: bash - - os user role list - [--project ] - [] - -.. option:: --project - - Filter users by `` (name or ID) - -.. describe:: - - User to list (name or ID) diff --git a/doc/source/command-objects/user.rst b/doc/source/command-objects/user.rst deleted file mode 100644 index a9fee72811..0000000000 --- a/doc/source/command-objects/user.rst +++ /dev/null @@ -1,216 +0,0 @@ -==== -user -==== - -Identity v2, v3 - -user create ------------ - -Create new user - -.. program:: user create -.. code:: bash - - os user create - [--domain ] - [--project [--project-domain ]] - [--password ] - [--password-prompt] - [--email ] - [--description ] - [--enable | --disable] - [--or-show] - - -.. option:: --domain - - Default domain (name or ID) - - .. versionadded:: 3 - -.. option:: --project - - Default project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --password - - Set user password - -.. option:: --password-prompt - - Prompt interactively for password - -.. option:: --email - - Set user email address - -.. option:: --description - - User description - - .. versionadded:: 3 - -.. option:: --enable - - Enable user (default) - -.. option:: --disable - - Disable user - -.. option:: --or-show - - Return existing user - - If the username already exist return the existing user data and do not fail. - -.. describe:: - - New user name - -user delete ------------ - -Delete user(s) - -.. program:: user delete -.. code:: bash - - os user delete - [--domain ] - [ ...] - -.. option:: --domain - - Domain owning :ref:`\ ` (name or ID) - - .. versionadded:: 3 - -.. _user_delete-user: -.. describe:: - - User(s) to delete (name or ID) - -user list ---------- - -List users - -.. program:: user list -.. code:: bash - - os user list - [--project ] - [--domain ] - [--group | --project ] - [--long] - -.. option:: --project - - Filter users by `` (name or ID) - -.. option:: --domain - - Filter users by `` (name or ID) - - *Identity version 3 only* - -.. option:: --group - - Filter users by `` membership (name or ID) - - *Identity version 3 only* - -.. option:: --long - - List additional fields in output - -user set --------- - -Set user properties - -.. program:: user set -.. code:: bash - - os user set - [--name ] - [--project [--project-domain ]] - [--password ] - [--password-prompt] - [--email ] - [--description ] - [--enable|--disable] - - -.. option:: --name - - Set user name - -.. option:: --project - - Set default project (name or ID) - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --password - - Set user password - -.. option:: --password-prompt - - Prompt interactively for password - -.. option:: --email - - Set user email address - -.. option:: --description - - Set user description - - .. versionadded:: 3 - -.. option:: --enable - - Enable user (default) - -.. option:: --disable - - Disable user - -.. describe:: - - User to modify (name or ID) - -user show ---------- - -Display user details - -.. program:: user show -.. code:: bash - - os user show - [--domain ] - - -.. option:: --domain - - Domain owning :ref:`\ ` (name or ID) - - .. versionadded:: 3 - -.. _user_show-user: -.. describe:: - - User to display (name or ID) diff --git a/doc/source/command-objects/volume-qos.rst b/doc/source/command-objects/volume-qos.rst deleted file mode 100644 index f3c7ec2118..0000000000 --- a/doc/source/command-objects/volume-qos.rst +++ /dev/null @@ -1,159 +0,0 @@ -========== -volume qos -========== - -Block Storage v1, v2 - -volume qos associate --------------------- - -Associate a QoS specification to a volume type - -.. program:: volume qos associate -.. code:: bash - - os volume qos associate - - - -.. describe:: - - QoS specification to modify (name or ID) - -.. describe:: - - Volume type to associate the QoS (name or ID) - -volume qos create ------------------ - -Create new QoS Specification - -.. program:: volume qos create -.. code:: bash - - os volume qos create - [--consumer ] - [--property [...] ] - - -.. option:: --consumer - - Consumer of the QoS. Valid consumers: 'front-end', 'back-end', 'both' (defaults to 'both') - -.. option:: --property - - Set a property on this QoS specification (repeat option to set multiple properties) - -.. describe:: - - New QoS specification name - -volume qos delete ------------------ - -Delete QoS specification - -.. program:: volume qos delete -.. code:: bash - - os volume qos delete - [--force] - [ ...] - -.. option:: --force - - Allow to delete in-use QoS specification(s) - -.. describe:: - - QoS specification(s) to delete (name or ID) - -volume qos disassociate ------------------------ - -Disassociate a QoS specification from a volume type - -.. program:: volume qos disassoiate -.. code:: bash - - os volume qos disassociate - --volume-type | --all - - -.. option:: --volume-type - - Volume type to disassociate the QoS from (name or ID) - -.. option:: --all - - Disassociate the QoS from every volume type - -.. describe:: - - QoS specification to modify (name or ID) - -volume qos list ---------------- - -List QoS specifications - -.. program:: volume qos list -.. code:: bash - - os volume qos list - -volume qos set --------------- - -Set QoS specification properties - -.. program:: volume qos set -.. code:: bash - - os volume qos set - [--property [...] ] - - -.. option:: --property - - Property to add or modify for this QoS specification (repeat option to set multiple properties) - -.. describe:: - - QoS specification to modify (name or ID) - -volume qos show ---------------- - -Display QoS specification details - -.. program:: volume qos show -.. code:: bash - - os volume qos show - - -.. describe:: - - QoS specification to display (name or ID) - -volume qos unset ----------------- - -Unset QoS specification properties - -.. program:: volume qos unset -.. code:: bash - - os volume qos unset - [--property ] - - -.. option:: --property - - Property to remove from QoS specification (repeat option to remove multiple properties) - -.. describe:: - - QoS specification to modify (name or ID) diff --git a/doc/source/command-objects/volume-service.rst b/doc/source/command-objects/volume-service.rst deleted file mode 100644 index aa9fa6d262..0000000000 --- a/doc/source/command-objects/volume-service.rst +++ /dev/null @@ -1,31 +0,0 @@ -============== -volume service -============== - -Volume v1, v2 - -volume service list -------------------- - -List volume service - -.. program:: volume service list -.. code:: bash - - os volume service list - [--host ] - [--service ] - [--long] - -.. _volume-service-list: -.. option:: --host - - List services on specified host (name only) - -.. option:: --service - - List only specified service (name only) - -.. option:: --long - - List additional fields in output diff --git a/doc/source/command-objects/volume-transfer-request.rst b/doc/source/command-objects/volume-transfer-request.rst deleted file mode 100644 index 79d84f7551..0000000000 --- a/doc/source/command-objects/volume-transfer-request.rst +++ /dev/null @@ -1,21 +0,0 @@ -======================= -volume transfer request -======================= - -Block Storage v1, v2 - -volume transfer request list ----------------------------- - -Lists all volume transfer requests. - -.. program:: volume transfer request list -.. code:: bash - - os volume transfer request list - --all-projects - -.. option:: --all-projects - - Shows detail for all projects. Admin only. - (defaults to False) \ No newline at end of file diff --git a/doc/source/command-objects/volume-type.rst b/doc/source/command-objects/volume-type.rst deleted file mode 100644 index dfc169cd14..0000000000 --- a/doc/source/command-objects/volume-type.rst +++ /dev/null @@ -1,176 +0,0 @@ -=========== -volume type -=========== - -Block Storage v1, v2 - -volume type create ------------------- - -Create new volume type - -.. program:: volume type create -.. code:: bash - - os volume type create - [--description ] - [--public | --private] - [--property [...] ] - - -.. option:: --description - - Volume type description - - .. versionadded:: 2 - -.. option:: --public - - Volume type is accessible to the public - - .. versionadded:: 2 - -.. option:: --private - - Volume type is not accessible to the public - - .. versionadded:: 2 - -.. option:: --property - - Set a property on this volume type (repeat option to set multiple properties) - -.. _volume_type_create-name: -.. describe:: - - Volume type name - -volume type delete ------------------- - -Delete volume type(s) - -.. program:: volume type delete -.. code:: bash - - os volume type delete - [ ...] - -.. _volume_type_delete-volume-type: -.. describe:: - - Volume type(s) to delete (name or ID) - -volume type list ----------------- - -List volume types - -.. program:: volume type list -.. code:: bash - - os volume type list - [--long] - -.. option:: --long - - List additional fields in output - -volume type set ---------------- - -Set volume type properties - -.. program:: volume type set -.. code:: bash - - os volume type set - [--name ] - [--description ] - [--property [...] ] - [--project ] - [--project-domain ] - - -.. option:: --name - - Set volume type name - - .. versionadded:: 2 - -.. option:: --description - - Set volume type description - - .. versionadded:: 2 - -.. option:: --project - - Set volume type access to project (name or ID) (admin only) - - *Volume version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. option:: --property - - Set a property on this volume type (repeat option to set multiple properties) - -.. _volume_type_set-volume-type: -.. describe:: - - Volume type to modify (name or ID) - -volume type show ----------------- - -Display volume type details - - -.. program:: volume type show -.. code:: bash - - os volume type show - - -.. _volume_type_show-volume-type: -.. describe:: - - Volume type to display (name or ID) - -volume type unset ------------------ - -Unset volume type properties - -.. program:: volume type unset -.. code:: bash - - os volume type unset - [--property [...] ] - [--project ] - [--project-domain ] - - -.. option:: --property - - Property to remove from volume type (repeat option to remove multiple properties) - -.. option:: --project - - Removes volume type access from project (name or ID) (admin only) - - *Volume version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - This can be used in case collisions between project names exist. - -.. _volume_type_unset-volume-type: -.. describe:: - - Volume type to modify (name or ID) diff --git a/doc/source/command-objects/volume.rst b/doc/source/command-objects/volume.rst deleted file mode 100644 index a51d1117d1..0000000000 --- a/doc/source/command-objects/volume.rst +++ /dev/null @@ -1,254 +0,0 @@ -====== -volume -====== - -Block Storage v1, v2 - -volume create -------------- - -Create new volume - -.. program:: volume create -.. code:: bash - - os volume create - --size - [--type ] - [--image ] - [--snapshot ] - [--source ] - [--description ] - [--user ] - [--project ] - [--availability-zone ] - [--property [...] ] - - -.. option:: --size (required) - - Volume size in GB - -.. option:: --type - - Set the type of volume - - Select :option:`\` from the available types as shown - by ``volume type list``. - -.. option:: --image - - Use :option:`\` as source of volume (name or ID) - - This is commonly used to create a boot volume for a server. - -.. option:: --snapshot - - Use :option:`\` as source of volume (name or ID) - -.. option:: --source - - Volume to clone (name or ID) - -.. option:: --description - - Volume description - -.. option:: --user - - Specify an alternate user (name or ID) - -.. option:: --project - - Specify an alternate project (name or ID) - -.. option:: --availability-zone - - Create volume in :option:`\` - -.. option:: --property - - Set a property on this volume (repeat option to set multiple properties) - -.. _volume_create-name: -.. describe:: - - Volume name - -The :option:`--project` and :option:`--user` options are typically only -useful for admin users, but may be allowed for other users depending on -the policy of the cloud and the roles granted to the user. - -volume delete -------------- - -Delete volume(s) - -.. program:: volume delete -.. code:: bash - - os volume delete - [--force] - [ ...] - -.. option:: --force - - Attempt forced removal of volume(s), regardless of state (defaults to False) - -.. _volume_delete-volume: -.. describe:: - - Volume(s) to delete (name or ID) - -volume list ------------ - -List volumes - -.. program:: volume list -.. code:: bash - - os volume list - [--project [--project-domain ]] - [--user [--user-domain ]] - [--name ] - [--status ] - [--all-projects] - [--long] - -.. option:: --project - - Filter results by :option:`\` (name or ID) (admin only) - - *Volume version 2 only* - -.. option:: --project-domain - - Domain the project belongs to (name or ID). - - This can be used in case collisions between project names exist. - - *Volume version 2 only* - -.. option:: --user - - Filter results by :option:`\` (name or ID) (admin only) - - *Volume version 2 only* - -.. option:: --user-domain - - Domain the user belongs to (name or ID). - - This can be used in case collisions between user names exist. - - *Volume version 2 only* - -.. option:: --name - - Filter results by volume name - -.. option:: --status - - Filter results by status - -.. option:: --all-projects - - Include all projects (admin only) - -.. option:: --long - - List additional fields in output - -volume set ----------- - -Set volume properties - -.. program:: volume set -.. code:: bash - - os volume set - [--name ] - [--size ] - [--description ] - [--property [...] ] - [--image-property [...] ] - - -.. option:: --name - - New volume name - -.. option:: --size - - Extend volume size in GB - -.. option:: --description - - New volume description - -.. option:: --property - - Set a property on this volume (repeat option to set multiple properties) - -.. option:: --image-property - - Set an image property on this volume - (repeat option to set multiple image properties) - - Image properties are copied along with the image when creating a volume - using :option:`--image`. Note that these properties are immutable on the - image itself, this option updates the copy attached to this volume. - - *Volume version 2 only* - -.. _volume_set-volume: -.. describe:: - - Volume to modify (name or ID) - -volume show ------------ - -Show volume details - -.. program:: volume show -.. code:: bash - - os volume show - - -.. _volume_show-volume: -.. describe:: - - Volume to display (name or ID) - -volume unset ------------- - -Unset volume properties - -.. program:: volume unset -.. code:: bash - - os volume unset - [--property ] - [--image-property ] - - -.. option:: --property - - Remove a property from volume (repeat option to remove multiple properties) - -.. option:: --image-property - - Remove an image property from volume - (repeat option to remove multiple image properties) - - *Volume version 2 only* - -.. _volume_unset-volume: -.. describe:: - - Volume to modify (name or ID) diff --git a/doc/source/commands.rst b/doc/source/commands.rst deleted file mode 100644 index 70f4c8b238..0000000000 --- a/doc/source/commands.rst +++ /dev/null @@ -1,277 +0,0 @@ -================= -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 -* ``backup``: (**Volume**) a volume copy -* ``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 -* ``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 -* ``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**, **Network**) - an internal IP address assigned to a server -* ``floating ip``: (**Compute**, **Network**) - a public IP address that can be mapped to a server -* ``floating ip pool``: (**Compute**, **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 -* ``ip availability``: (**Network**) - details of IP usage of a network -* ``ip fixed``: (**Compute**, **Network**) - an internal IP address assigned to a server -* ``ip floating``: (**Compute**, **Network**) - a public IP address that can be mapped to a server -* ``ip floating pool``: (**Compute**, **Network**) - a pool of public IP addresses -* ``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 segment``: (**Network**) - a segment of a virtual network -* ``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 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`` -* ``snapshot``: (**Volume**) a point-in-time copy of a volume -* ``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 qos``: (**Volume**) quality-of-service (QoS) specification for volumes -* ``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 :doc:`plugins`. These are -listed here to avoid name conflicts when creating new plugins. For a complete -list check out :doc:`plugin-commands`. - -* ``action definition``: (**Workflow Engine (Mistral)**) -* ``action execution``: (**Workflow Engine (Mistral)**) -* ``baremetal``: (**Baremetal (Ironic)**) -* ``cluster``: (**Clustering (Senlin)**) -* ``cluster action``: (**Clustering (Senlin)**) -* ``cluster event``: (**Clustering (Senlin)**) -* ``cluster members``: (**Clustering (Senlin)**) -* ``cluster node``: (**Clustering (Senlin)**) -* ``cluster policy``: (**CLustering (Senlin)**) -* ``cluster policy binding``: (**Clustering (Senlin)**) -* ``cluster policy type``: (**Clustering (Senlin)**) -* ``cluster profile``: (**Clustering (Senlin)**) -* ``cluster profile type``: (**Clustering (Senlin)**) -* ``cluster receiver``: (**Clustering (Senlin)**) -* ``congress datasource``: (**Policy (Congress)**) -* ``congress driver``: (**Policy (Congress)**) -* ``congress policy``: (**Policy (Congress)**) -* ``congress policy rule``: (**Policy (Congress)**) -* ``cron trigger``: (**Workflow Engine (Mistral)**) -* ``dataprocessing data source``: (**Data Processing (Sahara)**) -* ``dataprocessing image``: (**Data Processing (Sahara)**) -* ``dataprocessing image tags``: (**Data Processing (Sahara)**) -* ``dataprocessing plugin``: (**Data Processing (Sahara)**) -* ``message-broker cluster``: (**Message Broker (Cue)**) -* ``message flavor``: (**Messaging (Zaqar)**) -* ``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)**) -* ``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)**) -* ``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 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 -* ``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 to a different host; ``--live`` performs a - live migration if possible -* ``pause`` (``unpause``) - stop one or more servers and leave them in memory -* ``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 ``setuptools`` entry points. The plugin commands must -be subclasses of Cliff's ``command.Command`` object. See :doc:`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/conf.py b/doc/source/conf.py index 792ba40a41..6ee3145558 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- # # OpenStack Command Line Client documentation build configuration file, created # by sphinx-quickstart on Wed May 16 12:05:58 2012. @@ -12,93 +11,79 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import os -import sys - -import pbr.version - -# 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(os.path.join(os.path.dirname(__file__), '..', '..'))) - -# NOTE(blk-u): Path for our Sphinx extension, remove when -# https://launchpad.net/bugs/1260495 is fixed. -sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) - # -- 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', - 'oslosphinx', - 'ext.apidoc', - 'stevedore.sphinxext', - ] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'openstackdocstheme', + 'stevedore.sphinxext', + 'cliff.sphinxext', + 'sphinxcontrib.apidoc', +] + +# 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-2013 OpenStack Foundation' - -# 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. -# -version_info = pbr.version.VersionInfo('python-openstackclient') -# -# The short X.Y version. -version = version_info.version_string() -# The full version, including alpha/beta/rc tags. -release = version_info.release_string() +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 +# 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 = ['openstackclient.'] @@ -108,124 +93,126 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -#html_theme_path = ["."] -#html_theme = '_theme' +# 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', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # 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]) # . 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 ------------------------------------------- @@ -234,16 +221,16 @@ # (source start file, name, description, authors, manual section). man_pages = [ ( - 'man/openstack', + 'cli/man/openstack', 'openstack', - u'OpenStack Command Line Client', - [u'OpenStack contributors'], + '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 ----------------------------------------------- @@ -252,18 +239,52 @@ # (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 --------------------------------------- + +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.rst b/doc/source/configuration.rst deleted file mode 100644 index d80b3b3634..0000000000 --- a/doc/source/configuration.rst +++ /dev/null @@ -1,216 +0,0 @@ -============= -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 :doc:`openstack manpage ` lists all of the global -options recognized by OpenStackClient and the default authentication plugins. - -Environment Variables ---------------------- - -The :doc:`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:35357/ - project_name: demo - username: demo - password: 0penstack - region_name: RegionOne - ds-admin: - auth: - auth_url: http://192.168.122.10:35357/ - 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. - -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 :doc:`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:35357/ - 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:35357/ - 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` 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/command-beta.rst b/doc/source/contributor/command-beta.rst similarity index 98% rename from doc/source/command-beta.rst rename to doc/source/contributor/command-beta.rst index bc8c04c5e7..40ede67100 100644 --- a/doc/source/command-beta.rst +++ b/doc/source/contributor/command-beta.rst @@ -1,3 +1,5 @@ +.. _command-beta: + ============ Command Beta ============ @@ -45,7 +47,7 @@ List examples .. program:: example list .. code:: bash - os example list + openstack example list Help ~~~~ diff --git a/doc/source/command-errors.rst b/doc/source/contributor/command-errors.rst similarity index 96% rename from doc/source/command-errors.rst rename to doc/source/contributor/command-errors.rst index c4adb7d190..f47dfec7c3 100644 --- a/doc/source/command-errors.rst +++ b/doc/source/contributor/command-errors.rst @@ -29,8 +29,9 @@ 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. +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 @@ -45,7 +46,7 @@ raised that includes the name of the file that was attempted to be opened. public_key = parsed_args.public_key if public_key: try: - with io.open( + with open( os.path.expanduser(parsed_args.public_key), "rb" ) as p: @@ -56,8 +57,8 @@ raised that includes the name of the file that was attempted to be opened. msg % (parsed_args.public_key, e), ) - keypair = compute_client.keypairs.create( - parsed_args.name, + keypair = compute_client.create_keypair( + name=parsed_args.name, public_key=public_key, ) diff --git a/doc/source/command-logs.rst b/doc/source/contributor/command-logs.rst similarity index 96% rename from doc/source/command-logs.rst rename to doc/source/contributor/command-logs.rst index 6212651067..c203d02aee 100644 --- a/doc/source/command-logs.rst +++ b/doc/source/contributor/command-logs.rst @@ -10,7 +10,7 @@ OpenStack projects. The following basic rules should be followed. 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: - http://docs.openstack.org/developer/oslo.i18n/guidelines.html + 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 diff --git a/doc/source/command-options.rst b/doc/source/contributor/command-options.rst similarity index 77% rename from doc/source/command-options.rst rename to doc/source/contributor/command-options.rst index 5cb84684c9..845d51f9f2 100644 --- a/doc/source/command-options.rst +++ b/doc/source/contributor/command-options.rst @@ -14,6 +14,13 @@ 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 ======================= @@ -30,7 +37,7 @@ prepended (such as in the traditional GNU option usage) like `--share` and 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 mutiually exclusive group, rather than the more common configuration 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. @@ -112,12 +119,12 @@ 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`` and ``unset`` actions. 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 -``--no`` 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. +``--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: @@ -147,6 +154,15 @@ 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='', @@ -155,24 +171,21 @@ An example parser declaration for `set` action: help=_('Example property for this ' '(repeat option to set multiple properties)'), ) - parser.add_argument( - '--no-example-property', - dest='no_example_property', - action='store_true', - help=_('Remove all example properties for this '), - ) + +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.example_property and parsed_args.no_example_property: + 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 - elif parsed_args.no_example_property: - kwargs['example_property'] = [] An example parser declaration for `unset` action: @@ -188,8 +201,8 @@ An example parser declaration for `unset` action: '(repeat option to remove multiple properties)'), ) example_property_group.add_argument( - '--no-example-property', - dest='no_example_property', + '--all-example-property', + dest='all_example_property', action='store_true', help=_('Remove all example properties for this '), ) @@ -202,9 +215,39 @@ An example handler in `take_action()` for `unset` action: kwargs['example_property'] = \ list(set(resource_example_property) - \ set(parsed_args.example_property)) - if parsed_args.no_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 ==================== @@ -240,11 +283,11 @@ 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 +.. option:: --marker - Anchor for paging + Anchor for paging (name or ID) -.. option:: --limit +.. option:: --limit Limit number of returned (*integer*) @@ -257,13 +300,13 @@ The parser declaration should look like this: parser.add_argument( "--marker", - metavar="", - help="Anchor for paging", + metavar="", + help="Anchor for paging (name or ID)", ) parser.add_argument( "--limit", - metavar="", + metavar="", type=int, help="Limit the number of returned", ) diff --git a/doc/source/command-wrappers.rst b/doc/source/contributor/command-wrappers.rst similarity index 96% rename from doc/source/command-wrappers.rst rename to doc/source/contributor/command-wrappers.rst index 2a5d92239d..cf4eece23a 100644 --- a/doc/source/command-wrappers.rst +++ b/doc/source/contributor/command-wrappers.rst @@ -7,7 +7,7 @@ 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 ``setuptools`` entry points for dispatching the parsed command +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. 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 ``--