Update README
Restructure things to be a little more helpful. Also add a reference to the Dockerfile we provide and remove an errant header that should have been removed in change Ife108e6ae191641b56e872e4616a3f4ec78281e8. Change-Id: I5f562a99ccee7db485b5d40ef4ea6f2e2e362c13 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
parent
22eecc54f8
commit
6cb5d8cd14
196
README.rst
196
README.rst
@ -1,7 +1,3 @@
|
||||
========================
|
||||
Team and repository tags
|
||||
========================
|
||||
|
||||
===============
|
||||
OpenStackClient
|
||||
===============
|
||||
@ -10,94 +6,158 @@ OpenStackClient
|
||||
:target: https://pypi.org/project/python-openstackclient/
|
||||
:alt: Latest Version
|
||||
|
||||
OpenStackClient (aka OSC) is a command-line client for OpenStack that brings
|
||||
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`_ - bugs and feature requests
|
||||
* `Blueprints`_ - feature specifications (historical only)
|
||||
* `Source`_
|
||||
* `Developer`_ - getting started as a developer
|
||||
* `Contributing`_ - contributing code
|
||||
* `Testing`_ - testing code
|
||||
* IRC: #openstack-sdks on OFTC (irc.oftc.net)
|
||||
* License: Apache 2.0
|
||||
|
||||
.. _PyPi: https://pypi.org/project/python-openstackclient
|
||||
.. _Online Documentation: https://docs.openstack.org/python-openstackclient/latest/
|
||||
.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient
|
||||
.. _`Launchpad project`: https://bugs.launchpad.net/python-openstackclient
|
||||
.. _Source: https://opendev.org/openstack/python-openstackclient
|
||||
.. _Developer: https://docs.openstack.org/project-team-guide/project-setup/python.html
|
||||
.. _Contributing: https://docs.openstack.org/infra/manual/developers.html
|
||||
.. _Testing: https://docs.openstack.org/python-openstackclient/latest/contributor/developing.html#testing
|
||||
.. _Release Notes: https://docs.openstack.org/releasenotes/python-openstackclient
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
OpenStack Client can be installed from PyPI using pip::
|
||||
OpenStack Client can be installed from PyPI using pip:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python3 -m pip install python-openstackclient
|
||||
|
||||
There are a few variants on getting help. A list of global options and supported
|
||||
commands is shown with ``--help``::
|
||||
You can use ``--help`` or the ``help`` command to get a list of global options
|
||||
and supported commands:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
openstack --help
|
||||
|
||||
There is also a ``help`` command that can be used to get help text for a specific
|
||||
command::
|
||||
|
||||
openstack help
|
||||
|
||||
You can also get help for a specific command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
openstack server create --help
|
||||
openstack help server create
|
||||
|
||||
If you want to make changes to the OpenStackClient for testing and contribution,
|
||||
make any changes and then run::
|
||||
You can add support for additional services by installing their clients. For
|
||||
example, to add support for the DNS service (designate):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python3 -m pip install python3-designateclient
|
||||
|
||||
A ``Dockerfile`` is provided for your convenience in the repository. You can
|
||||
use this to build your own container images:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://opendev.org/openstack/python-openstackclient
|
||||
cd python-openstackclient
|
||||
python3 -m pip install -e .
|
||||
podman build . -t example.com/myuser/openstackclient
|
||||
|
||||
For more information the available options and commands, refer to the `Users
|
||||
Guide`__.
|
||||
|
||||
.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
The CLI is configured via environment variables and command-line
|
||||
options as listed in https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
|
||||
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:
|
||||
|
||||
Authentication using username/password is most commonly used:
|
||||
* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment
|
||||
variable
|
||||
* ``.`` (the current directory)
|
||||
* ``$HOME/.config/openstack``
|
||||
* ``/etc/openstack``
|
||||
|
||||
- For a local user, your configuration will look like the one below::
|
||||
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: '<url-to-openstack-identity>'
|
||||
project_name: '<project-name>'
|
||||
project_domain_name: '<project-domain-name>'
|
||||
username: '<username>'
|
||||
user_domain_name: '<user-domain-name>'
|
||||
password: '<password>' # (optional)
|
||||
region_name: '<region>'
|
||||
|
||||
The corresponding environment variables would look very similar:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export OS_AUTH_URL=<url-to-openstack-identity>
|
||||
export OS_IDENTITY_API_VERSION=3
|
||||
export OS_REGION_NAME=<region>
|
||||
export OS_PROJECT_NAME=<project-name>
|
||||
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
|
||||
export OS_USERNAME=<username>
|
||||
export OS_USER_DOMAIN_NAME=<user-domain-name>
|
||||
export OS_PASSWORD=<password> # (optional)
|
||||
|
||||
The corresponding command-line options look very similar::
|
||||
Likewise, the corresponding command-line options would look very similar:
|
||||
|
||||
--os-auth-url <url>
|
||||
--os-identity-api-version 3
|
||||
::
|
||||
|
||||
openstack
|
||||
--os-auth-url <url-to-openstack-identity>
|
||||
--os-region <region>
|
||||
--os-project-name <project-name>
|
||||
--os-project-domain-name <project-domain-name>
|
||||
--os-username <username>
|
||||
--os-user-domain-name <user-domain-name>
|
||||
[--os-password <password>]
|
||||
|
||||
- For a federated user, your configuration will look the so::
|
||||
.. 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: '<url-to-openstack-identity>'
|
||||
project_name: '<project-name>'
|
||||
project_domain_name: '<project-domain-name>'
|
||||
username: '<username-in-idp>'
|
||||
user_domain_name: '<user-domain-name>'
|
||||
password: '<password-in-idp>'
|
||||
identity_provider: '<the-desired-idp-in-keystone>'
|
||||
client_id: '<the-client-id-configured-in-the-idp>'
|
||||
client_secret: '<the-client-secret-configured-in-the-idp>'
|
||||
openid_scope: '<the-scopes-of-desired-attributes-to-claim-from-idp>'
|
||||
protocol: '<the-protocol-used-in-the-apache2-oidc-proxy>'
|
||||
access_token_type: '<the-access-token-type-used-by-your-idp>'
|
||||
discovery_endpoint: '<the-well-known-endpoint-of-the-idp>'
|
||||
auth_type: 'v3oidcpassword'
|
||||
region_name: '<region>'
|
||||
|
||||
The corresponding environment variables would look very similar:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export OS_PROJECT_NAME=<project-name>
|
||||
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
|
||||
export OS_AUTH_URL=<url-to-openstack-identity>
|
||||
export OS_IDENTITY_API_VERSION=3
|
||||
export OS_AUTH_PLUGIN=openid
|
||||
export OS_AUTH_TYPE=v3oidcpassword
|
||||
export OS_USERNAME=<username-in-idp>
|
||||
export OS_PASSWORD=<password-in-idp>
|
||||
@ -109,7 +169,9 @@ Authentication using username/password is most commonly used:
|
||||
export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
|
||||
export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
|
||||
|
||||
The corresponding command-line options look very similar::
|
||||
Likewise, the corresponding command-line options would look very similar:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
--os-project-name <project-name>
|
||||
--os-project-domain-name <project-domain-name>
|
||||
@ -127,5 +189,41 @@ Authentication using username/password is most commonly used:
|
||||
--os-access-token-type <the-access-token-type-used-by-your-idp>
|
||||
--os-discovery-endpoint <the-well-known-endpoint-of-the-idp>
|
||||
|
||||
If a password is not provided above (in plaintext), you will be interactively
|
||||
prompted to provide one securely.
|
||||
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 <https://bugs.launchpad.net/python-openstackclient>`_
|
||||
* `Code Review <https://review.opendev.org/#/q/status:open+project:openstack/openstacksdk,n,z>`_
|
||||
* `Documentation <https://docs.openstack.org/python-openstackclient/latest/>`_
|
||||
* `PyPi <https://pypi.org/project/python-openstackclient>`_
|
||||
* `Mailing list <https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/>`_
|
||||
* `Release Notes <https://docs.openstack.org/releasenotes/python-openstackclient>`_
|
||||
* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) <irc://irc.oftc.net/openstack-sdks>`_
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user