From 6cb5d8cd1476b0415f85033582312887f4b9ea18 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 16 Apr 2025 12:16:29 +0100 Subject: [PATCH] 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 --- README.rst | 196 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 147 insertions(+), 49 deletions(-) diff --git a/README.rst b/README.rst index ff1b42c8ee..af3837a351 100644 --- a/README.rst +++ b/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: '' + 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_IDENTITY_API_VERSION=3 + 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) - The corresponding command-line options look very similar:: +Likewise, the corresponding command-line options would look very similar: - --os-auth-url - --os-identity-api-version 3 +:: + + openstack + --os-auth-url + --os-region --os-project-name --os-project-domain-name --os-username --os-user-domain-name [--os-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: '' + 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_PLUGIN=openid export OS_AUTH_TYPE=v3oidcpassword export OS_USERNAME= export OS_PASSWORD= @@ -109,7 +169,9 @@ Authentication using username/password is most commonly used: export OS_ACCESS_TOKEN_TYPE= export OS_DISCOVERY_ENDPOINT= - The corresponding command-line options look very similar:: +Likewise, the corresponding command-line options would look very similar: + +.. code-block:: shell --os-project-name --os-project-domain-name @@ -127,5 +189,41 @@ Authentication using username/password is most commonly used: --os-access-token-type --os-discovery-endpoint -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 `_ +* `Code Review `_ +* `Documentation `_ +* `PyPi `_ +* `Mailing list `_ +* `Release Notes `_ +* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) `_