From cab6917356d0af1ab27623745d6f125c7ce0fa62 Mon Sep 17 00:00:00 2001 From: Tom Fifield Date: Wed, 20 Feb 2013 00:28:55 +1100 Subject: Remove old, outdated keystone devref docs The doc/source/old directory contained several docs that were marked as 'old' and hadn't been updated for more than a year. This patch simply removes them - they aren't referred to in any way noticable on keystone.openstack.org. Change-Id: Ida57e0321be09aa8ddcb966f386132946017cdcb --- doc/source/old/backends.rst | 188 --------------- doc/source/old/controllingservers.rst | 288 ----------------------- doc/source/old/endpoints.rst | 430 ---------------------------------- doc/source/old/extensions.rst | 183 --------------- doc/source/old/migration.rst | 126 ---------- doc/source/old/releases.rst | 36 --- doc/source/old/services.rst | 92 -------- doc/source/old/ssl.rst | 118 ---------- 8 files changed, 1461 deletions(-) delete mode 100644 doc/source/old/backends.rst delete mode 100644 doc/source/old/controllingservers.rst delete mode 100644 doc/source/old/endpoints.rst delete mode 100644 doc/source/old/extensions.rst delete mode 100644 doc/source/old/migration.rst delete mode 100644 doc/source/old/releases.rst delete mode 100644 doc/source/old/services.rst delete mode 100644 doc/source/old/ssl.rst (limited to 'doc') diff --git a/doc/source/old/backends.rst b/doc/source/old/backends.rst deleted file mode 100644 index 9bf83b0c..00000000 --- a/doc/source/old/backends.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======== -Backends -======== - -Keystone supports multiple types of data stores for things like users, tenants, and -tokens, including SQL, LDAP, and memcache. - -SQL -=== - -In the default backend configuration (SQL-only), Keystone depends on the following database tables. - -``users`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Unqiue username used for authentication via ``passwordCredentials``. -``password`` - Password used for authentication via ``passwordCredentials``. - - Salted and hashed using ``passlib``. -``email`` - Email address (uniqueness is expected, but not enforced). -``enabled`` - If false, the user is unable to authenticate and the user's tokens will fail validation. -``tenant_id`` - Default tenant for the user. - -``tokens`` ----------- - -``id`` - The actual token provided after successful authentication (*plaintext*). -``user_id`` - References the user who owns the token. -``tenant_id`` - (*optional*) References the tenant the token is scoped to. -``expires`` - Indicates the expiration date of the token, after which the token can no longer be validated successfully. - -``tenants`` ------------ - -``id`` - Auto-incremented primary key. -``name`` - Unique string identifying the tenant. -``desc`` - Description of the tenant. -``enabled`` - If false, users are unable to scope to the tenant. - -``roles`` ---------- - -``id`` - Auto-incremented primary key. -``name`` - Name of the role. - - If the role is owned by a service, the role name **must** follow the convention:: - - serviceName:roleName -``desc`` - Description of the role. -``service_id`` - (*optional*) References the service that owns the role. - -``user_roles`` --------------- - -Maps users to the roles that have been granted to them (*optionally*, within the scope of a tenant). - -``id`` - Auto-incremented primary key. -``user_id`` - References the user the role is granted to. -``role_id`` - References the granted role. -``tenant_id`` - (*optional*) References a tenant upon which this grant is applies. - -``services`` ------------- - -``id`` - Auto-incremented primary key. -``name`` - Unique name of the service. -``type`` - Indicates the type of service (e.g. ``compute``, ``object``, ``identity``, etc). - - This can also be extended to support non-core services. Extended services - follow the naming convention ``extension:type`` (e.g. ``dnsextension:dns``). -``desc`` - Describes the service. -``owner_id`` - (*optional*) References the user who owns the service. - -``credentials`` ---------------- - -Currently only used for Amazon EC2 credential storage, this table is designed to support multiple -types of credentials in the future. - -``id`` - Auto-incremented primary key. -``user_id`` - References the user who owns the credential. -``tenant_id`` - References the tenant upon which the credential is valid. -``types`` - Indicates the type of credential (e.g. ``Password``, ``APIKey``, ``EC2``). -``key`` - Amazon EC2 access key. -``secret`` - Amazon EC2 secret key. - -``endpoints`` -------------- - -Tenant-specific endpoints map endpoint templates to specific tenants. -The ``tenant_id`` which appears here replaces the -``%tenant_id%`` template variable in the specified endpoint template. - -``id`` - Auto-incremented primary key. -``tenant_id`` - References the tenant this endpoint applies to. -``endpoint_template_id`` - The endpoint template to appear in the user's service catalog. - -``endpoint_templates`` ----------------------- - -A multi-purpose model for the service catalog which can be: - -- Provided to users of a specific tenants via ``endpoints``, when ``is_global`` is false. -- Provided to all users as-is, when ``is_global`` is true. - -``id`` - Auto-incremented primary key. -``region`` - Identifies the geographic region the endpoint is physically located within. -``service_id`` - TODO: References the service which owns the endpoints? -``public_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint available on the public Internet. -``admin_url`` - Appears in the service catalog [#first]_. - - Users of this endpoint must have an Admin or ServiceAdmin role. -``internal_url`` - Appears in the service catalog [#first]_. - - Represents an endpoint on an internal, unmetered network. -``enabled`` - If false, this endpoint template will not appear in the service catalog. -``is_global`` - If true, this endpoint can not be mapped to tenant-specific endpoints, and ``%tenant_id%`` will not be substituted in endpoint URL's. Additionally, this endpoint will appear for all users. -``version_id`` - Identifies the version of the API contract that endpoint supports. -``version_list`` - A URL which lists versions supported by the endpoint. -``version_info`` - A URL which provides detailed version info regarding the service. - -.. [#first] ``%tenant_id%`` may be replaced by actual tenant references, depending on the value of ``is_global`` and the existence of a corresponding ``endpoints`` record. diff --git a/doc/source/old/controllingservers.rst b/doc/source/old/controllingservers.rst deleted file mode 100644 index 50fc0902..00000000 --- a/doc/source/old/controllingservers.rst +++ /dev/null @@ -1,288 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================ -Controlling Keystone Servers -============================ - -This section describes the ways to start, stop, and reload the Keystone -services. - -Keystone Services ------------------ - -Keystone can serve a number of REST APIs and extensions on different TCP/IP -ports. - -The Service API -~~~~~~~~~~~~~~~~ - -The core Keystone -API is primarily a read-only API (the only write operation being POST /tokens -which authenticates a client, and returns a generated token). -This API is sufficient to use OpenStack if all users, roles, endpoints already -exist. This is often the case if Keystone is using an enterprise backend -and the backend is managed through other entperrise tools and business -processes. This core API is called the Service API and can be started -separately from the more complete Admin API. By default, Keystone runs -this API on port 5000. This is not an IANA assigned port and should not -be relied upon (instead, use the Admin API on port 35357 to look for -this endpoint - more on this later) - -The Service API is started using this command in the /bin directory:: - - $ ./keystone-auth - -The Admin API -~~~~~~~~~~~~~ - -Inn order for Keystone to be a fully functional service out of the box, -API extensions that provide full CRUD operations is included with Keystone. -This full set of API calls includes the OS-KSCATALOG, OS-KSADM, and OS-KSEC2 -extensions. These extensions provide a full set of create, read, update, delete -(CRUD) operations that can be used to manage Keystone objects through REST -calls. By default Keystone runs this full REST API on TCP/IP port 35357 -(assigned by IANA to Keystone). - -The Admin API is started using this command in the /bin directory:: - - $ ./keystone-admin - - -Both APIs can be loaded simultaneously (on different ports) using this command:: - - $ ./keystone - -Starting a server ------------------ - -There are two ways to start a Keystone service (either the Service API server -or the Admin API server): - -- Manually calling the server program -- Using the ``keystone-control`` server daemon wrapper program - -We recommend using the second way in production and the first for development -and debugging. - -Manually starting the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first is by directly calling the server program, passing in command-line -options and a single argument for a ``paste.deploy`` configuration file to -use when configuring the server application. - -.. note:: - - Keystone ships with an ``etc/`` directory that contains a sample ``paste.deploy`` - configuration files that you can copy to a standard configuration directory and - adapt for your own uses. - -If you do `not` specify a configuration file on the command line, Keystone will -do its best to locate a configuration file in one of the -following directories, stopping at the first config file it finds: - -- ``$CWD`` -- ``~/.keystone`` -- ``~/`` -- ``/etc/keystone`` -- ``/etc`` - -The filename that is searched for is ``keystone.conf`` by default. - -If no configuration file is found, you will see an error, like:: - - $ keystone - ERROR: Unable to locate any configuration file. Cannot load application keystone - -Here is an example showing how you can manually start the ``keystone-auth`` server and ``keystone-registry`` in a shell:: - - $ ./keystone -d - keystone-legacy-auth: INFO ************************************************** - keystone-legacy-auth: INFO Configuration options gathered from config file: - keystone-legacy-auth: INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - keystone-legacy-auth: INFO ================================================ - keystone-legacy-auth: INFO admin_host 0.0.0.0 - keystone-legacy-auth: INFO admin_port 35357 - keystone-legacy-auth: INFO admin_ssl False - keystone-legacy-auth: INFO backends keystone.backends.sqlalchemy - keystone-legacy-auth: INFO ca_certs /etc/keystone/ssl/certs/ca.pem - keystone-legacy-auth: INFO cert_required True - keystone-legacy-auth: INFO certfile /etc/keystone/ssl/certs/keystone.pem - keystone-legacy-auth: INFO debug True - keystone-legacy-auth: INFO default_store sqlite - keystone-legacy-auth: INFO extensions osksadm,oskscatalog,hpidm - keystone-legacy-auth: INFO hash-password True - keystone-legacy-auth: INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - keystone-legacy-auth: INFO keystone-admin-role Admin - keystone-legacy-auth: INFO keystone-service-admin-role KeystoneServiceAdmin - keystone-legacy-auth: INFO log_dir . - keystone-legacy-auth: INFO log_file keystone.log - keystone-legacy-auth: INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - keystone-legacy-auth: INFO service_host 0.0.0.0 - keystone-legacy-auth: INFO service_port 5000 - keystone-legacy-auth: INFO service_ssl False - keystone-legacy-auth: INFO verbose False - keystone-legacy-auth: INFO ************************************************** - passlib.registry: INFO registered crypt handler 'sha512_crypt': - Starting the RAX-KEY extension - Starting the Legacy Authentication component - admin : INFO ************************************************** - admin : INFO Configuration options gathered from config file: - admin : INFO /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - admin : INFO ================================================ - admin : INFO admin_host 0.0.0.0 - admin : INFO admin_port 35357 - admin : INFO admin_ssl False - admin : INFO backends keystone.backends.sqlalchemy - admin : INFO ca_certs /etc/keystone/ssl/certs/ca.pem - admin : INFO cert_required True - admin : INFO certfile /etc/keystone/ssl/certs/keystone.pem - admin : INFO debug True - admin : INFO default_store sqlite - admin : INFO extensions osksadm,oskscatalog,hpidm - admin : INFO hash-password True - admin : INFO keyfile /etc/keystone/ssl/private/keystonekey.pem - admin : INFO keystone-admin-role Admin - admin : INFO keystone-service-admin-role KeystoneServiceAdmin - admin : INFO log_dir . - admin : INFO log_file keystone.log - admin : INFO service-header-mappings { - 'nova' : 'X-Server-Management-Url', - 'swift' : 'X-Storage-Url', - 'cdn' : 'X-CDN-Management-Url'} - admin : INFO service_host 0.0.0.0 - admin : INFO service_port 5000 - admin : INFO service_ssl False - admin : INFO verbose False - admin : INFO ************************************************** - Using config file: /Users/ziadsawalha/Documents/Code/keystone/etc/keystone.conf - Service API (ssl=False) listening on 0.0.0.0:5000 - Admin API (ssl=False) listening on 0.0.0.0:35357 - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:5000/ - eventlet.wsgi.server: DEBUG (77128) wsgi starting up on http://0.0.0.0:35357/ - - $ sudo keystone-registry keystone-registry.conf & - jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0) - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties") - 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] () - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk') - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0) - 2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0) - - $ ps aux | grep keystone - myuser 77148 0.0 0.0 2434892 472 s012 U+ 11:50AM 0:00.01 grep keystone - myuser 77128 0.0 0.6 2459356 25360 s011 S+ 11:48AM 0:00.82 python ./keystone -d - -Simply supply the configuration file as the first argument -and then any common options -you want to use (``-d`` was used above to show some of the debugging -output that the server shows when starting up. Call the server program -with ``--help`` to see all available options you can specify on the -command line.) - -Using ``--trace-calls`` is useful for showing a trace of calls (errors in red) -for debugging. - -For more information on configuring the server via the ``paste.deploy`` -configuration files, see the section entitled -:doc:`Configuring Keystone ` - -Note that the server `daemonizes` itself by using the standard -shell backgrounding indicator, ``&``, in the previous example. For most use cases, we recommend -using the ``keystone-control`` server daemon wrapper for daemonizing. See below -for more details on daemonization with ``keystone-control``. - -Using ``keystone-control`` to start the server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The second way to start up a Keystone server is to use the ``keystone-control`` -program. ``keystone-control`` is a wrapper script that allows the user to -start, stop, restart, and reload the other Keystone server programs in -a fashion that is more conducive to automation and scripting. - -Servers started via the ``keystone-control`` program are always `daemonized`, -meaning that the server program process runs in the background. - -To start a Keystone server with ``keystone-control``, simply call -``keystone-control`` with a server and the word "start", followed by -any command-line options you wish to provide. Start the server with ``keystone-control`` -in the following way:: - - $ sudo keystone-control start [CONFPATH] - -.. note:: - - You must use the ``sudo`` program to run ``keystone-control`` currently, as the - pid files for the server programs are written to /var/run/keystone/ - -Start the ``keystone-admin`` server using ``keystone-control``:: - - $ sudo keystone-control admin start - Starting keystone-admin with /etc/keystone.conf - -The same ``paste.deploy`` configuration files are used by ``keystone-control`` -to start the Keystone server programs, and you can specify (as the example above -shows) a configuration file when starting the server. - -Stopping a server ------------------ - -If you started a Keystone server manually and did not use the ``&`` backgrounding -function, simply send a terminate signal to the server process by typing -``Ctrl-C`` - -If you started the Keystone server using ``keystone-control``, you can -use the ``keystone-control`` program to stop it:: - - $ sudo keystone-control stop - -For example:: - - $ sudo keystone-control auth stop - Stopping keystone-auth pid: 77401 signal: 15 - -Restarting a server -------------------- - -Restart the Keystone server using ``keystone-control``:: - - $ sudo keystone-control admin restart /etc/keystone.conf - Stopping keystone-admin pid: 77401 signal: 15 - Starting keystone-admin with /etc/keystone.conf diff --git a/doc/source/old/endpoints.rst b/doc/source/old/endpoints.rst deleted file mode 100644 index 477592b9..00000000 --- a/doc/source/old/endpoints.rst +++ /dev/null @@ -1,430 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================================ -Endpoints and Endpoint Templates -================================ - -.. toctree:: - :maxdepth: 1 - -What are Endpoints? -------------------- - -Simply, endpoints are URLs that point to OpenStack services. When you -authenticate to Keystone you get back a token which has a service catalog in -it. The service catalog is basically a list of the OpenStack services that -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/" - } - ] - } - ] - } - } - -Note the following about this response: - -#. There are two endpoints given to the Nova compute service. The only - difference between them is the version (1.0 vs. 1.1). This allows for code - written to look for the version 1.0 endpoint to still work even after the 1.1 - version is released. - -#. There are two endpoints for the Swift object-store service. The difference - between them is they are in different regions (North and South). - -#. Note the DNS service is global; it does not have a Region. Also, since DNS - is not a core OpenStack service, the endpoint type is "dnsextension:dns" - showing it is coming from an extension to the Keystone service. - -#. The Region, Tenant, and versionId are listed under the endpoint. You do not - (and should not) have to parse those out of the URL. In fact, they may not be - embedded in the URL if the service developer so chooses. - - -What do the fields in an Endpoint mean? ---------------------------------------- - -The schema definition for an endpoint is in endpoints.xsd under -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`` - (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'. - The list of regions and what a region means is decided by the operator. The - 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 - want to access a swift cluster from inside your Nova VMs and want to make - sure the communication stays local and does not go over a public network - 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 - other mechanism to identify the tenant. This field is therefore optional. - Having this field also means you do not have to parse the URL to identify - 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 - This is the URL to call to get some information on the version. This returns - information in this format:: - - { - "version": { - "id": "v2.0", - "status": "CURRENT", - "updated": "2011-01-21T11:33:21-06:00", - "links": [ - { - "rel": "self", - "href": "http://identity.api.openstack.org/v2.0/" - }, { - "rel": "describedby", - "type": "application/pdf", - "href": "http://docs.openstack.org/identity/api/v2.0/identity-latest.pdf" - }, { - "rel": "describedby", - "type": "application/vnd.sun.wadl+xml", - "href": "http://docs.openstack.org/identity/api/v2.0/identity.wadl" - } - ], - "media-types": [ - { - "base": "application/xml", - "type": "application/vnd.openstack.identity+xml;version=2.0" - }, { - "base": "application/json", - "type": "application/vnd.openstack.identity+json;version=2.0" - } - ] - } - } - -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", - "status":"DEPRECATED", - "updated":"2009-10-09T11:30:00Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.0/" - } - ] - }, - { - "id":"v1.1", - "status":"CURRENT", - "updated":"2010-12-12T18:30:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v1.1/" - } - ] - }, - { - "id":"v2.0", - "status":"BETA", - "updated":"2011-05-27T20:22:02.25Z", - "links":[{ - "rel":"self", - "href":"http://identity.api.openstack.org/v2.0/" - } - ] - } - ], - "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. - -What are Endpoint Templates? ----------------------------- - -Endpoint Templates are a way for an administrator to manage endpoints en masse. -They provide a way to define Endpoints that apply to many or all tenants -without having to a create each endpoint on each tenant manually. Without -Endpoint Templates, if I wanted to create Endpoints for each tenant in my -OpenStack deployment, I'd have to manually create a bunch of endpoints on -each tenant (probably when I created the tenant). And then I'd have to go change -them all whenever a service changed versions or I added a new service. - -To provide a simpler mechanism to manage endpoints on tenants, Keystone uses -Endpoint Templates. I can, for example, define a template with parametrized URLs -and set its `global` to true and that will show up as an endpoint on all the tenants -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 -authentication request for use against tenant 1:: - - $ curl -H "Content-type: application/json" -d '{"auth":{"passwordCredentials":{"username":"joeuser","password":"secrete"}, "tenantId": "1"}}' http://localhost:5000/v2.0/tokens - -The response is:: - - { - "access": { - "serviceCatalog": [ - { - "endpoints": [ - { - "internalURL": "https://compute.north.example.local", - "publicURL": "https://compute.north.example.com/v1/1/", - "region": "North" - } - ], - "name": "nova", - "type": "compute" - } - ], - "token": { - "expires": "2012-02-05T00:00:00", - "id": "887665443383838", - "tenant": { - "id": "1", - "name": "customer-x" - } - }, - "user": { - "id": "1", - "name": "joeuser", - "roles": [ - { - "id": "3", - "name": "Member", - "tenantId": "1" - } - ] - } - } - } - -Notice the adminURL is not showing (this user is a regular user and does not -have rights to see the adminURL) and the tenant ID has been substituted in the -URL:: - - "publicURL": "https://compute.north.example.com/v1/1/", - -This endpoint will show up for all tenants. The OpenStack administrator does -not need to create the endpoint manually. - -.. note:: Endpoint Templates are not part of the core Keystone API (but Endpoints are). - - -What parameters can I use in a Template URL -------------------------------------------- - -Currently the only parameterization available is %tenant_id% which gets -substituted by the Tenant ID. - - -Endpoint Template Types: Global or not --------------------------------------- - -When the global flag is set to true on an Endpoint Template, it means it should -be available to all tenants. Whenever someone authenticates to a tenant, they -will see the Endpoint generated by that template. - -When the global flag is not set, the template only shows up when it is added to -a tenant manually. To add an endpoint to a tenant manually, you must create -the Endpoint and supply the Endpoint Template ID: - -Create the Endpoint Template:: - - $ ./keystone-manage endpointTemplates add West nova https://compute.west.example.com/v1/%tenant_id%/ https://compute.west.example.corp https://compute.west.example.local 1 0 - - Note the 0 at the end - this Endpoint Template is not global. So it will not show up for users authenticating. - -Find the Endpoint Template ID:: - - $ ./keystone-manage endpointTemplates list - - All EndpointTemplates - 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 - -Add the Endpoint to the tenant:: - - $ ./keystone-manage endpoint add customer-x 16 - -Now, when the user authenticates, they get the endpoint:: - - { - "internalURL": "https://compute.west.example.local", - "publicURL": "https://compute.west.example.com/v1/1/", - "region": "West" - } - -Who can see the AdminURL? -------------------------- - -Users who have the Keystone `Admin` or `Service Admin` roles will see the -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, - "type": "compute" - } - ], - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?marker=6&limit=10", - "rel": "next" - } - ] - } diff --git a/doc/source/old/extensions.rst b/doc/source/old/extensions.rst deleted file mode 100644 index f57fd687..00000000 --- a/doc/source/old/extensions.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========== -Extensions -========== - -Extensions support adding features and functions to OpenStack APIs at any time, without prior -approval or waiting for a new API and release cycles. - -The extension framework is in development and documented in extensions_ and extensionspresentation_. - -This document describes the extensions included with Keystone, how to enable and disable them, -and briefly touches on how to write your own extensions. - -.. _extensions: http://docs.openstack.org/trunk/openstack-compute/developer/openstack-api-extensions/content/ch02s01.html -.. _extensionspresentation: http://www.slideshare.net/RackerWilliams/openstack-extensions - -Built-in Extensions -------------------- - -Keystone ships with a number of extensions found under the -``keystone/contib/extensions`` folder. - -The following built-in extensions are included: - -OS-KSADM - - This is an extensions that supports managing users, tenants, and roles - through the API. Without this extensions, the ony way to manage those - objects is through keystone-manage or directly in the underlying database. - - This is an Admin API extension only. - -OS-KSCATALOG - - This extensions supports managing Endpoints and prrovides the Endpoint - Template mechanism for managing bulk endpoints. - - This is an Admin API extension only. - -OS-EC2 - - This extension adds support for EC2 credentials. - - This is an Admin and Service API extension. - -RAX-GRP - - This extension adds functionality the enables groups. - - This is an Admin and Service API extension. - -RAX-KEY - - This extensions adds support for authentication with an API Key (the core - Keystone API only supports username/password credentials) - - This is an Admin and Service API extension. - -HP-IDM - - This extension adds capability to filter roles with optional service IDs - for token validation to mitigate security risks with role name conflicts. - See https://bugs.launchpad.net/keystone/+bug/890411 for more details. - - This is an Admin API extension. Applicable to validate token (GET) - and check token (HEAD) APIs only. - -OS-KSVALIDATE - - This extensions supports admin calls to /tokens without having to specify - the token ID in the URL. Instead, the ID is supplied in a header called - X-Subject-Token. This is provided as an alternative to address any security - concerns that arise when token IDs are passed as part of the URL which is - often (and by default) logged to insecure media. - - This is an Admin API extension only. - -.. note:: - - The included extensions are in the process of being rewritten. Currently - osksadm, oskscatalog, hpidm, and osksvalidate work with this new - extensions design. - - -Enabling & Disabling Extensions -------------------------------- - -The Keystone conf file has a property called extensions. This property holds -the list of supported extensions that you want enabled. If you want to -add/remove an extension from being supported, add/remove the extension key -from this property. The key is the name of the folder of the extension -under the keystone/contrib/extensions folder. - -.. note:: - - If you want to load different extensions in the service API than the Admin API - you need to use different config files. - -Creating New Extensions ------------------------ - -#. **Adopt a unique organization abbreviation.** - - This prefix should uniquely identify your organization within the community. - The goal is to avoid schema and resource collisions with similar extensions. - (e.g. ``OS`` for OpenStack, ``RAX`` for Rackspace, or ``HP`` for Hewlett-Packard) - -#. **Adopt a unique extension abbreviation.** - - Select an abbreviation to identify your extension, and append to - your organization prefix using a hyphen (``-``), by convention - (e.g. ``OS-KSADM`` (for OpenStack's Keystone Administration extension). - - This combination is referred to as your extension's prefix. - -#. **Determine the scope of your extension.** - - Extensions can enhance the Admin API, Service API or both. - -#. **Create a new module.** - - Create a module to isolate your namespace based on the extension prefix - you selected:: - - keystone/contrib/extensions/admin - - ... and/or:: - - keystone/contrib/extensions/service/ - - ... based on which API you are enhancing. - - .. note:: - - In the future, we will support loading external extensions. - -#. Add static extension files for JSON (``*.json``) and XML - (``*.xml``) to the new extension module. - - Refer to `Service Guide `_ - `Sample extension XML `_ - `Sample extension JSON `_ for the the content and structure. - -#. If your extension is adding additional methods override the base class - ``BaseExtensionHandler``, name it ``ExtensionHandler``, and add your methods. - -#. **Document your work.** - - Provide documentation to support your extension. - - Extensions documentation, WADL, and XSD files can be stored in the - ``keystone/content`` folder. - -#. Add your extension name to the list of supported extensions in The - ``keystone.conf`` file. - -Which extensions are enabled? ------------------------------ - -Discover which extensions are available (service API):: - - curl http://localhost:5000/v2.0/extensions - -... or (admin API):: - - curl http://localhost:35357/v2.0/extensions - -The response will list the extensions available. diff --git a/doc/source/old/migration.rst b/doc/source/old/migration.rst deleted file mode 100644 index 460d980b..00000000 --- a/doc/source/old/migration.rst +++ /dev/null @@ -1,126 +0,0 @@ -=================== -Database Migrations -=================== - -Keystone uses SQLAlchemy Migrate (``sqlalchemy-migrate``) to manage -migrations. - -Migrations are tracked using a metadata table (``migrate_version``), which -allows keystone to compare the state of your database to the state it -expects, and to move between versions. - -.. WARNING:: - - Backup your database before applying migrations. Migrations may - attempt to modify both your schema and data, and could result in data - loss. - - Always review the behavior of migrations in a staging environment - before applying them in production. - -Getting Started -=============== - -Your initial approach to migrations should depend on whether you have an -empty database or a schema full of data. - -Starting with an empty database -------------------------------- - -If you have an empty database for keystone to work with, you can simply -run:: - - $ ./bin/keystone-manage database sync - -This command will initialize your metadata table, and run through all the -schema & data migrations necessary to bring your database in sync with -keystone. That's it! - -Starting with an existing database ----------------------------------- - -Place an existing database under version control to enable migration -support:: - - $ ./bin/keystone-manage database version_control - -This command simply creates a ``migrate_version`` table, set at -``version_number`` 0, which indicates that no migrations have been applied. - -If you are starting with an existing schema, you can jump to a specific -schema version without performing migrations using the ``database goto`` -command. For example, if you're starting from a diablo-compatible -database, set your current database ``version_number`` to ``1`` using:: - - $ ./bin/keystone-manage database goto - -Determine your appropriate database ``version_number`` by referencing the -following table: - - +------------+-------------+ - | Release | ``version`` | - +============+=============+ - | pre-diablo | (see below) | - +------------+-------------+ - | diablo | 1 | - +------------+-------------+ - | essex-m1 | 3 | - +------------+-------------+ - | essex-m2 | 4 | - +------------+-------------+ - -From there, you can upgrade normally (see :ref:`upgrading`). - -Starting with a pre-diablo database (cactus) --------------------------------------------- - -You'll need to manually migrate your database to a diablo-compatible -schema, and continue forward from there (if desired) using migrations. - -.. _upgrading: - -Upgrading & Downgrading -======================= - -.. note:: - - Attempting to start keystone with an outdated schema will cause - keystone to abort, to avoid corrupting your data. - -Upgrade to the latest version automatically:: - - $ ./bin/keystone-manage database sync - -Check your current schema version:: - - $ ./bin/keystone-manage database version - -Jump to a specific version without performing migrations:: - - $ ./bin/keystone-manage database goto - -Upgrade to a specific version:: - - $ ./bin/keystone-manage database upgrade - -Downgrade to a specific version (will likely result in data loss!):: - - $ ./bin/keystone-manage database downgrade - -Opting Out of Migrations -======================== - -If you don't want to use migrations (e.g. if you want to manage your -schema manually), keystone will complain in your logs on startup, but -won't actually stop you from doing so. - -It's recommended that you use migrations to get up and running, but if -you want to manage migrations manually after that, simply drop the -``migrate_version`` table:: - - DROP TABLE migrate_version; - -Useful Links -============ - -Principles to follow when developing migrations `OpenStack Deployability `_ diff --git a/doc/source/old/releases.rst b/doc/source/old/releases.rst deleted file mode 100644 index a4b698d7..00000000 --- a/doc/source/old/releases.rst +++ /dev/null @@ -1,36 +0,0 @@ -============= -Release notes -============= - - -E3 (January 26, 2012) -========================================== -* Contract compliance: version response and ATOM, 300 multiple choice -* Global endpoints returned for unscoped calls -* adminUrl only shown to admin clients -* Endpoints have unique ID -* Auth-N/Auth-Z for S3 API (OS-KSS3 extension) -* Default tenant scope optionally returned when authenticating -* Vary header returned for caching proxies - -* Portable identifiers: modifiable, string identifiers in database backend -* Much improved keystone-manage command (see --help and docs) -* OS-KSVALIDATE extension to support not passing tokens in URL -* OS-KSEC2 and OS-KSS3 extensions respond on /tokens -* HP-IDM extension to filter roles to a given service ID -* Additional caching options in middleware (memcache and swift cache) - -* Enhanced configuration management (in line with other OpenStack projects) -* Additional logging -* Enhanced tracer tool (-t or --trace-calls) - -See comprehensive list here https://launchpad.net/keystone/+milestone/essex-3 - - -E2 (December 15, 2011) -======================== -* D5 compatibility middleware -* Database versioning -* Much more documentation: http://keystone.openstack.org - -See https://launchpad.net/keystone/+milestone/essex-2 diff --git a/doc/source/old/services.rst b/doc/source/old/services.rst deleted file mode 100644 index 4c147bd0..00000000 --- a/doc/source/old/services.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================ -Services -================ - -.. toctree:: - :maxdepth: 1 - - -What are services? -================== - -Keystone includes service registry and service catalog functionality which it -uses to respond to client authentication requests with information useful to -clients in locating the list of available services they can access. - -The Service entity in Keystone represents an OpenStack service that is integrated -with Keystone. The Service entity is also used as a reference from roles, endpoints, -and endpoint templates. - -Keystone also includes an authorization mechanism to allow a service to own -its own roles and endpoints and prevent other services from changing or -modifying them. - -Who can create services? -======================== - -Any user with the Admin or Service Admin roles in Keystone may create services. - -How are services created? -========================= - -Services can be created using ``keystone-manage`` or through the REST API using -the OS-KSADM extension calls. - -Using ``keystone-manage`` (see :doc:`man/keystone-manage` for details):: - - $ keystone-manage add service compute nova 'This is a sample compute service' - -Using the REST API (see `extensions dev guide `_ for details):: - - $ curl -H "Content-type: application/json" -X POST -d '{ - "OS-KSADM:service": { - "name": "nova", - "type": "compute", - "description": "This is a sample compute service" - } - }' -H "X-Auth-Token: 999888777666" http://localhost:35357/v2.0/OS-KSADM/services/ - -How is service ownership determined? -==================================== - -Currently, the way to assign ownership to a service is to provide the owner's -user id in the keystone-manage add command:: - - $ keystone-manage add service nova compute 'This is a sample compute service' joeuser - -This will assign ownership to the new service to joeuser. - -When a service has an owner, then only that owner (or a global Admin) can create and manage -roles that start with that service name (ex: "nova:admin") and manage endpoints -and endpoint templates associated with that service. - -Listing services -================ - -Using ``keystone-manage``, the list of services and their owners can be listed:: - - $ keystone-manage service list - - id name type owner_id description - ------------------------------------------------------------------------------- - 1 compute nova joeuser This is a sample compute service - -Using the REST API, call ``GET /v2.0/OS-KSADM/services`` - -.. note: The rest API does not yet support service ownership diff --git a/doc/source/old/ssl.rst b/doc/source/old/ssl.rst deleted file mode 100644 index 926efd59..00000000 --- a/doc/source/old/ssl.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. - Copyright 2011-2012 OpenStack, LLC - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=========================== -x.509 Client Authentication -=========================== - -Purpose -======= - -Allows the Keystone middleware to authenticate itself with the Keystone server -via an x.509 client certificate. Both Service API and Admin API may be secured -with this feature. - -Certificates -============ - -The following types of certificates are required. A set of certficates is provided -in the examples/ssl directory with the Keystone distribution for testing. Here -is the description of each of them and their purpose: - -ca.pem - Certificate Authority chain to validate against. - -keystone.pem - Public certificate for Keystone server. - -middleware-key.pem - Public and private certificate for Keystone middleware. - -cakey.pem - Private key for the CA. - -keystonekey.pem - Private key for the Keystone server. - -Note that you may choose whatever names you want for these certificates, or combine -the public/private keys in the same file if you wish. These certificates are just -provided as an example. - -Configuration -============= - -By default, the Keystone server does not use SSL. To enable SSL with client authentication, -modify the etc/keystone.conf file accordingly: - -1. To enable SSL for Service API:: - - service_ssl = True - -2. To enable SSL for Admin API:: - - admin_ssl = True - -3. To enable SSL client authentication:: - - cert_required = True - -4. Set the location of the Keystone certificate file (example):: - - certfile = /etc/keystone/ca/certs/keystone.pem - -5. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/private/keystonekey.pem - -6. Set the location of the CA chain:: - - ca_certs = /etc/keystone/ca/certs/ca.pem - -Middleware -========== - -Add the following to your middleware configuration to support x.509 client authentication. -If ``cert_required`` is set to ``False`` on the keystone server, the certfile and keyfile parameters -in steps 3) and 4) may be commented out. - -1. Specify 'https' as the auth_protocol:: - - auth_protocol = https - -2. Modify the protocol in 'auth_uri' to be 'https' as well, if the service API is configured - for SSL:: - - auth_uri = https://localhost:5000/ - -3. Set the location of the middleware certificate file (example):: - - certfile = /etc/keystone/ca/certs/middleware-key.pem - -4. Set the location of the Keystone private file (example):: - - keyfile = /etc/keystone/ca/certs/middleware-key.pem - -For an example, take a look at the ``echo.ini`` middleware configuration for the 'echo' example -service in the examples/echo directory. - -Testing -======= - -You can test out how it works by using the ``echo`` example service in the ``examples/echo`` directory -and the certficates included in the ``examples/ssl`` directory. Invoke the ``echo_client.py`` with -the path to the client certificate:: - - python echo_client.py -s -- cgit