Skip to content

Commit a49a290

Browse files
Zuulopenstack-gerrit
Zuul
authored and
openstack-gerrit
committed
Merge "Update README"
2 parents 871b2a4 + 6cb5d8c commit a49a290

File tree

1 file changed

+148
-50
lines changed

1 file changed

+148
-50
lines changed

‎README.rst‎

Lines changed: 148 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
========================
2-
Team and repository tags
3-
========================
4-
51
===============
62
OpenStackClient
73
===============
@@ -10,94 +6,158 @@ OpenStackClient
106
:target: https://pypi.org/project/python-openstackclient/
117
:alt: Latest Version
128

13-
OpenStackClient (aka OSC) is a command-line client for OpenStack that brings
9+
OpenStackClient (OSC) is a command-line client for OpenStack that brings
1410
the command set for Compute, Identity, Image, Network, Object Store and Block
1511
Storage APIs together in a single shell with a uniform command structure.
12+
Support for additional service APIs is provided via plugins.
1613

1714
The primary goal is to provide a unified shell command structure and a common
1815
language to describe operations in OpenStack.
1916

20-
* `PyPi`_ - package installation
21-
* `Online Documentation`_
22-
* `Launchpad project`_ - bugs and feature requests
23-
* `Blueprints`_ - feature specifications (historical only)
24-
* `Source`_
25-
* `Developer`_ - getting started as a developer
26-
* `Contributing`_ - contributing code
27-
* `Testing`_ - testing code
28-
* IRC: #openstack-sdks on OFTC (irc.oftc.net)
29-
* License: Apache 2.0
30-
31-
.. _PyPi: https://pypi.org/project/python-openstackclient
32-
.. _Online Documentation: https://docs.openstack.org/python-openstackclient/latest/
33-
.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient
34-
.. _`Launchpad project`: https://bugs.launchpad.net/python-openstackclient
35-
.. _Source: https://opendev.org/openstack/python-openstackclient
36-
.. _Developer: https://docs.openstack.org/project-team-guide/project-setup/python.html
37-
.. _Contributing: https://docs.openstack.org/infra/manual/developers.html
38-
.. _Testing: https://docs.openstack.org/python-openstackclient/latest/contributor/developing.html#testing
39-
.. _Release Notes: https://docs.openstack.org/releasenotes/python-openstackclient
40-
4117
Getting Started
4218
===============
4319

44-
OpenStack Client can be installed from PyPI using pip::
20+
OpenStack Client can be installed from PyPI using pip:
21+
22+
.. code-block:: shell
4523
4624
python3 -m pip install python-openstackclient
4725
48-
There are a few variants on getting help. A list of global options and supported
49-
commands is shown with ``--help``::
26+
You can use ``--help`` or the ``help`` command to get a list of global options
27+
and supported commands:
28+
29+
.. code-block:: shell
5030
5131
openstack --help
32+
openstack help
5233
53-
There is also a ``help`` command that can be used to get help text for a specific
54-
command::
34+
You can also get help for a specific command:
5535

56-
openstack help
36+
.. code-block:: shell
37+
38+
openstack server create --help
5739
openstack help server create
5840
59-
If you want to make changes to the OpenStackClient for testing and contribution,
60-
make any changes and then run::
41+
You can add support for additional services by installing their clients. For
42+
example, to add support for the DNS service (designate):
43+
44+
.. code-block:: shell
45+
46+
python3 -m pip install python3-designateclient
47+
48+
A ``Dockerfile`` is provided for your convenience in the repository. You can
49+
use this to build your own container images:
50+
51+
.. code-block:: shell
6152
6253
git clone https://opendev.org/openstack/python-openstackclient
6354
cd python-openstackclient
64-
python3 -m pip install -e .
55+
podman build . -t example.com/myuser/openstackclient
6556
66-
Configuration
67-
=============
57+
For more information the available options and commands, refer to the `Users
58+
Guide`__.
6859

69-
The CLI is configured via environment variables and command-line
70-
options as listed in https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
60+
.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html
7161

72-
Authentication using username/password is most commonly used:
62+
Configuration
63+
=============
7364

74-
- For a local user, your configuration will look like the one below::
65+
OpenStack Client must be configured with authentication information in order to
66+
communicate with a given OpenStack cloud. This configuration can be achieved
67+
via a ``clouds.yaml`` file, a set of environment variables (often shared via an
68+
``openrc`` file), a set of command-line options, or a combination of all three.
69+
Your cloud provider or deployment tooling will typically provide either a
70+
``clouds.yaml`` file or ``openrc`` file for you. If using a ``clouds.yaml``
71+
file, OpenStack Client expects to find it in one of the following locations:
72+
73+
* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment
74+
variable
75+
* ``.`` (the current directory)
76+
* ``$HOME/.config/openstack``
77+
* ``/etc/openstack``
78+
79+
The options you should set will depend on the configuration of your cloud and
80+
the authentication mechanism(s) supported. For example, consider a cloud that
81+
supports username/password authentication. Configuration for this cloud using a
82+
``clouds.yaml`` file would look like so:
83+
84+
.. code-block:: yaml
85+
86+
clouds:
87+
my-cloud:
88+
auth:
89+
auth_url: '<url-to-openstack-identity>'
90+
project_name: '<project-name>'
91+
project_domain_name: '<project-domain-name>'
92+
username: '<username>'
93+
user_domain_name: '<user-domain-name>'
94+
password: '<password>' # (optional)
95+
region_name: '<region>'
96+
97+
The corresponding environment variables would look very similar:
98+
99+
.. code-block:: shell
75100
76101
export OS_AUTH_URL=<url-to-openstack-identity>
77-
export OS_IDENTITY_API_VERSION=3
102+
export OS_REGION_NAME=<region>
78103
export OS_PROJECT_NAME=<project-name>
79104
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
80105
export OS_USERNAME=<username>
81106
export OS_USER_DOMAIN_NAME=<user-domain-name>
82107
export OS_PASSWORD=<password> # (optional)
83108
84-
The corresponding command-line options look very similar::
109+
Likewise, the corresponding command-line options would look very similar:
85110

86-
--os-auth-url <url>
87-
--os-identity-api-version 3
111+
::
112+
113+
openstack
114+
--os-auth-url <url-to-openstack-identity>
115+
--os-region <region>
88116
--os-project-name <project-name>
89117
--os-project-domain-name <project-domain-name>
90118
--os-username <username>
91119
--os-user-domain-name <user-domain-name>
92120
[--os-password <password>]
93121

94-
- For a federated user, your configuration will look the so::
122+
.. note::
123+
124+
If a password is not provided above (in plaintext), you will be
125+
interactively prompted to provide one securely.
126+
127+
Some clouds use federated authentication. If this is the case, your
128+
configuration will be slightly more involved. For example, to configure
129+
username/password authentication for a federated user using a ``clouds.yaml``
130+
file:
131+
132+
.. code-block:: yaml
133+
134+
clouds:
135+
my-cloud:
136+
auth:
137+
auth_url: '<url-to-openstack-identity>'
138+
project_name: '<project-name>'
139+
project_domain_name: '<project-domain-name>'
140+
username: '<username-in-idp>'
141+
user_domain_name: '<user-domain-name>'
142+
password: '<password-in-idp>'
143+
identity_provider: '<the-desired-idp-in-keystone>'
144+
client_id: '<the-client-id-configured-in-the-idp>'
145+
client_secret: '<the-client-secret-configured-in-the-idp>'
146+
openid_scope: '<the-scopes-of-desired-attributes-to-claim-from-idp>'
147+
protocol: '<the-protocol-used-in-the-apache2-oidc-proxy>'
148+
access_token_type: '<the-access-token-type-used-by-your-idp>'
149+
discovery_endpoint: '<the-well-known-endpoint-of-the-idp>'
150+
auth_type: 'v3oidcpassword'
151+
region_name: '<region>'
152+
153+
The corresponding environment variables would look very similar:
154+
155+
.. code-block:: shell
95156
96157
export OS_PROJECT_NAME=<project-name>
97158
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
98159
export OS_AUTH_URL=<url-to-openstack-identity>
99160
export OS_IDENTITY_API_VERSION=3
100-
export OS_AUTH_PLUGIN=openid
101161
export OS_AUTH_TYPE=v3oidcpassword
102162
export OS_USERNAME=<username-in-idp>
103163
export OS_PASSWORD=<password-in-idp>
@@ -109,7 +169,9 @@ Authentication using username/password is most commonly used:
109169
export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
110170
export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
111171
112-
The corresponding command-line options look very similar::
172+
Likewise, the corresponding command-line options would look very similar:
173+
174+
.. code-block:: shell
113175
114176
--os-project-name <project-name>
115177
--os-project-domain-name <project-domain-name>
@@ -127,5 +189,41 @@ Authentication using username/password is most commonly used:
127189
--os-access-token-type <the-access-token-type-used-by-your-idp>
128190
--os-discovery-endpoint <the-well-known-endpoint-of-the-idp>
129191
130-
If a password is not provided above (in plaintext), you will be interactively
131-
prompted to provide one securely.
192+
For more information on configuring authentication, including an overview of
193+
the many authentication mechanisms supported, refer to the `Authentication
194+
guide`__. For more information on configuration in general, refer to the
195+
`Configuration guide`__.
196+
197+
.. __: https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
198+
.. __: https://docs.openstack.org/python-openstackclient/latest/configuration/index.html
199+
200+
Contributing
201+
============
202+
203+
You can clone the repository from opendev.org::
204+
205+
git clone https://opendev.org/openstack/python-openstackclient
206+
cd python-openstackclient
207+
208+
OpenStack Client uses the same contributor process as other OpenStack projects.
209+
For information on this process, including help on setting up you Gerrit
210+
account and an overview of the CI process, refer to the `OpenStack Contributors
211+
Guide`__.
212+
213+
For more information on contributing to OpenStack Client itself, including
214+
guidance on how to design new commands and how to report bugs, refer to the
215+
`Contributors Guide`__.
216+
217+
.. __: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html
218+
.. __: https://docs.opendev.org/opendev/infra-manual/latest/developers.html
219+
220+
Links
221+
-----
222+
223+
* `Issue Tracker <https://bugs.launchpad.net/python-openstackclient>`_
224+
* `Code Review <https://review.opendev.org/#/q/status:open+project:openstack/openstacksdk,n,z>`_
225+
* `Documentation <https://docs.openstack.org/python-openstackclient/latest/>`_
226+
* `PyPi <https://pypi.org/project/python-openstackclient>`_
227+
* `Mailing list <https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/>`_
228+
* `Release Notes <https://docs.openstack.org/releasenotes/python-openstackclient>`_
229+
* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) <irc://irc.oftc.net/openstack-sdks>`_

0 commit comments

Comments
 (0)