openstack/deb-python-keystoneclient
Code Issues Proposed changes

updating base keystoneclient documentation

Browse Source 
* updated changelog
* described CLI authentication for admin and user
* tweaked API usage docs a bit with formatting and typos

Change-Id: I61c3aab99bb0ecbad1de6d32a767558ca1a2ab5b
This commit is contained in:
Joe Heck
2012-09-28 15:57:25 +00:00
parent 06916aab53
commit 135100a2ed
4 changed files with 74 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/index.rst
View File

@@ -18,7 +18,7 @@ Contents:
Contributing
============
Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
`Launchpad`_. Submit code to the openstack/python-keystoneclient project using
`Gerrit`_.

129
doc/source/releases.rst
View File

@@ -2,105 +2,32 @@
Release notes
=============
2.7.0 (October 21, 2011)
========================
* Forked from http://github.com/rackspace/python-novaclient
* Rebranded to python-keystoneclient
* Refactored to support Keystone API (auth, tokens, services, roles, tenants,
0.1.3 (August 31, 2012)
=======================
* changed logging to report request and response independently in --debug mode
* changed options to use hyphens instead of underscores
* added support for PKI signed tokens with Keystone
0.1.2 (July 9, 2012)
====================
* added support for two-way SSL and --insecure option to allow for self-signed
certificates
* added support for password prompting if not provided
* added support for bash completion for keystone
* updated CLI options to use dashes instead of underscores
0.1.1 (June 25, 2012)
=====================
* corrected versioning
0.1.0 (March 29, 2012)
======================
* released with OpenStack Essex and Diablo compatibility
* forked from http://github.com/rackspace/python-novaclient
* refactored to support Keystone API (auth, tokens, services, roles, tenants,
users, etc.)
2.5.8 (July 11, 2011)
=====================
* returns all public/private ips, not just first one
* better 'nova list' search options
2.5.7 - 2.5.6 = minor tweaks
2.5.5 (June 21, 2011)
=====================
* zone-boot min/max instance count added thanks to comstud
* create for user added thanks to cerberus
* fixed tests
2.5.3 (June 15, 2011)
=====================
* ProjectID can be None for backwards compatability.
* README/docs updated for projectId thanks to usrleon
2.5.1 (June 10, 2011)
=====================
* ProjectID now part of authentication
2.5.0 (June 3, 2011)
====================
* better logging thanks to GridDynamics
2.4.4 (June 1, 2011)
====================
* added support for GET /servers with reservation_id (and /servers/detail)
2.4.3 (May 27, 2011)
====================
* added support for POST /zones/select (client only, not cmdline)
2.4 (March 7, 2011)
===================
* added Jacob Kaplan-Moss copyright notices to older/untouched files.
2.3 (March 2, 2011)
===================
* package renamed to python-novaclient. Module to novaclient
2.2 (March 1, 2011)
===================
* removed some license/copywrite notices from source that wasn't
significantly changed.
2.1 (Feb 28, 2011)
==================
* shell renamed to nova from novatools
* license changed from BSD to Apache
2.0 (Feb 7, 2011)
=================
* Forked from https://github.com/jacobian/python-cloudservers
* Rebranded to python-novatools
* Auth URL support
* New OpenStack specific commands added (pause, suspend, etc)
1.2 (August 15, 2010)
=====================
* Support for Python 2.4 - 2.7.
* Improved output of :program:`cloudservers ipgroup-list`.
* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
<id>``).
1.1 (May 6, 2010)
=================
* Added a ``--files`` option to :program:`cloudservers boot` supporting
the upload of (up to five) files at boot time.
* Added a ``--key`` option to :program:`cloudservers boot` to key the server
with an SSH public key at boot time. This is just a shortcut for ``--files``,
but it's a useful shortcut.
* Changed the default server image to Ubuntu 10.04 LTS.
* removed legacy arguments of --username, --password, etc in migration to
support a cross-openstack unified CLI convention defined at
http://wiki.openstack.org/UnifiedCLI
* required service ID for listing endpoints

39
doc/source/shell.rst
View File

@@ -1,5 +1,5 @@
The :program:`keystone` shell utility
=========================================
=====================================
.. program:: keystone
.. highlight:: bash
@@ -8,15 +8,36 @@ The :program:`keystone` shell utility
The :program:`keystone` shell utility interacts with OpenStack Keystone API
from the command line. It supports the entirety of the OpenStack Keystone API.
First, you'll need an OpenStack Keystone account. You get this by using the
`keystone-manage` command in OpenStack Keystone.
To communicate with the API, you will need to be authenticated - and the
:program:`keystone` provides multiple options for this.
You'll need to provide :program:`keystone` with your OpenStack username and
password. You can do this with the :option:`--os-username`, :option:`--os-password`.
You can optionally specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`,
to scope your token to a specific tenant. If you don't specify a tenant, you
will be scoped to your default tenant if you have one. Instead of using
options, it is easier to just set them as environment variables:
While bootstrapping keystone the authentication is accomplished with a
shared secret token and the location of the keystone API endpoint. The
shared secret token is configured in keystone.conf as "admin_token".
You can specify those values on the command line with :option:`--os-token`
and :option:`--os-endpoint`, or set them in environment variables:
.. envvar:: OS_SERVICE_TOKEN
Your keystone administrative token
.. envvar:: OS_SERVICE_ENDPOINT
Your keystone API endpoint
The command line options will override any environment variables set.
If you already have accounts, you can use your OpenStack username and
password. You can do this with the :option:`--os-username`,
:option:`--os-password`.
Keystone allows a user to be associated with one or more tenants. To specify
the tenant for which you want to authorize against, you may optionally
specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`.
Instead of using options, it is easier to just set them as environment
variables:
.. envvar:: OS_USERNAME

27
doc/source/using-api.rst
View File

@@ -13,11 +13,12 @@ The main concepts in the Keystone API are:
* endpoints
The Keystone API lets you query and make changes through managers. For example,
to maipulate tenants, you interact with a
to manipulate tenants, you interact with a
``keystoneclient.v2_0.tenants.TenantManger`` object.
You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client``
class is a tenant manager::
You obtain access to managers through via atributes of the
``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants``
attribute of the ``Client`` class is a tenant manager::
>>> from keystoneclient.v2_0 import client
>>> keystone = client.Client(...)
@@ -36,8 +37,8 @@ There are two ways to authenticate against Keystone:
If you are an administrator, you can authenticate by connecting to the admin
endpoint and using the admin token (sometimes referred to as the service
token). The token is specified as the ``admin_token`` configuration option in your
keystone.conf config file, which is typically in /etc/keystone::
token). The token is specified as the ``admin_token`` configuration option in
your keystone.conf config file, which is typically in /etc/keystone::
>>> from keystoneclient.v2_0 import client
>>> token = '012345SECRET99TOKEN012345'
@@ -54,7 +55,7 @@ user::
>>> tenant_name='openstackDemo'
>>> auth_url='http://192.168.206.130:5000/v2.0'
>>> keystone = client.Client(username=username, password=password,
... tenant_name, auth_url=auth_url)
... tenant_name=tenant_name, auth_url=auth_url)
Creating tenants
================
@@ -77,8 +78,9 @@ in the opoenstackDemo tenant. We first need to retrieve the tenant::
>>> keystone = client.Client(...)
>>> tenants = keystone.tenants.list()
>>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0]
>>> my_user = keystone.users.create(name="adminUser", password="secretword",
... tenant_id=my_tenant.id)
>>> my_user = keystone.users.create(name="adminUser",
... password="secretword",
... tenant_id=my_tenant.id)
Creating roles and adding users
===============================
@@ -103,7 +105,8 @@ Compute service::
>>> keystone = client.Client(...)
>>> service = keystone.services.create(name="nova", service_type="compute",
... description="Nova Compute Service")
>>> keystone.endpoints.create(region="RegionOne", service_id=service.id,
... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")
>>> keystone.endpoints.create(
... region="RegionOne", service_id=service.id,
... publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
... internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")