document the bootstrapping process

create docs on how to configure keystone with the new
keystone-manage bootstrap option.

implements bp: bootstrap

Change-Id: I4c7520cc68aadd49179e40e77b2d5058125edf00

doc/source/configuringservices.rst

@@ -38,8 +38,60 @@ The middleware will pass those data down to the service as headers. More
 details on the architecture of that setup is described in the
 `authentication middleware documentation`_.
 
-Setting up credentials
-======================
+Setting up credentials with ``keystone-manage bootstrap``
+=========================================================
+
+Setting up projects, users, and roles
+-------------------------------------
+
+The ``keystone-manage bootstrap`` command will create a user, project and role,
+and will assign the newly created role to the newly created user on the newly
+created project. By default, the names of these new resources will be called
+``admin``.
+
+The defaults may be overridden by calling ``--bootstrap-username``,
+``--bootstrap-project-name`` and ``--bootstrap-role-name``. Each of these have
+an environment variable equivalent: ``OS_BOOTSTRAP_USERNAME``,
+``OS_BOOTSTRAP_PROJECT_NAME`` and ``OS_BOOTSTRAP_ROLE_NAME``.
+
+A user password must also be supplied. This can be passed in as either
+``--bootstrap-password``, or set as an environment variable using
+``OS_BOOTSTRAP_PASSWORD``.
+
+Minimally, keystone can be bootstrapped with:
+
+.. code-block:: bash
+
+    $ keystone-manage bootstrap --bootstrap-password s3cr3t
+
+This will create an ``admin`` user with the ``admin`` role on the ``admin``
+project. The user will have the password specified in the command. Note that
+both the user and the project will be created in the ``default`` domain.
+
+To retrieve a token using these new values, a user can use OpenStackClient CLI:
+
+.. code-block:: bash
+
+    $ openstack token issue --os-username admin --os-project-name admin \
+        --os-user-domain-id default --os-project-domain-id default \
+        --os-identity-api-version 3 --os-auth-url http://localhost:5000/v3 \
+        --os-password s3cr3t
+
+With the newly returned token, a user may perform actions to create services
+and endpoints.
+
+.. code-block:: bash
+
+    $ openstack service create identity --name keystone --os-token $token_id
+        --os-url http://localhost:5000/v3
+
+Using this technique, deployers will be able to authenticate as the ``admin``
+user and configure endpoints and services; never having to use or configure
+the ``admin_token`` (described below).
+
+
+Setting up credentials with Admin Token
+=======================================
 
 Admin Token
 -----------

doc/source/man/keystone-manage.rst

@@ -40,6 +40,7 @@ Invoking ``keystone-manage`` by itself will give you some usage information.
 
 Available commands:
 
+* ``bootstrap``: Perform the basic bootstrap process.
 * ``db_sync``: Sync the database.
 * ``db_version``: Print the current migration version of the database.
 * ``domain_config_upload``: Upload domain configuration file.