Update keystone documentation

First, including rst files is inconvenient and does not play well
with references (ends up in duplicates). Make user/keystone a proper
separate document.

Second, address various factual errors in both keystone documents.

Change-Id: I5d54c0727c428956424deb7998e86ad3e802bdf6

doc/source/install/keystone.rst

@@ -1,13 +1,6 @@
 Installation with Keystone
 ==========================
 
-.. NOTE:: Use of keystone with bifrost is a very new feature and should
-   be considered an advanced topic. Please feel free to reach out to the
-   bifrost contributors and the ironic community as a whole in the project's
-   `IRC`_ channel.
-
-.. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC
-
 Bifrost can now install and make use of keystone. In order to enable
 this as part of the installation, the ``enable_keystone`` variable
 must be set to ``true``, either in ``playbooks/inventory/group_vars/target``
@@ -51,11 +44,11 @@ Ideally, when setting new defaults, they should be set in the
 Creation of clouds.yaml
 -----------------------
 
-By default, during bifrost installation, when keystone is enabled,
-a file will be written to the user's home directory that is executing
-the installation.  That file can be located at
-``~/.config/openstack/clouds.yaml``. The cloud that is written
-to that file is named ``bifrost``.
+By default, during bifrost installation, a file will be written to the user's
+home directory that is executing the installation. That file can be located at
+``~/.config/openstack/clouds.yaml``. The clouds that are written
+to that file are named ``bifrost`` (for regular users) and ``bifrost-admin``
+(for administrators).
 
 Creation of openrc
 ------------------
@@ -63,6 +56,7 @@ Creation of openrc
 Also by default, after bifrost installation and again, when keystone
 is enabled, a file will be written to the user's home directory that
 you can use to set the appropriate environment variables in your
-current shell to be able to use OpenStack utilities:
+current shell to be able to use OpenStack utilities::
 
-    . ~/openrc bifrost && openstack baremetal driver list
+    . ~/openrc bifrost
+    openstack baremetal driver list

doc/source/user/howto.rst

@@ -290,6 +290,5 @@ as a space-separated list of elements. This defaults to an empty string.
 
 Use Bifrost with Keystone
 =========================
-.. include:: keystone.rst
-
 
+Content moved, see :doc:`keystone`.

doc/source/user/index.rst

@@ -10,4 +10,4 @@ this documentation serves as a blend of both Admin and User documentation.
 
    howto
    troubleshooting
-
+   keystone

doc/source/user/keystone.rst

@@ -1,15 +1,13 @@
-.. _keystone:
-
-.. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC
-
-Bifrost execution with Keystone
-===============================
+Using Keystone
+==============
 
 Ultimately, as bifrost was designed for relatively short-lived
 installations to facilitate rapid hardware deployment, the default
-operating mode is referred to as ``noauth`` mode. With that,
-in order to leverage keystone authentication for the roles,
-one of the following steps need to take place.
+operating mode is referred to as ``noauth`` mode. In order to leverage Keystone
+authentication for the roles, Bifrost reads configuration from ``clouds.yaml``.
+If ``clouds.yaml`` has not been generated through the
+``bifrost-keystone-client-config`` role, one of the following steps need
+to take place:
 
 #. Update the role defaults for each role you plan to make use.
    This may not make much sense  for most users, unless they are
@@ -17,13 +15,13 @@ one of the following steps need to take place.
 #. Invoke ansible-playbook with variables being set to override
    the default behavior. Example::
 
-       -e noauth_mode=false -e cloud_name=bifrost
+       -e enable_keystone=true -e noauth_mode=false -e cloud_name=bifrost
 
 #. Set the global defaults for tagret
    (``master/playbooks/inventory/group_vars/target``).
 
-OpenStack Client use with bifrost installed Keystone
-----------------------------------------------------
+OpenStack Client usage
+----------------------
 
 A user wishing to invoke OSC commands against the bifrost
 installation, should set the ``OS_CLOUD`` environment variable.
@@ -33,6 +31,11 @@ the OSC command to list all baremetal nodes::
     export OS_CLOUD=bifrost
     openstack baremetal node list
 
+For administration actions, use the ``bifrost-admin`` cloud::
+
+    export OS_CLOUD=bifrost-admin
+    openstack endpoint list
+
 Keystone roles
 --------------
 
@@ -44,20 +47,14 @@ These roles are ``baremetal_admin`` and ``baremetal_observer``
 and a user can learn more about the roles from the ironic `install
 guide`_.
 
-.. _`install guide`: https://docs.openstack.org/project-install-guide/baremetal/draft/configure-integration.html#configure-the-identity-service-for-the-bare-metal-service
+.. _`install guide`: https://docs.openstack.org/ironic/latest/install/configure-identity.html
 
-Individual playbook use with os-client-config
-=============================================
+Individual playbook use
+-----------------------
 
-The OpenStack Ansible modules utilize os-client-config to obtain
-authentication details to connect to determine details.
-
-If ``noauth_mode`` is explicitly disabled, the bifrost roles that
+The OpenStack Ansible modules utilize ``clouds.yaml`` file to obtain
+authentication details to connect to determine details. The bifrost roles that
 speak with Ironic for actions such as enrollment of nodes and
 deployment, automatically attempt to collect authentication
-data from os-client-config. Largely these details are governed
-as environment variables.
-
-That being said, os-client-config supports the concept of clouds
-and an a user can explicitly select the cloud they wish to deploy
-to via the ``cloud_name`` parameter.
+data from ``clouds.yaml``. A user can explicitly select the cloud they wish
+to deploy to via the ``cloud_name`` parameter.