openstack/bifrost
Code Issues Proposed changes

Update keystone documentation

Browse Source 
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
This commit is contained in:
Dmitry Tantsur 2020-08-27 11:51:22 +02:00
parent 114c21043c
commit ee5fb6911b
4 changed files with 32 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/source/install/keystone.rst
View File

@ -1,13 +1,6 @@
Installation with Keystone 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 Bifrost can now install and make use of keystone. In order to enable
this as part of the installation, the ``enable_keystone`` variable this as part of the installation, the ``enable_keystone`` variable
must be set to ``true``, either in ``playbooks/inventory/group_vars/target`` 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 Creation of clouds.yaml
----------------------- -----------------------
By default, during bifrost installation, when keystone is enabled, By default, during bifrost installation, a file will be written to the user's
a file will be written to the user's home directory that is executing home directory that is executing the installation. That file can be located at
the installation. That file can be located at ``~/.config/openstack/clouds.yaml``. The clouds that are written
``~/.config/openstack/clouds.yaml``. The cloud that is written to that file are named ``bifrost`` (for regular users) and ``bifrost-admin``
to that file is named ``bifrost``. (for administrators).
Creation of openrc Creation of openrc
------------------ ------------------
@ -63,6 +56,7 @@ Creation of openrc
Also by default, after bifrost installation and again, when keystone Also by default, after bifrost installation and again, when keystone
is enabled, a file will be written to the user's home directory that 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 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

3
doc/source/user/howto.rst
View File

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

2
doc/source/user/index.rst
View File

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

47
doc/source/user/keystone.rst
View File

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