Reorganised keystone documentation structure

Divided the keystone docs into four categories, depending
upon the usage criteria: general information (which will
be common for all), developer documentation,
user documantation and operator documentation.

Change-Id: I2f5dd41acd9874739accc54c4f4fd69460b58334
This commit is contained in:
Samriddhi Jain 2017-06-17 14:12:37 +05:30
parent f992b1ce42
commit 459f078d0c
35 changed files with 144 additions and 108 deletions

View File

@ -4,10 +4,10 @@ Using external authentication with Keystone
.. _external-auth: .. _external-auth:
When Keystone is executed in a web server like :doc:`Apache HTTPD When Keystone is executed in a web server like :doc:`Apache HTTPD
<apache-httpd>`, it is possible to have the web server also handle <../getting-started/apache-httpd>`, it is possible to have the web server
authentication. This enables support for additional methods of authentication also handle authentication. This enables support for additional methods of
that are not provided by the identity store backend and the authentication authentication that are not provided by the identity store backend and
plugins that Keystone supports. the authentication plugins that Keystone supports.
Having the web server handle authentication is not exclusive, and both Having the web server handle authentication is not exclusive, and both
Keystone and the web server can provide different methods of authentication at Keystone and the web server can provide different methods of authentication at
@ -72,7 +72,8 @@ server, that will pass down the authenticated user to Keystone using the
``REMOTE_USER`` environment variable. This user must exist in advance in the ``REMOTE_USER`` environment variable. This user must exist in advance in the
identity backend to get a token from the controller. identity backend to get a token from the controller.
To use this method, Keystone should be running on :doc:`HTTPD <apache-httpd>`. To use this method, Keystone should be running on
:doc:`HTTPD <../getting-started/apache-httpd>`.
X.509 example X.509 example
------------- -------------

View File

@ -0,0 +1,17 @@
===============
Advanced Topics
===============
.. toctree::
:maxdepth: 2
federation/federated_identity.rst
.. toctree::
:maxdepth: 1
configure_tokenless_x509.rst
auth-totp.rst
event_notifications.rst
external-auth.rst
security_compliance.rst

View File

@ -0,0 +1,6 @@
Code Documentation
==================
.. toctree::
:maxdepth: 1
api/modules

View File

@ -530,7 +530,8 @@ Keystone provides three authentication methods by default. ``password`` handles
password authentication and ``token`` handles token authentication. password authentication and ``token`` handles token authentication.
``external`` is used in conjunction with authentication performed by a ``external`` is used in conjunction with authentication performed by a
container web server that sets the ``REMOTE_USER`` environment variable. For container web server that sets the ``REMOTE_USER`` environment variable. For
more details, refer to :doc:`External Authentication <external-auth>`. more details, refer to :doc:`External Authentication
<advanced-topics/external-auth>`.
How to Implement an Authentication Plugin How to Implement an Authentication Plugin
----------------------------------------- -----------------------------------------
@ -578,8 +579,8 @@ The ``REMOTE_USER`` environment variable is only set from a containing
webserver. However, to ensure that a user must go through other authentication webserver. However, to ensure that a user must go through other authentication
mechanisms, even if this variable is set, remove ``external`` from the list of mechanisms, even if this variable is set, remove ``external`` from the list of
plugins specified in ``methods``. This effectively disables external plugins specified in ``methods``. This effectively disables external
authentication. For more details, refer to :doc:`ExternalAuthentication authentication. For more details, refer to :doc:`External Authentication
<external-auth>`. <advanced-topics/external-auth>`.
Token Drivers and Providers Token Drivers and Providers
=========================== ===========================

View File

@ -22,7 +22,8 @@ Prerequisites
------------- -------------
In order to follow this tutorial, it is assumed that you have read our In order to follow this tutorial, it is assumed that you have read our
:doc:`development_best_practices` and :doc:`../architecture` documents. :doc:`development_best_practices` and :doc:`../getting-started/architecture`
documents.
Proposing a change Proposing a change
------------------ ------------------
@ -73,8 +74,9 @@ code to implement such change.
Architectural Recapitulation Architectural Recapitulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As you saw in the :doc:`../architecture` document, there are four logical levels of As you saw in the :doc:`../getting-started/architecture` document, there are
code at which a successful request calls: router, controller, manager and four logical levels of code at which a successful request calls: router,
controller, manager and
driver. driver.
For the role backend, they can be found in the directory `keystone/assignment`, For the role backend, they can be found in the directory `keystone/assignment`,

View File

@ -22,7 +22,7 @@ Setting up Keystone
=================== ===================
Get your development environment set up according to Get your development environment set up according to
:doc:`development.environment`. It is recommended that you install :doc:`development_environment`. It is recommended that you install
Keystone into a virtualenv. Keystone into a virtualenv.
@ -235,7 +235,7 @@ Running Tests
Before running tests, you should have ``tox`` installed and available in your Before running tests, you should have ``tox`` installed and available in your
environment (in addition to the other external dependencies in environment (in addition to the other external dependencies in
:doc:`development.environment`): :doc:`development_environment`):
.. code-block:: bash .. code-block:: bash

View File

@ -0,0 +1,18 @@
========================
Developers Documentation
========================
.. toctree::
:maxdepth: 2
development_best_practices.rst
.. toctree::
:maxdepth: 1
development_environment.rst
developing_drivers.rst
api_curl_examples.rst
api_change_tutorial.rst
http-api.rst
services.rst

View File

@ -1,4 +1,3 @@
.. ..
Copyright 2011-2012 OpenStack Foundation Copyright 2011-2012 OpenStack Foundation
All Rights Reserved. All Rights Reserved.
@ -105,7 +104,7 @@ Update the file to match your system configuration. Note the following:
Keystone's primary configuration file (``etc/keystone.conf``) and the Keystone's primary configuration file (``etc/keystone.conf``) and the
PasteDeploy configuration file (``etc/keystone-paste.ini``) must be readable to PasteDeploy configuration file (``etc/keystone-paste.ini``) must be readable to
HTTPD in one of the default locations described in :doc:`configuration`. HTTPD in one of the default locations described in :doc:`../configuration`.
Configuration file location can be customized using the ``OS_KEYSTONE_CONFIG_DIR`` Configuration file location can be customized using the ``OS_KEYSTONE_CONFIG_DIR``
environment variable: if this is set, the ``keystone.conf`` file will be searched environment variable: if this is set, the ``keystone.conf`` file will be searched

View File

@ -0,0 +1,14 @@
===============
Getting Started
===============
.. toctree::
:maxdepth: 1
installing.rst
upgrading.rst
performance.rst
apache-httpd.rst
architecture.rst
policy_mapping.rst
community.rst

View File

@ -21,8 +21,8 @@ Installing Keystone
This document describes how to install Keystone in order to use it. If you are This document describes how to install Keystone in order to use it. If you are
intending to develop on or with Keystone, please read intending to develop on or with Keystone, please read
:doc:`devref/development_best_practices` and :doc:`../devref/development_best_practices` and
:doc:`devref/development.environment`. :doc:`../devref/development_environment`.
Installing from Source Installing from Source
---------------------- ----------------------
@ -73,7 +73,7 @@ You will find sample configuration files in ``etc/``:
* ``policy.json`` * ``policy.json``
* ``default_catalog.templates`` * ``default_catalog.templates``
From here, refer to :doc:`configuration` to choose which backend drivers to From here, refer to :doc:`../configuration` to choose which backend drivers to
enable and use. Once configured, you should be able to run Keystone by issuing enable and use. Once configured, you should be able to run Keystone by issuing
the command: the command:
@ -83,7 +83,7 @@ the command:
By default, this will show logging on the console from which it was started. By default, this will show logging on the console from which it was started.
Once started, you can initialize data in Keystone for use with the rest of Once started, you can initialize data in Keystone for use with the rest of
OpenStack, as described in :doc:`configuration`. OpenStack, as described in :doc:`../configuration`.
An excellent reference implementation of setting up Keystone is DEVSTACK_, An excellent reference implementation of setting up Keystone is DEVSTACK_,
most commonly used for development and testing setup of not only Keystone, most commonly used for development and testing setup of not only Keystone,
@ -111,7 +111,7 @@ the Keystone service (`keystone`), and place default configurations in
all SQL based, stored locally in SQLite. all SQL based, stored locally in SQLite.
Once installed, you still need to initialize data in Keystone, which you can Once installed, you still need to initialize data in Keystone, which you can
find described in :doc:`configuration`. find described in :doc:`../configuration`.
Installing from packages: Fedora Installing from packages: Fedora
-------------------------------- --------------------------------
@ -126,6 +126,6 @@ To install the packages:
$ sudo yum install openstack-keystone $ sudo yum install openstack-keystone
Once installed, you still need to initialize data in Keystone, which you can Once installed, you still need to initialize data in Keystone, which you can
find described in :doc:`configuration`. find described in :doc:`../configuration`.
.. _`OpenStack Install Guide`: https://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html .. _`OpenStack Install Guide`: https://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html

View File

@ -31,104 +31,50 @@ useful.
.. _`end-user perspective`: https://docs.openstack.org .. _`end-user perspective`: https://docs.openstack.org
This documentation is generated by the Sphinx toolkit and lives in the `source This documentation is generated by the Sphinx toolkit and lives in the `source
tree`_. Also see the :doc:`community` page for other ways to interact with the tree`_. Also see the :doc:`getting-started/community` page for other ways to interact with the
community. community.
.. _`source tree`: https://git.openstack.org/cgit/openstack/keystone/tree/doc/source .. _`source tree`: https://git.openstack.org/cgit/openstack/keystone/tree/doc/source
Related Identity Projects General Information
========================= ~~~~~~~~~~~~~~~~~~~
In addition to creating OpenStack's Identity Service, the Keystone team also This section sontains the general information related to keystone which is commom to all
provides a `WSGI middleware`_, an `Authentication library`_ and a `Python the developers, users and operators. For documentation specific to the any of these three,
client library`_. please see the subsequent sections.
.. _`WSGI middleware`: https://docs.openstack.org/developer/keystonemiddleware/
.. _`Authentication library`: https://docs.openstack.org/developer/keystoneauth/
.. _`Python client library`: https://docs.openstack.org/developer/python-keystoneclient/
Getting Started
===============
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
installing related_projects.rst
upgrading getting-started/index.rst
performance man/index.rst
apache-httpd code_documentation.rst
architecture indices-tables.rst
policy_mapping
community
Configuration
=============
.. toctree::
:maxdepth: 2
configuration
Advanced Topics
===============
.. toctree::
:maxdepth: 2
federation/federated_identity
.. toctree::
:maxdepth: 1
configure_tokenless_x509
auth-totp
event_notifications
external-auth
security_compliance
Developers Documentation Developers Documentation
======================== ~~~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 2
devref/development_best_practices This section contains the documentation needed for developing keystone.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
devref/development.environment devref/index.rst
devref/developing_drivers
devref/api_curl_examples
devref/api_change_tutorial
devref/http-api
devref/services
Sample Files Operator Documentation
============ ~~~~~~~~~~~~~~~~~~~~~~
This section contains the documentation for operating, deploying and configuring
the keystone service.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
sample_config configuration.rst
sample_policy advanced-topics/index.rst
sample_files/index.rst
Man Pages API Documentation
========= ~~~~~~~~~~~~~~~~~
An end user can find the specific API documentation here, `OpenStack's Identity API`_.
.. toctree::
:maxdepth: 1
man/keystone-manage
Code Documentation
==================
.. toctree::
:maxdepth: 1
api/modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,6 @@
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

7
doc/source/man/index.rst Normal file
View File

@ -0,0 +1,7 @@
Man Pages
=========
.. toctree::
:maxdepth: 1
keystone-manage

View File

@ -0,0 +1,10 @@
Related Identity Projects
=========================
In addition to creating OpenStack's Identity Service, the Keystone team also
provides a `WSGI middleware`_, an `Authentication library`_ and a `Python
client library`_.
.. _`WSGI middleware`: https://docs.openstack.org/developer/keystonemiddleware/
.. _`Authentication library`: https://docs.openstack.org/developer/keystoneauth/
.. _`Python client library`: https://docs.openstack.org/developer/python-keystoneclient/

View File

@ -0,0 +1,8 @@
Sample Files
============
.. toctree::
:maxdepth: 1
sample_config
sample_policy

View File

@ -7,6 +7,6 @@ auto-generated from keystone when this documentation is built, so if you are
having issues with an option, please compare your version of keystone with the having issues with an option, please compare your version of keystone with the
version of this documentation. version of this documentation.
The sample configuration can also be viewed in `file form <_static/keystone.conf.sample>`_. The sample configuration can also be viewed in `file form <../_static/keystone.conf.sample>`_.
.. literalinclude:: _static/keystone.conf.sample .. literalinclude:: ../_static/keystone.conf.sample

View File

@ -10,6 +10,6 @@ to help explain which policy operations protect specific keystone APIs, but it
is not suggested to copy and paste into a deployment unless you're planning on is not suggested to copy and paste into a deployment unless you're planning on
providing a different policy for an operation that is not the default. providing a different policy for an operation that is not the default.
The sample policy file can also be viewed in `file form <_static/keystone.policy.yaml.sample>`_. The sample policy file can also be viewed in `file form <../_static/keystone.policy.yaml.sample>`_.
.. literalinclude:: _static/keystone.policy.yaml.sample .. literalinclude:: ../_static/keystone.policy.yaml.sample

View File

@ -237,7 +237,8 @@ class PolicyJsonTestCase(unit.TestCase):
# targets. # targets.
doc_path = os.path.join( doc_path = os.path.join(
unit.ROOTDIR, 'doc', 'source', 'policy_mapping.rst') unit.ROOTDIR, 'doc', 'source', 'getting-started',
'policy_mapping.rst')
with open(doc_path) as doc_file: with open(doc_path) as doc_file:
for line in doc_file: for line in doc_file:
if line.startswith('Target'): if line.startswith('Target'):