Reorganize admin guide

Now that most of the operator docs are consolidated into the admin
guide, it is huge and hard to find things. This patch breaks the guide
into groups to make it a little easier to navigate:

1. Getting started: basics of keystone and initializing a deployment.
2. Configuration: not a replacement for the main config docs but a
   grouping of all discussions on the various config options.
3. Operations: maintenance workflows like upgrading and cleanups
4. Tokens: an important part of keystone
5. RBAC: gets a section to itself
6. Advanced keystone features: grouping of lesser-known/lesser-used,
   not-required features.
7. Authentication mechanisms: various auth methods besides password,
   including the federation guide

Change-Id: I9039b7023d843349154d28ee0ee2c7b9a9eb97ab

doc/source/admin/authentication-mechanisms.rst

@@ -0,0 +1,15 @@
+=========================
+Authentication Mechanisms
+=========================
+
+Keystone supports various methods of authentication beyond the standard local
+user and password method.
+
+.. toctree::
+   :maxdepth: 2
+
+   auth-totp
+   federation/federated_identity
+   external-authentication
+   configure_tokenless_x509
+   oauth1

doc/source/admin/caching-layer.rst

@@ -1,5 +1,5 @@
 Caching layer
-~~~~~~~~~~~~~
+=============
 
 OpenStack Identity supports a caching layer that is above the configurable
 subsystems (for example, token). This gives you the flexibility to setup

doc/source/admin/configuration.rst

@@ -0,0 +1,36 @@
+======================
+Keystone Configuration
+======================
+
+Information and recommendations for general configuration of keystone for
+keystone administrators. See the main `Configuration`_ section for
+complete keystone configuration documentation and sample config files.
+
+.. _Configuration: ../configuration/index.html
+
+.. toctree::
+   :maxdepth: 1
+
+   troubleshoot
+   logging
+   domain-specific-config
+   integrate-with-ldap
+   caching-layer
+   security-compliance
+   performance
+   url-safe-naming
+   limit-list-size
+   endpoint-filtering
+   endpoint-policy
+
+.. include:: troubleshoot.rst
+.. include:: logging.rst
+.. include:: domain-specific-config.rst
+.. include:: integrate-with-ldap.rst
+.. include:: caching-layer.rst
+.. include:: security-compliance.rst
+.. include:: performance.rst
+.. include:: url-safe-naming.rst
+.. include:: limit-list-size.rst
+.. include:: endpoint-filtering.rst
+.. include:: endpoint-policy.rst

doc/source/admin/domain-specific-config.rst

@@ -1,4 +1,3 @@
-=============================
 Domain-specific configuration
 =============================
 

doc/source/admin/getting-started.rst

@@ -0,0 +1,14 @@
+===============
+Getting Started
+===============
+
+Everything you need to get started administering a keystone deployment.
+
+.. toctree::
+   :maxdepth: 1
+
+   identity-concepts
+   identity-sources
+   bootstrap
+   cli-manage-projects-users-and-roles
+   manage-services

doc/source/admin/index.rst

@@ -5,49 +5,16 @@ Administrator Guides
 ====================
 
 OpenStack Identity, code-named keystone, is the default Identity
-management system for OpenStack. After you install Identity, you
-configure it through the ``/etc/keystone/keystone.conf``
-configuration file and, possibly, a separate logging configuration
-file. You initialize data into Identity by using the ``keystone``
-command-line client.
-
-.. toctree::
-   :maxdepth: 1
-
-   identity-concepts.rst
-   identity-sources.rst
-   bootstrap.rst
-   cli-manage-projects-users-and-roles.rst
-   manage-services.rst
-   domain-specific-config.rst
-   url-safe-naming.rst
-   case-insensitive.rst
-   integrate-with-ldap.rst
-   upgrading.rst
-   tokens.rst
-   fernet-token-faq.rst
-   manage-trusts.rst
-   caching-layer.rst
-   security-compliance.rst
-   resource-options.rst
-   performance.rst
-   service-api-protection.rst
-   troubleshoot.rst
-   unified-limits.rst
-   token-provider.rst
-   credential-encryption.rst
-   endpoint-filtering.rst
-   health-check-middleware.rst
-   oauth1.rst
-   endpoint-policy.rst
-   event_notifications.rst
-   auth-totp.rst
-   external-authentication.rst
-   configure_tokenless_x509.rst
-   limit-list-size.rst
-   logging.rst
+management system for OpenStack. This section contains guides for keystone
+operators to help with administering a keystone deployment.
 
 .. toctree::
    :maxdepth: 2
 
-   federation/federated_identity.rst
+   getting-started
+   configuration
+   operations
+   tokens
+   service-api-protection
+   keystone-features
+   authentication-mechanisms

doc/source/admin/integrate-with-ldap.rst

@@ -1,6 +1,3 @@
-.. _integrate-identity-with-ldap:
-
-============================
 Integrate Identity with LDAP
 ============================
 
@@ -31,10 +28,8 @@ providing user authentication through the LDAP directory.
     back ends are integrated with LDAP, the identity back end must also be
     integrated with LDAP.
 
-.. _identity_ldap_server_setup:
-
 Identity LDAP server set up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 .. important::
 
@@ -52,8 +47,8 @@ Identity LDAP server set up
 The Identity configuration is split into two separate back ends; identity
 (back end for users and groups), and assignments (back end for domains,
 projects, roles, role assignments). To configure Identity, set options
-in the ``/etc/keystone/keystone.conf`` file. See
-:ref:`integrate-identity-backend-ldap` for Identity back end configuration
+in the ``/etc/keystone/keystone.conf`` file. See `Integrate Identity back end
+with LDAP`_ for Identity back end configuration
 examples. Modify these examples as needed.
 
 **To define the destination LDAP server**
@@ -175,10 +170,8 @@ service.
    During the service restart, authentication and authorization are
    unavailable.
 
-.. _integrate-identity-backend-ldap:
-
 Integrate Identity back end with LDAP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The Identity back end contains information for users, groups, and group
 member lists. Integrating the Identity back end with LDAP allows
@@ -189,7 +182,7 @@ administrators to use users and groups in LDAP.
    For OpenStack Identity service to access LDAP servers, you must
    define the destination LDAP server in the
    ``/etc/keystone/keystone.conf`` file. For more information,
-   see :ref:`identity_ldap_server_setup`.
+   see `Identity LDAP server set up`_.
 
 **To integrate one Identity back end with LDAP**
 
@@ -428,7 +421,7 @@ service.
    unavailable.
 
 Secure the OpenStack Identity service connection to an LDAP back end
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------------------------------------
 
 We recommend securing all connections between OpenStack Identity and LDAP. The
 Identity service supports the use of TLS to encrypt LDAP traffic. Before

doc/source/admin/keystone-features.rst

@@ -0,0 +1,14 @@
+==========================
+Advanced Keystone Features
+==========================
+
+Guides to lesser-known features of keystone.
+
+.. toctree::
+   :maxdepth: 2
+
+   unified-limits
+   resource-options
+   credential-encryption
+   health-check-middleware
+   event_notifications

doc/source/admin/logging.rst

@@ -1,5 +1,5 @@
 Logging
--------
+=======
 
 You configure logging externally to the rest of Identity. The name of
 the file specifying the logging configuration is set using the

doc/source/admin/operations.rst

@@ -0,0 +1,13 @@
+===================
+Keystone Operations
+===================
+
+Guides for managing day-to-day operations of keystone and understanding your
+deployment.
+
+.. toctree::
+   :maxdepth: 1
+
+   upgrading
+   case-insensitive
+   manage-trusts

doc/source/admin/performance.rst

@@ -11,7 +11,6 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-=======================
 Performance and scaling
 =======================
 
@@ -26,7 +25,7 @@ Keystone, many of which are actually trade-offs between performance and
 security that you need to judge for yourself, and tune accordingly.
 
 Keystone configuration options that affect performance
-======================================================
+------------------------------------------------------
 
 These are all of the options in ``keystone.conf`` that have a direct impact on
 performance. See the help descriptions for these options for more specific
@@ -55,7 +54,7 @@ details on how and why you might want to tune these options for yourself.
   key rotation strategies.
 
 Keystonemiddleware configuration options that affect performance
-================================================================
+----------------------------------------------------------------
 
 This configuration actually lives in the Paste pipelines of services consuming
 token validation from keystone (i.e.: nova, cinder, swift, etc.).

doc/source/admin/security-compliance.rst

@@ -1,6 +1,3 @@
-.. _identity_security_compliance:
-
-===============================
 Security compliance and PCI-DSS
 ===============================
 

doc/source/admin/tokens-overview.rst

@@ -0,0 +1,96 @@
+===============
+Keystone tokens
+===============
+
+Tokens are used to authenticate and authorize your interactions with the
+various OpenStack APIs. Tokens come in many scopes, representing various
+authorization and sources of identity.
+
+Authorization scopes
+--------------------
+
+Tokens are used to relay information about your user's role assignments. It's
+not uncommon for a user to have multiple role assignments, sometimes spanning
+projects, domains, or the entire system. These are referred to as authorization
+scopes, where a token has a single scope of operation. For example, a token
+scoped to a project can't be reused to do something else in a different
+project.
+
+Each level of authorization scope is useful for certain types of operations in
+certain OpenStack services, and are not interchangeable.
+
+Unscoped tokens
+~~~~~~~~~~~~~~~
+
+An unscoped token contains neither a service catalog, any roles, a project
+scope, nor a domain scope. Their primary use case is simply to prove your
+identity to keystone at a later time (usually to generate scoped tokens),
+without repeatedly presenting your original credentials.
+
+The following conditions must be met to receive an unscoped token:
+
+* You must not specify an authorization scope in your authentication request
+  (for example, on the command line with arguments such as
+  ``--os-project-name`` or ``--os-domain-id``),
+
+* Your identity must not have a "default project" associated with it that you
+  also have role assignments, and thus authorization, upon.
+
+Project-scoped tokens
+~~~~~~~~~~~~~~~~~~~~~
+
+Project-scoped tokens express your authorization to operate in a specific
+tenancy of the cloud and are useful to authenticate yourself when working with
+most other services.
+
+They contain a service catalog, a set of roles, and details of the project upon
+which you have authorization.
+
+Domain-scoped tokens
+~~~~~~~~~~~~~~~~~~~~
+
+Domain-scoped tokens have limited use cases in OpenStack. They express your
+authorization to operate a domain-level, above that of the user and projects
+contained therein (typically as a domain-level administrator).  Depending on
+Keystone's configuration, they are useful for working with a single domain in
+Keystone.
+
+They contain a limited service catalog (only those services which do not
+explicitly require per-project endpoints), a set of roles, and details of the
+project upon which you have authorization.
+
+They can also be used to work with domain-level concerns in other services,
+such as to configure domain-wide quotas that apply to all users or projects in
+a specific domain.
+
+System-scoped tokens
+~~~~~~~~~~~~~~~~~~~~
+
+There are APIs across OpenStack that fit nicely within the concept of a project
+or domain, but there are also APIs that affect the entire deployment system
+(e.g. modifying endpoints, service management, or listing information about
+hypervisors). These operations require the use of a system-scoped token, which
+represents the role assignments a user has to operate on the deployment as a
+whole.
+
+Token providers
+---------------
+
+The token type issued by keystone is configurable through the
+``/etc/keystone/keystone.conf`` file. Currently, the only supported token
+provider is ``fernet``.
+
+Fernet tokens
+~~~~~~~~~~~~~
+
+The fernet token format was introduced in the OpenStack Kilo release and now
+is the default token provider in Keystone. Unlike the other token types
+mentioned in this document, fernet tokens do not need to be persisted in a back
+end. ``AES256`` encryption is used to protect the information stored in the
+token and integrity is verified with a ``SHA256 HMAC`` signature. Only the
+Identity service should have access to the keys used to encrypt and decrypt
+fernet tokens. Like UUID tokens, fernet tokens must be passed back to the
+Identity service in order to validate them. For more information on the fernet
+token type, see the :doc:`fernet-token-faq`.
+
+.. support_matrix:: token-support-matrix.ini

doc/source/admin/tokens.rst

@@ -1,96 +1,12 @@
-===============
-Keystone tokens
-===============
+=========================
+All about keystone tokens
+=========================
 
-Tokens are used to authenticate and authorize your interactions with the
-various OpenStack APIs. Tokens come in many scopes, representing various
-authorization and sources of identity.
+Everything you need to know about keystone tokens.
 
-Authorization scopes
---------------------
+.. toctree::
+   :maxdepth: 2
 
-Tokens are used to relay information about your user's role assignments. It's
-not uncommon for a user to have multiple role assignments, sometimes spanning
-projects, domains, or the entire system. These are referred to as authorization
-scopes, where a token has a single scope of operation. For example, a token
-scoped to a project can't be reused to do something else in a different
-project.
-
-Each level of authorization scope is useful for certain types of operations in
-certain OpenStack services, and are not interchangeable.
-
-Unscoped tokens
-~~~~~~~~~~~~~~~
-
-An unscoped token contains neither a service catalog, any roles, a project
-scope, nor a domain scope. Their primary use case is simply to prove your
-identity to keystone at a later time (usually to generate scoped tokens),
-without repeatedly presenting your original credentials.
-
-The following conditions must be met to receive an unscoped token:
-
-* You must not specify an authorization scope in your authentication request
-  (for example, on the command line with arguments such as
-  ``--os-project-name`` or ``--os-domain-id``),
-
-* Your identity must not have a "default project" associated with it that you
-  also have role assignments, and thus authorization, upon.
-
-Project-scoped tokens
-~~~~~~~~~~~~~~~~~~~~~
-
-Project-scoped tokens express your authorization to operate in a specific
-tenancy of the cloud and are useful to authenticate yourself when working with
-most other services.
-
-They contain a service catalog, a set of roles, and details of the project upon
-which you have authorization.
-
-Domain-scoped tokens
-~~~~~~~~~~~~~~~~~~~~
-
-Domain-scoped tokens have limited use cases in OpenStack. They express your
-authorization to operate a domain-level, above that of the user and projects
-contained therein (typically as a domain-level administrator).  Depending on
-Keystone's configuration, they are useful for working with a single domain in
-Keystone.
-
-They contain a limited service catalog (only those services which do not
-explicitly require per-project endpoints), a set of roles, and details of the
-project upon which you have authorization.
-
-They can also be used to work with domain-level concerns in other services,
-such as to configure domain-wide quotas that apply to all users or projects in
-a specific domain.
-
-System-scoped tokens
-~~~~~~~~~~~~~~~~~~~~
-
-There are APIs across OpenStack that fit nicely within the concept of a project
-or domain, but there are also APIs that affect the entire deployment system
-(e.g. modifying endpoints, service management, or listing information about
-hypervisors). These operations require the use of a system-scoped token, which
-represents the role assignments a user has to operate on the deployment as a
-whole.
-
-Token providers
----------------
-
-The token type issued by keystone is configurable through the
-``/etc/keystone/keystone.conf`` file. Currently, the only supported token
-provider is ``fernet``.
-
-Fernet tokens
-~~~~~~~~~~~~~
-
-The fernet token format was introduced in the OpenStack Kilo release and now
-is the default token provider in Keystone. Unlike the other token types
-mentioned in this document, fernet tokens do not need to be persisted in a back
-end. ``AES256`` encryption is used to protect the information stored in the
-token and integrity is verified with a ``SHA256 HMAC`` signature. Only the
-Identity service should have access to the keys used to encrypt and decrypt
-fernet tokens. Like UUID tokens, fernet tokens must be passed back to the
-Identity service in order to validate them. For more information on the fernet
-token type, see the :doc:`fernet-token-faq`.
-
-.. support_matrix:: token-support-matrix.ini
+   tokens-overview
+   fernet-token-faq
+   token-provider

doc/source/admin/troubleshoot.rst

@@ -1,4 +1,3 @@
-=================================
 Troubleshoot the Identity service
 =================================
 

doc/source/admin/url-safe-naming.rst

@@ -1,4 +1,3 @@
-=======================================
 URL safe naming of projects and domains
 =======================================
 

doc/source/index.rst

@@ -99,7 +99,7 @@ Administrator Guides
 ~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     admin/index.rst