From 4b108fa087826a6b4cd5dc4b00bcc179acec92d6 Mon Sep 17 00:00:00 2001 From: Michael McCune Date: Fri, 5 Sep 2014 17:27:42 -0400 Subject: [PATCH] Adding documentation for proxy domain usage Changes * creating an advanced configuration guide * adding a link for the advanced config guide to index * changing the notification config heading to subsection * adding labels to diskimagebuilder and hadoop-swift documents Partial-Implements: blueprint edp-swift-trust-authentication Change-Id: Ie3a3cf0b470ac67670251a5ccd2c3689e338ed1c --- doc/source/index.rst | 1 + .../userdoc/advanced.configuration.guide.rst | 69 +++++++++++++++++++ doc/source/userdoc/configuration.guide.rst | 2 +- doc/source/userdoc/diskimagebuilder.rst | 2 + doc/source/userdoc/hadoop-swift.rst | 2 + 5 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 doc/source/userdoc/advanced.configuration.guide.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 1ae88a44..2d61e20c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -26,6 +26,7 @@ User guide userdoc/installation.guide userdoc/configuration.guide + userdoc/advanced.configuration.guide horizon/installation.guide userdoc/upgrade.guide diff --git a/doc/source/userdoc/advanced.configuration.guide.rst b/doc/source/userdoc/advanced.configuration.guide.rst new file mode 100644 index 00000000..f3da974a --- /dev/null +++ b/doc/source/userdoc/advanced.configuration.guide.rst @@ -0,0 +1,69 @@ +Sahara Advanced Configuration Guide +=================================== + +This guide addresses specific aspects of Sahara configuration that pertain to +advanced usage. It is divided into sections about various features that can be +utilized, and their related configurations. + +Domain usage for Swift proxy users +---------------------------------- + +To improve security for Sahara clusters accessing Swift objects, Sahara can be +configured to use proxy users and delegated trusts for access. This behavior +has been implemented to reduce the need for storing and distributing user +credentials. + +The use of proxy users involves creating a domain in Keystone that will be +designated as the home for any proxy users created. These created users will +only exist for as long as a job execution runs. The domain created for the +proxy users must have an identity backend that allows Sahara's admin user to +create new user accounts. This new domain should contain no roles, to limit +the potential access of a proxy user. + +Once the domain has been created Sahara must be configured to use it by adding +the domain name and any potential roles that must be used for Swift access in +the sahara.conf file. With the domain enabled in Sahara, users will no longer +be required to enter credentials with their Swift-backed Data Sources and Job +Binaries. + +Detailed instructions +^^^^^^^^^^^^^^^^^^^^^ + +First a domain must be created in Keystone to hold proxy users created by +Sahara. This domain must have an identity backend that allows for Sahara to +create new users. The default SQL engine is sufficient but if your Keystone +identity is backed by LDAP or similar then domain specific configurations +should be used to ensure Sahara's access. See the `Keystone documentation`_ +for more information. + +.. _Keystone documentation: http://docs.openstack.org/developer/keystone/configuration.html#domain-specific-drivers + +With the domain created Sahara's configuration file should be updated to +include the new domain name and any potential roles that will be needed. For +this example let's assume that the name of the proxy domain is +``sahara_proxy`` and the roles needed by proxy users will be ``Member`` and +``SwiftUser``. + +.. sourcecode:: cfg + + [DEFAULT] + use_domain_for_proxy_users=True + proxy_user_domain_name=sahara_proxy + proxy_user_role_names=Member,SwiftUser + +.. + +A note on the use of roles. In the context of the proxy user, any roles +specified here are roles intended to be delegated to the proxy user from the +user with access to the Swift object store. More specifically, any roles that +are required for Swift access by the project owning the object store must be +delegated to the proxy user for Swift authentication to be successful. + +Finally, the stack administrator must ensure that images registered with +Sahara have the latest version of the Hadoop Swift filesystem plugin +installed. The sources for this plugin can be found in the +`Sahara extra repository`_. For more information on images or Swift +integration see the Sahara documentation sections +:ref:`diskimage-builder-label` and :ref:`swift-integration-label`. + +.. _Sahara extra repository: http://github.com/openstack/sahara-extra diff --git a/doc/source/userdoc/configuration.guide.rst b/doc/source/userdoc/configuration.guide.rst index b4a4eadb..35d4b8b5 100644 --- a/doc/source/userdoc/configuration.guide.rst +++ b/doc/source/userdoc/configuration.guide.rst @@ -52,7 +52,7 @@ to write logs of INFO level and above. If ``debug`` is set to true, Sahara will write all the logs, including the DEBUG ones. Sahara notifications configuration -================================== +---------------------------------- Sahara can send notifications to Ceilometer, if it's enabled. If you want to enable notifications you should switch to ``[DEFAULT]`` diff --git a/doc/source/userdoc/diskimagebuilder.rst b/doc/source/userdoc/diskimagebuilder.rst index 8e301a93..37364713 100644 --- a/doc/source/userdoc/diskimagebuilder.rst +++ b/doc/source/userdoc/diskimagebuilder.rst @@ -1,3 +1,5 @@ +.. _diskimage-builder-label: + Building Images for Vanilla Plugin ================================== diff --git a/doc/source/userdoc/hadoop-swift.rst b/doc/source/userdoc/hadoop-swift.rst index 62840f48..7d12221f 100644 --- a/doc/source/userdoc/hadoop-swift.rst +++ b/doc/source/userdoc/hadoop-swift.rst @@ -1,3 +1,5 @@ +.. _swift-integration-label: + Swift Integration ================= Hadoop and Swift integration is the essential continuation of Hadoop&OpenStack