blob: c892df1c102395c02449cba74682026cd18ffadf (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
================
OpenStack Client
================
OpenStackclient (aka ``python-openstackclient``) is a command-line client for
the OpenStack APIs.
It is primarily a wrapper to the stock python-*client modules that implement the
actual REST API client actions.
This is an implementation of the design goals shown in
`OpenStack Client Wiki`_. The primary goal is to provide
a unified shell command structure and a common language to describe
operations in OpenStack. The master repository is on GitHub_.
.. _OpenStack Client Wiki: https://wiki.openstack.org/wiki/OpenStackClient
.. _GitHub: https://github.com/openstack/python-openstackclient
OpenStackclient has a plugin mechanism to add support for API extensions.
* `Release management`_
* `Blueprints and feature specifications`_
* `Issue tracking`_
* `PyPi`_
* `Developer Docs`_
.. _release management: https://launchpad.net/python-openstackclient
.. _Blueprints and feature specifications: https://blueprints.launchpad.net/python-openstackclient
.. _Issue tracking: https://bugs.launchpad.net/python-openstackclient
.. _PyPi: https://pypi.python.org/pypi/python-openstackclient
.. _Developer Docs: http://docs.openstack.org/developer/python-openstackclient/
.. _install virtualenv: tools/install_venv.py
Note
====
OpenStackClient is considered to be beta release quality as of the 0.3 release;
no assurances are made at this point for ongoing compatibility in command forms
or output. We do not, however, expect any major changes at this point.
Getting Started
===============
OpenStackclient can be installed from PyPI using pip::
pip install python-openstackclient
Developers can use the `install virtualenv`_ script to create the virtualenv::
python tools/install_venv.py
source .venv/bin/activate
python setup.py develop
Unit tests are now run using tox. The ``run_test.sh`` script provides compatibility
but is generally considered deprecated.
The client can be called interactively by simply typing::
openstack
There are a few variants on getting help. A list of global options and supported
commands is shown with ``--help``::
openstack --help
There is also a ``help`` command that can be used to get help text for a specific
command::
openstack help
openstack help server create
Configuration
=============
The CLI is configured via environment variables and command-line
options as listed in https://wiki.openstack.org/wiki/OpenStackClient/Authentication.
The 'password flow' variation is most commonly used::
export OS_AUTH_URL=<url-to-openstack-identity>
export OS_PROJECT_NAME=<project-name>
export OS_USERNAME=<user-name>
export OS_PASSWORD=<password> # (optional)
The corresponding command-line options look very similar::
--os-auth-url <url>
--os-project-name <project-name>
--os-username <user-name>
[--os-password <password>]
If a password is not provided above (in plaintext), you will be interactively
prompted to provide one securely.
The token flow variation for authentication uses an already-acquired token
and a URL pointing directly to the service API that presumably was acquired
from the Service Catalog::
export OS_TOKEN=<token>
export OS_URL=<url-to-openstack-service>
The corresponding command-line options look very similar::
--os-token <token>
--os-url <url-to-openstack-service>
Additional command-line options and their associated environment variables
are listed here::
--debug # turns on some debugging of the API conversation
--verbose | -v # Increase verbosity of output. Can be repeated.
--quiet | -q # suppress output except warnings and errors
--help | -h # show a help message and exit
Building Documentation
======================
This documentation is written by contributors, for contributors.
The source is maintained in the ``doc/source`` folder using
`reStructuredText`_ and built by `Sphinx`_
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx.pocoo.org/
Building Manually::
cd doc
make html
Results are in the ``build/html`` directory.
|
