https://github.com/openstack/python-openstackclient
Client for OpenStack services. Mirror of code maintained at opendev.org.
https://github.com/openstack/python-openstackclient
client-tools
Last synced: 25 days ago
JSON representation
Client for OpenStack services. Mirror of code maintained at opendev.org.
- Host: GitHub
- URL: https://github.com/openstack/python-openstackclient
- Owner: openstack
- License: apache-2.0
- Created: 2012-04-28T21:07:25.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2025-04-03T18:18:51.000Z (2 months ago)
- Last Synced: 2025-04-06T13:03:10.559Z (2 months ago)
- Topics: client-tools
- Language: Python
- Homepage: https://opendev.org/openstack/python-openstackclient
- Size: 16.6 MB
- Stars: 339
- Watchers: 33
- Forks: 211
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
Awesome Lists containing this project
README
===============
OpenStackClient
===============
.. image:: https://img.shields.io/pypi/v/python-openstackclient.svg
:target: https://pypi.org/project/python-openstackclient/
:alt: Latest Version
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.
Getting Started
===============
OpenStack Client can be installed from PyPI using pip:
.. code-block:: shell
python3 -m pip install python-openstackclient
You can use ``--help`` or the ``help`` command to get a list of global options
and supported commands:
.. code-block:: shell
openstack --help
openstack help
You can also get help for a specific command:
.. code-block:: shell
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
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
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
=============
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)) `_