Improved doc formatting consistency (bug 898211)

Change-Id: I588a87fe9004c32946a6af0637688838f43c46b1
This commit is contained in:
Dolph Mathews 2011-11-30 10:33:27 -06:00
parent 1778dcf006
commit 0ea013a059
6 changed files with 159 additions and 195 deletions

View File

@ -66,7 +66,7 @@ to write drafts for specs or documentation, describe a blueprint, or collaborate
`OpenStack Wiki <http://wiki.openstack.org/>`_
Keystone on Launchpad
-------------------
---------------------
Launchpad is a code hosting service that hosts the Keystone source code. From
Launchpad you can report bugs, ask questions, and register blueprints (feature requests).

View File

@ -27,24 +27,22 @@ Configuring Keystone
Once Keystone is installed, there are a number of configuration options
available and potentially some initial data to create and set up.
Sample data / Quick Setup
=========================
Default sampledata is provided for easy setup and testing in bin/sampeldata. To
set up the sample data run the following command while Keystone is running:
set up the sample data run the following command while Keystone is running::
$ ./bin/sampledata
The sample data created comes from the file :doc:`keystone.test.sampledata`
The sample data created comes from the file :doc:`sourcecode/keystone.test.sampledata`
Keystone Configuration File
===========================
Most configuration is done via configuration files. The default files are
in /etc/keystone.conf
in ``/etc/keystone.conf``
When starting up a Keystone server, you can specify the configuration file to
use (see :doc:`controllingservers`).
@ -65,8 +63,3 @@ In addition to this documentation page, you can check the
``etc/keystone.conf`` sample configuration
files distributed with keystone for example configuration files for each server
application with detailed comments on what each options does.

View File

@ -29,16 +29,16 @@ Setting up a virtualenv
We recommend establishing a virtualenv to run keystone within. To establish
this environment, use the command::
$> python tools/install_venv.py
$ python tools/install_venv.py
This will create a local virtual environment in the directory ``.keystone-venv``.
Once created, you can activate this virtualenv for your current shell using:
Once created, you can activate this virtualenv for your current shell using::
$> source .keystone-venv/bin/activate
$ source .keystone-venv/bin/activate
The virtual environment can be disabled using the command::
$> deactivate
$ deactivate
You can also use ``tools\with_venv.sh`` to prefix commands so that they run
within the virtual environment. For more information on virtual environments,
@ -51,22 +51,23 @@ Running Keystone
To run the keystone Admin and API server instances, use::
$> tools/with_venv.sh bin/keystone
$ tools/with_venv.sh bin/keystone
Running a demo service that uses Keystone
-----------------------------------------
To run client demo (with all auth middleware running locally on sample service):
$> tools/with_venv.sh examples/echo/bin/echod
To run client demo (with all auth middleware running locally on sample service)::
which spins up a simple "echo" service on port 8090. To use a simple echo client:
$ tools/with_venv.sh examples/echo/bin/echod
$> python examples/echo/echo_client.py
which spins up a simple "echo" service on port 8090. To use a simple echo client::
$ python examples/echo/echo_client.py
Interacting with Keystone
=========================
You can interact with Keystone through the command line using :doc:`keystone-manage`
You can interact with Keystone through the command line using :doc:`man/keystone-manage`
which allows you to establish tenants, users, etc.
You can also interact with Keystone through it's REST API. There is a python
@ -78,29 +79,10 @@ the REST API.
The easiest way to establish some base information in Keystone to interact with is
to invoke::
$> tools/with_venv.sh bin/sampledata
$ tools/with_venv.sh bin/sampledata
You can see the details of what that creates in ``keystone/test/sampledata.py``
interacting with keystone using curl
------------------------------------
Get an unscoped token::
$> curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
Get a token for a tenant::
$> curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}, "tenantName": "customer-x"}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
Get an admin token::
$> curl -d '{"auth": {"passwordCredentials": {"username": "admin", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens
Get a list of tenants using the admin token::
$> curl -H "X-Auth-Token: abcdef-my-token-35774654455" http://localhost:35357/v2.0/tenants
Enabling debugging middleware
-----------------------------
@ -108,7 +90,7 @@ You can enable a huge amount of additional data (debugging information) about
the request and repsonse objects flowing through Keystone using the debugging
WSGI middleware.
To enable this, just modify the pipelines in ``etc/keystone.conf``, changing::
To enable this, just modify the pipelines in ``etc/keystone.conf``, from::
[pipeline:admin]
pipeline =
@ -122,7 +104,7 @@ To enable this, just modify the pipelines in ``etc/keystone.conf``, changing::
RAX-KEY-extension
service_api
to::
... to::
[pipeline:admin]
pipeline =
@ -138,16 +120,15 @@ to::
RAX-KEY-extension
service_api
Two simple and easy debugging tools are using the ``-d`` when you start keystone::
Two simple and easy debugging tools are using the `-d` when you start keystone::
$ ./keystone -d
$> ./keystone -d
and the `--trace-calls` flag::
$> ./keystone -trace-calls
$ ./keystone -trace-calls
The `-d` flag outputs debug information to the console. The `--trace-calls` flag
The ``-d`` flag outputs debug information to the console. The ``--trace-calls`` flag
outputs extensive, nested trace calls to the console and highlights any errors
in red.

View File

@ -31,93 +31,93 @@ you have access to and the URLs you can use to get to them; their endpoints.
Here is an example response from Keystone when you authenticate::
{
"access":{
"token":{
"id":"ab48a9efdfedb23ty3494",
"expires":"2010-11-01T03:32:15-05:00",
"tenant":{
"id": "t1000",
"name": "My Project"
}
},
"user":{
"id":"u123",
"name":"jqsmith",
"roles":[{
"id":"100",
"name":"compute:admin"
},
{
"id":"101",
"name":"object-store:admin",
"tenantId":"t1000"
}
],
"roles_links":[]
},
"serviceCatalog":[{
"name":"Nova",
"type":"compute",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://compute.north.host.com/v1/t1000",
"internalURL":"https://compute.north.internal/v1/t1000",
"region":"North",
"versionId":"1",
"versionInfo":"https://compute.north.host.com/v1/",
"versionList":"https://compute.north.host.com/"
},
{
"tenantId":"t1000",
"publicURL":"https://compute.north.host.com/v1.1/t1000",
"internalURL":"https://compute.north.internal/v1.1/t1000",
"region":"North",
"versionId":"1.1",
"versionInfo":"https://compute.north.host.com/v1.1/",
"versionList":"https://compute.north.host.com/"
}
],
"endpoints_links":[]
},
{
"name":"Swift",
"type":"object-store",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://storage.north.host.com/v1/t1000",
"internalURL":"https://storage.north.internal/v1/t1000",
"region":"North",
"versionId":"1",
"versionInfo":"https://storage.north.host.com/v1/",
"versionList":"https://storage.north.host.com/"
},
{
"tenantId":"t1000",
"publicURL":"https://storage.south.host.com/v1/t1000",
"internalURL":"https://storage.south.internal/v1/t1000",
"region":"South",
"versionId":"1",
"versionInfo":"https://storage.south.host.com/v1/",
"versionList":"https://storage.south.host.com/"
}
]
},
{
"name":"DNS-as-a-Service",
"type":"dnsextension:dns",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://dns.host.com/v2.0/t1000",
"versionId":"2.0",
"versionInfo":"https://dns.host.com/v2.0/",
"versionList":"https://dns.host.com/"
}
]
}
]
}
}
{
"access":{
"token":{
"id":"ab48a9efdfedb23ty3494",
"expires":"2010-11-01T03:32:15-05:00",
"tenant":{
"id": "t1000",
"name": "My Project"
}
},
"user":{
"id":"u123",
"name":"jqsmith",
"roles":[{
"id":"100",
"name":"compute:admin"
},
{
"id":"101",
"name":"object-store:admin",
"tenantId":"t1000"
}
],
"roles_links":[]
},
"serviceCatalog":[{
"name":"Nova",
"type":"compute",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://compute.north.host.com/v1/t1000",
"internalURL":"https://compute.north.internal/v1/t1000",
"region":"North",
"versionId":"1",
"versionInfo":"https://compute.north.host.com/v1/",
"versionList":"https://compute.north.host.com/"
},
{
"tenantId":"t1000",
"publicURL":"https://compute.north.host.com/v1.1/t1000",
"internalURL":"https://compute.north.internal/v1.1/t1000",
"region":"North",
"versionId":"1.1",
"versionInfo":"https://compute.north.host.com/v1.1/",
"versionList":"https://compute.north.host.com/"
}
],
"endpoints_links":[]
},
{
"name":"Swift",
"type":"object-store",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://storage.north.host.com/v1/t1000",
"internalURL":"https://storage.north.internal/v1/t1000",
"region":"North",
"versionId":"1",
"versionInfo":"https://storage.north.host.com/v1/",
"versionList":"https://storage.north.host.com/"
},
{
"tenantId":"t1000",
"publicURL":"https://storage.south.host.com/v1/t1000",
"internalURL":"https://storage.south.internal/v1/t1000",
"region":"South",
"versionId":"1",
"versionInfo":"https://storage.south.host.com/v1/",
"versionList":"https://storage.south.host.com/"
}
]
},
{
"name":"DNS-as-a-Service",
"type":"dnsextension:dns",
"endpoints":[{
"tenantId":"t1000",
"publicURL":"https://dns.host.com/v2.0/t1000",
"versionId":"2.0",
"versionInfo":"https://dns.host.com/v2.0/",
"versionList":"https://dns.host.com/"
}
]
}
]
}
}
Note the following about this response:
@ -146,23 +146,19 @@ keystone/content/common/xsd in the Keystone code repo. The fields are:
id
A unique ID for the endpoint.
type
The OpenStack-registered type (ex. 'compute', 'object-store', 'image service')
This can also be extended using the OpenStack Extension mechanism to support
non-core services. Extended services will be in the form extension:type. Ex.
dnsextension:dns
non-core services. Extended services will be in the form ``extension:type``
(e.g. ``dnsextension:dns``)
name
This can be anything that the operator of OpenStack chooses. It could be a
brand or marketing name (ex. Rackspace Cloud Servers).
region
This is a string that identifies the region where this endpoint exists.
Examples are 'North America', 'Europe', 'Asia'. Or 'North' and 'South'. Or
'Data Center 1', 'Data Center 2'.
@ -170,11 +166,9 @@ region
spec treats them as opaque strings.
publicURL
This is the URL to use to access that endpoint over the internet.
internalURL
This is the URL to use to communicate between services. This is genenrally
a way to communicate between services over a high bandwidth, low latency,
unmetered (free, no bandwidth charges) network. An example would be if you
@ -183,12 +177,10 @@ internalURL
and rack up your bandwidth charges.
adminURL
This is the URL to use to administer the service. In Keystone, this URL
is only shown to users with the appropriate rights.
tenantId
If an endpoint is specific to a tenant, the tenantId field identifies the
tenant that URL applies to. Some operators include the tenant in the
URLs for a service, while others may provide one endpoint and use some
@ -197,18 +189,16 @@ tenantId
a tenant if the operator includes it in the URL.
versionId
This identifies the version of the API contract that endpoint supports.
While many APIs include the version in the URL (ex: https://compute.host/v1),
this field allows you to identify the version without parsing the URL. It
therefore also allows operators and service developers to publish endpoints
that do not have versions embedded in the URL.
versionInfo
versionInfo
This is the URL to call to get some information on the version. This returns
information in this format::
{
"version": {
"id": "v2.0",
@ -244,7 +234,7 @@ versionList
This is the URL to call to find out which versions are supported at that
endpoint. The response is in this format::
{
"versions":[{
"id":"v1.0",
@ -279,7 +269,7 @@ versionList
],
"versions_links":[]
}
Here, the response shows that the endpoint supports version 1.0, 1.1, and 2.0.
It also shows that 1.0 is in DEPRECTAED status and 2.0 is in BETA.
@ -302,9 +292,9 @@ I have. Here is an example:
Define a global Endpoint Template::
$ ./keystone-manage endpointTemplates add North nova https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp/v1/ https://compute.north.example.local/v1/%tenant_id%/ 1 1
The arguments are: object_type action 'region' 'service_name' 'publicURL' 'adminURL' 'internalURL' 'enabled' 'global'
This creates a global endpoint (global means it gets applied to all tenants automatically).
Now, when a user authenticates, they get that endpoint in their service catalog. Here's an example
@ -320,30 +310,30 @@ The response is::
{
"endpoints": [
{
"internalURL": "https://compute.north.example.local",
"publicURL": "https://compute.north.example.com/v1/1/",
"internalURL": "https://compute.north.example.local",
"publicURL": "https://compute.north.example.com/v1/1/",
"region": "North"
}
],
"name": "nova",
],
"name": "nova",
"type": "compute"
}
],
],
"token": {
"expires": "2012-02-05T00:00:00",
"id": "887665443383838",
"expires": "2012-02-05T00:00:00",
"id": "887665443383838",
"tenant": {
"id": "1",
"id": "1",
"name": "customer-x"
}
},
},
"user": {
"id": "1",
"name": "joeuser",
"id": "1",
"name": "joeuser",
"roles": [
{
"id": "3",
"name": "Member",
"id": "3",
"name": "Member",
"tenantId": "1"
}
]
@ -389,13 +379,13 @@ Create the Endpoint Template::
Find the Endpoint Template ID::
$ ./keystone-manage endpointTemplates list
$ ./keystone-manage endpointTemplates list
All EndpointTemplates
id service type region enabled is_global Public URL Admin URL
id service type region enabled is_global Public URL Admin URL
-------------------------------------------------------------------------------
15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp
16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp
15 nova compute North True True https://compute.north.example.com/v1/%tenant_id%/ https://compute.north.example.corp
16 nova compute West True False https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp
Add the Endpoint to the tenant::
@ -404,8 +394,8 @@ Add the Endpoint to the tenant::
Now, when the user authenticates, they get the endpoint::
{
"internalURL": "https://compute.west.example.local",
"publicURL": "https://compute.west.example.com/v1/1/",
"internalURL": "https://compute.west.example.local",
"publicURL": "https://compute.west.example.com/v1/1/",
"region": "West"
}
@ -418,20 +408,20 @@ AdminURL when they authenticate or when they retrieve token information:
Using an administrator token to authenticate, GET a client token's endpoints::
$ curl -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints
{
"endpoints": [
{
"adminURL": "https://compute.west.example.corp",
"id": 6,
"internalURL": "https://compute.west.example.local",
"name": "nova",
"publicURL": "https://compute.west.example.com/v1/1/",
"region": "West",
"tenantId": 1,
"adminURL": "https://compute.west.example.corp",
"id": 6,
"internalURL": "https://compute.west.example.local",
"name": "nova",
"publicURL": "https://compute.west.example.com/v1/1/",
"region": "West",
"tenantId": 1,
"type": "compute"
}
],
],
"endpoints_links": [
{
"href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10",

View File

@ -30,8 +30,8 @@ USAGE
``keystone-admin [options]``
Common Options:
^^^^^^^^^^^^^^^
Common Options
--------------
--version show program's version number and exit
-h, --help show this help message and exit
@ -50,8 +50,9 @@ Common Options:
-t, --trace-calls Turns on call tracing for troubleshooting
-a PORT, --admin-port=PORT Specifies port for Admin API to listen on
(default is 35357)
Logging Options:
^^^^^^^^^^^^^^^^
Logging Options
---------------
The following configuration options are specific to logging
functionality for this program.

View File

@ -30,7 +30,7 @@ USAGE
``keystone-manage [options] type action [additional args]``
user
^^^^
----
* **user add** [username] [password]
@ -45,7 +45,7 @@ user
disables the user *username*
tenant
^^^^^^
------
* **tenant add** [tenant_name]
@ -58,7 +58,7 @@ tenant
* **tenant disable** [tenant_name]
role
^^^^
----
Roles are used to associated users to tenants. Two roles are defined related
to the Keystone service in it's configuration file :doc:`../keystone.conf`
@ -77,7 +77,7 @@ to the Keystone service in it's configuration file :doc:`../keystone.conf`
provided or granted for a specific tenant if tenant_name is provided.
service
^^^^^^^
-------
* **service add** [name] [type] [description] [owner_id]
@ -88,7 +88,7 @@ service
lists all services with id, name, and type
endpointTemplate
^^^^^^^^^^^^^^^^
----------------
* **endpointTemplate add** [region] [service_name] [public_url] [admin_url] [internal_url] [enabled] [is_global]
@ -103,14 +103,13 @@ endpointTemplate
http://keystone_host:5000/v2.0 \
1 1
* **endpointTemplate list** ([tenant_name])
lists endpoint templates with service, region, and public_url. Restricted to
tenant endpoints if tenant_name is provided.
tenant endpoints if tenant_name is provided.
token
^^^^^
-----
* **token add** [token] [username] [tenant] [expiration]
@ -125,14 +124,14 @@ token
deletes the identified token
endpoint
^^^^^^^^
--------
* **endpoint add** [tenant_name] [endpoint_template]
adds a tenant-specific endpoint
credentials
^^^^^^^^^^^
-----------
* **credentials add** [username] [type] [key] [password] ([tenant_name])