From 135100a2ed7849e13b2260b526844cc4170c12f6 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 28 Sep 2012 15:57:25 +0000 Subject: [PATCH] updating base keystoneclient documentation * updated changelog * described CLI authentication for admin and user * tweaked API usage docs a bit with formatting and typos Change-Id: I61c3aab99bb0ecbad1de6d32a767558ca1a2ab5b --- doc/source/index.rst | 2 +- doc/source/releases.rst | 129 +++++++++------------------------------ doc/source/shell.rst | 39 +++++++++--- doc/source/using-api.rst | 27 ++++---- 4 files changed, 74 insertions(+), 123 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index bece0aa9b..bfa63b838 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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`_. diff --git a/doc/source/releases.rst b/doc/source/releases.rst index 4a9d281e5..2f1ed4222 100644 --- a/doc/source/releases.rst +++ b/doc/source/releases.rst @@ -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 `` work (as well as ``--ipgroup - ``). - -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 diff --git a/doc/source/shell.rst b/doc/source/shell.rst index cc0daa65b..e4baf4b8a 100644 --- a/doc/source/shell.rst +++ b/doc/source/shell.rst @@ -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 diff --git a/doc/source/using-api.rst b/doc/source/using-api.rst index d8fa0bcf8..809093e01 100644 --- a/doc/source/using-api.rst +++ b/doc/source/using-api.rst @@ -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")