Repository files navigation

OpenStackClient (OSC) is a command-line client for OpenStack that bringsthe command set for Compute, Identity, Image, Network, Object Store and BlockStorage 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 commonlanguage to describe operations in OpenStack.

OpenStack Client can be installed from PyPI using pip:

python3 -m pip install python-openstackclient

You can use--help or thehelp command to get a list of global optionsand supported commands:

openstack --helpopenstackhelp

You can also get help for a specific command:

openstack server create --helpopenstackhelp server create

You can add support for additional services by installing their clients. Forexample, to add support for the DNS service (designate):

python3 -m pip install python3-designateclient

ADockerfile is provided for your convenience in the repository. You canuse this to build your own container images:

git clone https://opendev.org/openstack/python-openstackclientcd python-openstackclientpodman build. -t example.com/myuser/openstackclient

For more information the available options and commands, refer to theUsersGuide.

OpenStack Client must be configured with authentication information in order tocommunicate with a given OpenStack cloud. This configuration can be achievedvia aclouds.yaml file, a set of environment variables (often shared via anopenrc file), a set of command-line options, or a combination of all three.Your cloud provider or deployment tooling will typically provide either aclouds.yaml file oropenrc file for you. If using aclouds.yamlfile, OpenStack Client expects to find it in one of the following locations:

• If set, the path indicated by theOS_CLIENT_CONFIG_FILE environmentvariable
• . (the current directory)
• $HOME/.config/openstack
• /etc/openstack

The options you should set will depend on the configuration of your cloud andthe authentication mechanism(s) supported. For example, consider a cloud thatsupports username/password authentication. Configuration for this cloud using aclouds.yaml file would look like so:

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:

export OS_AUTH_URL=<url-to-openstack-identity>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)

Likewise, the corresponding command-line options would look very similar:

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>]

Some clouds use federated authentication. If this is the case, yourconfiguration will be slightly more involved. For example, to configureusername/password authentication for a federated user using aclouds.yamlfile:

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:

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=3export OS_AUTH_TYPE=v3oidcpasswordexport OS_USERNAME=<username-in-idp>export OS_PASSWORD=<password-in-idp>export OS_IDENTITY_PROVIDER=<the-desired-idp-in-keystone>export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>

Likewise, the corresponding command-line options would look very similar:

--os-project-name<project-name>--os-project-domain-name<project-domain-name>--os-auth-url<url-to-openstack-identity>--os-identity-api-version 3--os-auth-plugin openid--os-auth-type v3oidcpassword--os-username<username-in-idp>--os-password<password-in-idp>--os-identity-provider<the-desired-idp-in-keystone>--os-client-id<the-client-id-configured-in-the-idp>--os-client-secret<the-client-secred-configured-in-the-idp>--os-openid-scope<the-scopes-of-desired-attributes-to-claim-from-idp>--os-protocol<the-protocol-used-in-the-apache2-oidc-proxy>--os-access-token-type<the-access-token-type-used-by-your-idp>--os-discovery-endpoint<the-well-known-endpoint-of-the-idp>

For more information on configuring authentication, including an overview ofthe many authentication mechanisms supported, refer to theAuthenticationguide. For more information on configuration in general, refer to theConfiguration guide.

You can clone the repository from opendev.org:

git clone https://opendev.org/openstack/python-openstackclientcd python-openstackclient

OpenStack Client uses the same contributor process as other OpenStack projects.For information on this process, including help on setting up you Gerritaccount and an overview of the CI process, refer to theOpenStack ContributorsGuide.

For more information on contributing to OpenStack Client itself, includingguidance on how to design new commands and how to report bugs, refer to theContributors Guide.

• Issue Tracker
• Code Review
• Documentation
• PyPi
• Mailing list
• Release Notes
• IRC (#openstack-sdks on OFTC (irc.oftc.net))