From ee5fb6911b3ca3033dbed4bdcab3c0cdcda5850d Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 27 Aug 2020 11:51:22 +0200 Subject: [PATCH] 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 | 22 ++++++--------- doc/source/user/howto.rst | 3 +-- doc/source/user/index.rst | 2 +- doc/source/user/keystone.rst | 47 +++++++++++++++------------------ 4 files changed, 32 insertions(+), 42 deletions(-) diff --git a/doc/source/install/keystone.rst b/doc/source/install/keystone.rst index baa8c7e3d..1f9981bbe 100644 --- a/doc/source/install/keystone.rst +++ b/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 diff --git a/doc/source/user/howto.rst b/doc/source/user/howto.rst index 77501b521..5aa52a103 100644 --- a/doc/source/user/howto.rst +++ b/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`. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 0fed296ab..da95fcff0 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -10,4 +10,4 @@ this documentation serves as a blend of both Admin and User documentation. howto troubleshooting - + keystone diff --git a/doc/source/user/keystone.rst b/doc/source/user/keystone.rst index 4a530c4fa..4ca414d36 100644 --- a/doc/source/user/keystone.rst +++ b/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.