Add initial keystone use documentation

Using keystone is a bit of an advance topic, but documentation
is required to allow users to hopefully grasp the essentials of
what is required.

Change-Id: I25fd57f9acf07420384f021d17a43cf73412a965
This commit is contained in:
Julia Kreger 2016-10-11 14:42:07 +00:00 committed by Chris Krelle
parent 69af537eb9
commit 2cf5ce5252

View File

@ -0,0 +1,110 @@
*********************
Bifrost 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
##########################
Installation with Keystone
##########################
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/localhost`` or on the
command line during installation. Example::
ansible-playbook -vvvv -i inventory/localhost install.yaml -e enable_keystone=true
However, prior to installation, overriding credentials should be set
in order to customize the deployment to meet your needs. See::
playbooks/roles/bifrost-ironic-install/defaults/main.yml
playbooks/roles/bifrost-keystone-install/defaults/main.yml
Using an existing Keystone
--------------------------
If you choose to install bifrost using an existing keystone, this
should be possible, however it has not been tested. In this case you
will need to set the appropriate defaults, via
``playbooks/roles/bifrost-ironic-install/defaults/main.yml``
which would be a good source for the role level defaults.
Ideally, when setting new defaults, they should be set in the
``playbooks/inventory/group_vars/localhost`` file.
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``.
Use of bifrost with Keystone
============================
Ultimately, as bifrost was designed for relatively short-lived
installations for 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.
#. Update the role defaults for each role you plan to make use.
This may not make much sense for most users, unless they are
carrying such changes as downstream debt.
#. Invoke ansible-playbook with variables being set to override
the default behavior. Example::
-e noauth_mode=false -e cloud_name=bifrost
#. Set the global defaults for localhost
(``master/playbooks/inventory/group_vars/localhost``).
OpenStack Client
----------------
A user wishing to invoke OSC commands against the bifrost
installation, should set the ``OS_CLOUD`` environment variable.
An example of setting the environment variable and then executing
the OSC command to list all baremetal nodes::
export OS_CLOUD=bifrost
openstack baremetal node list
Keystone roles
--------------
Ironic, which is the underlying OpenStack component bifrost
helps a user leverage, supports two different roles in keystone
that helps govern the rights a user has in keystone.
These roles are ``baremetal_admin`` and ``baremetal_observer``
and a user can learn more about the roles from the ironic `install
guide`_.
.. _`install guide`: http://docs.openstack.org/project-install-guide/baremetal/draft/configure-integration.html#configure-the-identity-service-for-the-bare-metal-service
##############################
Use of playbooks with Keystone
##############################
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
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.