From eab4ce1ca8affe988cbbd2281408580381e2cfcb Mon Sep 17 00:00:00 2001 From: Florent Flament Date: Tue, 24 Dec 2013 15:57:20 +0000 Subject: Rename using-api.rst to using-api-v2.rst Renaming file for consistency, since using-api-v3.rst is being written there: https://review.openstack.org/#/c/63408 Minor changes have been made to indicate that the file documents the keystone v2 API. Change-Id: I694b658a8b59d21615af5d88edc0f7b394ebbe7b Partial-Bug: #1260527 --- doc/source/index.rst | 2 +- doc/source/using-api-v2.rst | 117 ++++++++++++++++++++++++++++++++++++++++++++ doc/source/using-api.rst | 117 -------------------------------------------- 3 files changed, 118 insertions(+), 118 deletions(-) create mode 100644 doc/source/using-api-v2.rst delete mode 100644 doc/source/using-api.rst (limited to 'doc') diff --git a/doc/source/index.rst b/doc/source/index.rst index 45cb1d6..c982b37 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,7 +12,7 @@ Contents: releases man/keystone - using-api + using-api-v2 api/autoindex diff --git a/doc/source/using-api-v2.rst b/doc/source/using-api-v2.rst new file mode 100644 index 0000000..f491daf --- /dev/null +++ b/doc/source/using-api-v2.rst @@ -0,0 +1,117 @@ +================= +The client v2 API +================= + +Introduction +============ + +The main concepts in the Identity v2 API are: + + * tenants + * users + * roles + * services + * endpoints + +The client v2 API lets you query and make changes through +managers. For example, to manipulate tenants, you interact with a +``keystoneclient.v2_0.tenants.TenantManager`` object. + +You obtain access to managers through via attributes 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(...) + >>> keystone.tenants.list() # List tenants + +You create a valid ``keystoneclient.v2_0.client.Client`` object by passing +authentication data to the constructor. Authentication and examples of common +tasks are provided below. + +You can generally expect that when the client needs to propogate an exception +it will raise an instance of subclass of +``keystoneclient.exceptions.ClientException`` + +Authenticating +============== + +There are two ways to authenticate against Keystone: + * against the admin endpoint with the admin token + * against the public endpoint with a username and password + +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:: + + >>> from keystoneclient.v2_0 import client + >>> token = '012345SECRET99TOKEN012345' + >>> endpoint = 'http://192.168.206.130:35357/v2.0' + >>> keystone = client.Client(token=token, endpoint=endpoint) + +If you have a username and password, authentication is done against the +public endpoint. You must also specify a tenant that is associated with the +user:: + + >>> from keystoneclient.v2_0 import client + >>> username='adminUser' + >>> password='secreetword' + >>> tenant_name='openstackDemo' + >>> auth_url='http://192.168.206.130:5000/v2.0' + >>> keystone = client.Client(username=username, password=password, + ... tenant_name=tenant_name, auth_url=auth_url) + +Creating tenants +================ + +This example will create a tenant named *openStackDemo*:: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> keystone.tenants.create(tenant_name="openstackDemo", + ... description="Default Tenant", enabled=True) + + +Creating users +============== + +This example will create a user named *adminUser* with a password *secretword* +in the opoenstackDemo tenant. We first need to retrieve the tenant:: + + >>> from keystoneclient.v2_0 import client + >>> 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) + +Creating roles and adding users +=============================== + +This example will create an admin role and add the *my_user* user to that +role, but only for the *my_tenant* tenant: + + >>> from keystoneclient.v2_0 import client + >>> keystone = client.Client(...) + >>> role = keystone.roles.create('admin') + >>> my_tenant = ... + >>> my_user = ... + >>> keystone.roles.add_user_role(my_user, role, my_tenant) + +Creating services and endpoints +=============================== + +This example will create the service and corresponding endpoint for the +Compute service:: + + >>> from keystoneclient.v2_0 import client + >>> 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") diff --git a/doc/source/using-api.rst b/doc/source/using-api.rst deleted file mode 100644 index fb1aa3a..0000000 --- a/doc/source/using-api.rst +++ /dev/null @@ -1,117 +0,0 @@ -============== -The client API -============== - -Introduction -============ - -The main concepts in the Identity API are: - - * tenants - * users - * roles - * services - * endpoints - -The Identity API lets you query and make changes through managers. For example, -to manipulate tenants, you interact with a -``keystoneclient.v2_0.tenants.TenantManager`` object. - -You obtain access to managers through via attributes 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(...) - >>> keystone.tenants.list() # List tenants - -You create a valid ``keystoneclient.v2_0.client.Client`` object by passing -authentication data to the constructor. Authentication and examples of common -tasks are provided below. - -You can generally expect that when the client needs to propogate an exception -it will raise an instance of subclass of -``keystoneclient.exceptions.ClientException`` - -Authenticating -============== - -There are two ways to authenticate against Keystone: - * against the admin endpoint with the admin token - * against the public endpoint with a username and password - -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:: - - >>> from keystoneclient.v2_0 import client - >>> token = '012345SECRET99TOKEN012345' - >>> endpoint = 'http://192.168.206.130:35357/v2.0' - >>> keystone = client.Client(token=token, endpoint=endpoint) - -If you have a username and password, authentication is done against the -public endpoint. You must also specify a tenant that is associated with the -user:: - - >>> from keystoneclient.v2_0 import client - >>> username='adminUser' - >>> password='secreetword' - >>> tenant_name='openstackDemo' - >>> auth_url='http://192.168.206.130:5000/v2.0' - >>> keystone = client.Client(username=username, password=password, - ... tenant_name=tenant_name, auth_url=auth_url) - -Creating tenants -================ - -This example will create a tenant named *openStackDemo*:: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> keystone.tenants.create(tenant_name="openstackDemo", - ... description="Default Tenant", enabled=True) - - -Creating users -============== - -This example will create a user named *adminUser* with a password *secretword* -in the opoenstackDemo tenant. We first need to retrieve the tenant:: - - >>> from keystoneclient.v2_0 import client - >>> 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) - -Creating roles and adding users -=============================== - -This example will create an admin role and add the *my_user* user to that -role, but only for the *my_tenant* tenant: - - >>> from keystoneclient.v2_0 import client - >>> keystone = client.Client(...) - >>> role = keystone.roles.create('admin') - >>> my_tenant = ... - >>> my_user = ... - >>> keystone.roles.add_user_role(my_user, role, my_tenant) - -Creating services and endpoints -=============================== - -This example will create the service and corresponding endpoint for the -Compute service:: - - >>> from keystoneclient.v2_0 import client - >>> 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") -- cgit v1.2.1