openstack
/
openstack-ansible
Code Issues Proposed changes

DOCS: Configuration section - cleanup 

As per discussion in the OSA docs summit session, clean up
of installation guide. This fixes typos, minor RST mark up
changes, and passive voice.

This patch also merges a some of the sections into the larger
chapter. This is in an effort to remove multiple smaller
files.

This patch is the first of many to avoid major conflicts.

Change-Id: I38daa515ba47fde7719cd0bd3e0e40c2cd0f39f1
This commit is contained in:
Alexandra 2016-05-11 17:34:43 +01:00 committed by Jesse Pretorius (odyssey4me)
parent a4b513edd1
commit 71554ca7cf
16 changed files with 579 additions and 549 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/source/install-guide/configure-ceph.rst
View File

@ -1,11 +1,11 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Configuring the Ceph client (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
======================================
Ceph is a massively scalable, open source, distributed storage system.
These links provide more details around how to use Ceph with OpenStack:
These links provide details on how to use Ceph with OpenStack:
* `Ceph Block Devices and OpenStack`_
* `Ceph - The De Facto Storage Backend for OpenStack`_ *(Hong Kong Summit
@ -19,30 +19,32 @@ These links provide more details around how to use Ceph with OpenStack:
.. _OpenStack Config Reference - Ceph RADOS Block Device (RBD): http://docs.openstack.org/liberty/config-reference/content/ceph-rados.html
.. _OpenStack-Ansible and Ceph Working Example: https://www.openstackfaq.com/openstack-ansible-ceph/
Configuring Ceph storage servers is outside the scope of this documentation.
.. note::
Configuring Ceph storage servers is outside the scope of this documentation.
Authentication
--------------
~~~~~~~~~~~~~~
The ``cephx`` authentication method is strongly recommended in the `Ceph
config reference`_ and OpenStack-Ansible enables ``cephx`` by default for
the Ceph client. Deployers may choose to override this setting by using the
We recommend the ``cephx`` authentication method in the `Ceph
config reference`_. OpenStack-Ansible enables ``cephx`` by default for
the Ceph client. You can choose to override this setting by using the
``cephx`` Ansible variable:
.. code-block:: yaml
cephx: False
Ceph **must** be deployed on a trusted network if ``cephx`` is disabled.
Deploy Ceph on a trusted network if disabling ``cephx``.
.. _Ceph config reference: http://docs.ceph.com/docs/master/rados/configuration/auth-config-ref/
Configuration file overrides
----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack-Ansible provides the ``ceph_conf_file`` variable which allows
deployers to specify configuration file options to override the default
Ceph configuration.
OpenStack-Ansible provides the ``ceph_conf_file`` variable. This allows
you to specify configuration file options to override the default
Ceph configuration:
.. code-block:: console
@ -57,7 +59,7 @@ Ceph configuration.
The following minimal example configuration sets nova and glance
to use ceph pools: ``ephemeral-vms`` and ``images`` respectively.
The example uses cephx authentication, and requires existing ``glance`` and
The example uses ``cephx`` authentication, and requires existing ``glance`` and
``cinder`` accounts for ``images`` and ``ephemeral-vms`` pools.
.. code-block:: console
@ -65,9 +67,8 @@ The example uses cephx authentication, and requires existing ``glance`` and
glance_default_store: rbd
nova_libvirt_images_rbd_pool: ephemeral-vms
Monitors
--------
~~~~~~~~
The `Ceph Monitor`_ maintains a master copy of the cluster map.
OpenStack-Ansible provides the ``ceph_mons`` variable and expects a list of

19
doc/source/install-guide/configure-configurationintegrity.rst
View File

@ -1,28 +1,29 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Checking the integrity of your configuration files
--------------------------------------------------
==================================================
Here are a few steps to execute before running any playbook:
Execute the following steps before running any playbook:
#. Make sure all the files edited in ``/etc/`` are ansible
#. Ensure all files edited in ``/etc/`` are Ansible
YAML compliant. Guidelines can be found here:
`<http://docs.ansible.com/ansible/YAMLSyntax.html>`_
#. Check the integrity of your yaml files using a yaml linter.
#. Check the integrity of your YAML files:
.. note:: Here is an online linter: `<http://www.yamllint.com/>`_
#. Run your command with syntax-check, for example,
in the playbooks directory:
#. Run your command with ``syntax-check``:
.. code-block:: shell-session
# openstack-ansible setup-infrastructure.yml --syntax-check
#. Recheck that all indentation seems correct: the syntax of the
configuration files can be correct while not being meaningful
for openstack-ansible.
#. Recheck that all indentation is correct.
.. note::
The syntax of the configuration files can be correct
while not being meaningful for OpenStack-Ansible.
--------------

24
doc/source/install-guide/configure-federation-idp-adfs.rst
View File

@ -1,7 +1,7 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Configure Active Directory Federation Services (ADFS) 3.0 as an identity provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuring Active Directory Federation Services (ADFS) 3.0 as an identity provider
===================================================================================
To install ADFS:
@ -9,10 +9,10 @@ To install ADFS:
* `ADFS installation procedure from Microsoft Technet <https://technet.microsoft.com/en-us/library/dn303423>`_
Configuring ADFS
----------------
~~~~~~~~~~~~~~~~
#. The ADFS Server must already trust the service provider's (SP) keystone
certificate. It is recommended to have the ADFS CA (or a
#. Ensure the ADFS Server trusts the service provider's (SP) keystone
certificate. We recommend to have the ADFS CA (or a
public CA) sign a certificate request for the keystone service.
#. In the ADFS Management Console, choose ``Add Relying Party Trust``.
#. Select ``Import data about the relying party published online or on a
@ -20,8 +20,9 @@ Configuring ADFS
for example, ``https://<SP_IP_ADDRESS or DNS_NAME>:5000/Shibboleth.sso/Metadata``)
.. note::
ADFS may give a warning message that some of the content gathered from metadata
was skipped because is not supported by ADFS.
ADFS may give a warning message. The message states that ADFS skipped
some of the content gathered from metadata because it is not supported by ADFS
#. Continuing the wizard, select ``Permit all users to access this
relying party``.
@ -32,10 +33,11 @@ Configuring ADFS
#. Click :guilabel:`OK` to apply the rule and finalize the setup.
References
----------
* http://blogs.technet.com/b/rmilne/archive/2014/04/28/how-to-install-adfs-2012-r2-for-office-365.aspx
* http://blog.kloud.com.au/2013/08/14/powershell-deployment-of-web-application-proxy-and-adfs-in-under-10-minutes/
* https://ethernuno.wordpress.com/2014/04/20/install-adds-on-windows-server-2012-r2-with-powershell/
~~~~~~~~~~
* `http://blogs.technet.com/b/rmilne/archive/2014/04/28/how-to-install-adfs-2012-r2-for-office-365.aspx`_
* `http://blog.kloud.com.au/2013/08/14/powershell-deployment-of-web-application-proxy-and-adfs-in-under-10-minutes/`_
* `https://ethernuno.wordpress.com/2014/04/20/install-adds-on-windows-server-2012-r2-with-powershell/`_
--------------

48
doc/source/install-guide/configure-federation-idp.rst
View File

@ -1,11 +1,13 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Configure Identity Service (keystone) as a federated identity provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configure Identity service (keystone) as a federated identity provider
======================================================================
The identity provider (IdP) configuration for Keystone must be provided in a
The Identity Provider (IdP) configuration for keystone provides a
dictionary attribute with the key ``keystone_idp``. The following is a
complete example::
complete example:
.. code::
keystone_idp:
certfile: "/etc/keystone/ssl/idp_signing_cert.pem"
@ -29,7 +31,7 @@ complete example::
contact_telephone: 555-55-5555
contact_type: technical
The following list is a reference of all the allowed settings:
The following list is a reference of allowed settings:
* ``certfile`` defines the location and filename of the SSL certificate that
the IdP uses to sign assertions. This file must be in a location that is
@ -39,37 +41,37 @@ The following list is a reference of all the allowed settings:
the IdP uses to sign assertions. This file must be in a location that is
accessible to the keystone system user.
* ``self_signed_cert_subject`` is the subject used in the SSL signing
certificate. It is important to note that the common name of the certificate
must match the hostname that is configured in the service provider(s) for
* ``self_signed_cert_subject`` is the subject in the SSL signing
certificate. The common name of the certificate
must match the hostname configuration in the service provider(s) for
this IdP.
* ``regen_cert`` should normally be set to ``False``. When set to ``True``,
the existing signing certificate will be replaced with a new one. This
* ``regen_cert`` by default is set to ``False``. When set to ``True``, the
next Ansible run replaces the existing signing certificate with a new one. This
setting is added as a convenience mechanism to renew a certificate when it
is close to its expiration date.
* ``idp_entity_id`` is the entity ID. The service providers will
use this as a unique identifier for each IdP. The recommended value for this
setting is ``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp``
* ``idp_entity_id`` is the entity ID. The service providers
use this as a unique identifier for each IdP. ``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp``
is the value we recommend for this setting.
* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. The
recommended value for this setting is
``<keystone-public-endpoint>/OS-FEDERATION/saml2/sso>``
* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP.
``<keystone-public-endpoint>/OS-FEDERATION/saml2/sso>`` is the value
we recommend for this setting.
* ``idp_metadata_path`` is the location and filename where the metadata for
this IdP will be cached. The keystone system user must have access to this
this IdP is cached. The keystone system user must have access to this
location.
* ``service_providers`` is a list of the known service providers that will be
using this keystone instance as identity provider. For each SP there are
three values that need to be provided: ``id`` is a unique identifier,
``auth_url`` is the authentication endpoint of the SP, and ``sp_url`` is the
endpoint where SAML2 assertions need to be posted.
* ``service_providers`` is a list of the known service providers (SP) that
use the keystone instance as identity provider. For each SP, provide
three values: ``id`` as a unique identifier,
``auth_url`` as the authentication endpoint of the SP, and ``sp_url``
endpoint for posting SAML2 assertions.
* ``organization_name``, ``organization_display_name``, ``organization_url``,
``contact_company``, ``contact_name``, ``contact_surname``,
``contact_email``, ``contact_telephone`` and ``contact_type`` are all
``contact_email``, ``contact_telephone`` and ``contact_type`` are
settings that describe the identity provider. These settings are all optional.
--------------

64
doc/source/install-guide/configure-federation-mapping.rst
View File

@ -1,7 +1,7 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Configure Identity Service (keystone) Domain-Project-Group-Role mappings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
========================================================================
The following is an example service provider (SP) mapping configuration
for an ADFS identity provider (IdP):
@ -16,23 +16,21 @@ for an ADFS identity provider (IdP):
Each IdP trusted by an SP must have the following configuration:
#. ``project``: The project which federated users will have access to.
If the project does not already exist then it is created in the
domain with the name specified by ``domain``.
#. ``project``: The project that federation users have access to.
If the project does not already exist, create it in the
domain with the name, ``domain``.
#. ``group``: The Identity (keystone) group to which the federated users
will belong. If the group does not already exist then it is created in
the domain with the name specified by ``domain``.
#. ``group``: The keystone group that federation users
belong. If the group does not already exist, create it in
the domain with the name, ``domain``.
#. ``role``: The role which federated users will assume in that project.
If the role does not already exist, it is created.
#. ``role``: The role that federation users use in that project.
Create the role if it does not already exist.
#. ``domain``: The domain in which the ``project`` lives, and in
which the role is assigned. If the domain does not already exist,
it will be created.
#. ``domain``: The domain where the ``project`` lives, and where
the you assign roles. Create the domain if it does not already exist.
With the above information, Ansible implements the equivalent of the
following OpenStack CLI commands:
Ansible implements the equivalent of the following OpenStack CLI commands:
.. code-block:: shell-session
@ -51,8 +49,8 @@ following OpenStack CLI commands:
# map the role to the project and user group in the domain
openstack role add --project fedproject --group fedgroup _member_
If the deployer wants to add more mappings, additional options can be added to
the list, for example:
To add more mappings, add options to the list.
For example:
.. code-block:: yaml
@ -66,20 +64,19 @@ the list, for example:
group: fedgroup2
role: _member_
Identity Service federation attribute mapping
---------------------------------------------
Identity service federation attribute mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Attribute mapping adds a set of rules to map federation attributes to keystone
users and/or groups. An IdP has exactly one mapping specified per
protocol.
users and groups. IdP specifies one mapping per protocol.
Mapping objects can be used multiple times by different combinations of
Use mapping objects multiple times by different combinations of
IdP and protocol.
The details of how the mapping engine works, the schema and various rule
The details of how the mapping engine works, the schema, and various rule
examples are in the `keystone developer documentation <http://docs.openstack.org/developer/keystone/mapping_combinations.html>`_.
Consider an example SP attribute mapping configuration for an ADFS IdP:
For example, SP attribute mapping configuration for an ADFS IdP:
.. code-block:: yaml
@ -102,13 +99,12 @@ Consider an example SP attribute mapping configuration for an ADFS IdP:
Each IdP for an SP needs to be set up with a mapping. This tells the SP how
to interpret the attributes provided to the SP from the IdP.
In this particular case the IdP is publishing the ``upn`` attribute. As this
is not in the standard Shibboleth attribute attribute map (see
``/etc/shibboleth/attribute-map.xml`` in the keystone containers), this IdP
has been configured with the extra mapping through the ``attributes``
dictionary.
In this example, the IdP publishes the ``upn`` attribute. As this
is not in the standard Shibboleth attribute map (see
``/etc/shibboleth/attribute-map.xml`` in the keystone containers), the configuration
of the IdP has extra mapping through the ``attributes`` dictionary.
The ``mapping`` dictionary is a yaml representation very similar to the
The ``mapping`` dictionary is a YAML representation similar to the
keystone mapping property which Ansible uploads. The above mapping
produces the following in keystone.
@ -155,11 +151,11 @@ produces the following in keystone.
}
]
The interpretation of the above mapping rule is that any federated user
authenticated by the IdP is mapped to an ``ephemeral`` (non-existant) user in
keystone. The user is a member of a group named ``fedgroup``, which in turn is
in a domain called ``Default``. The user's ID and Name (federation always uses
the same value for both properties) for all OpenStack services will be
The interpretation of the above mapping rule is that any federation user
authenticated by the IdP maps to an ``ephemeral`` (non-existant) user in
keystone. The user is a member of a group named ``fedgroup``. This is
in a domain called ``Default``. The user's ID and Name (federation uses
the same value for both properties) for all OpenStack services is
the value of ``upn``.

63
doc/source/install-guide/configure-federation-sp-overview.rst
View File

@ -1,49 +1,52 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Identity Service (keystone) service provider background
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=======================================================
In OpenStack-Ansible (OSA) the Identity Service (keystone) is set up to
use Apache with mod_wsgi. The additional configuration of
keystone as a federation service provider adds Apache mod_shib
In OpenStack-Ansible, the Identity Service (keystone) is set up to
use Apache with ``mod_wsgi``. The additional configuration of
keystone as a federation service provider adds Apache ``mod_shib``
and configures it to respond to specific locations requests
from a client.
.. note::
There are alternative methods of implementing
federation, but at this time only SAML2-based federation using
the Shibboleth SP is instrumented in OA.
When requests are sent to those locations, Apache hands off the
request to the ``shibd`` service. Only requests pertaining to
authentication are handed off.
request to the ``shibd`` service.
The ``shibd`` service configuration is primarily handled through
the following files in ``/etc/shibboleth/`` within the keystone
.. note::
Handing off happens only with requests pertaining to authentication.
Handle the ``shibd`` service configuration through
the following files in ``/etc/shibboleth/`` in the keystone
containers:
* ``sp-cert.pem``, ``sp-key.pem``: These files are generated on the
first keystone container and replicated to the other keystone
containers by the ``os-keystone-install.yml`` playbook. They are
used as signing credentials in communications between the SP
and the IdP.
* ``shibboleth2.xml``: This file's contents are written by the
``os-keystone-install.yml`` playbook based on the configuration
of the ``keystone_sp`` structured attribute in the
* ``sp-cert.pem``, ``sp-key.pem``: The ``os-keystone-install.yml`` playbook
uses these files generated on the first keystone container to replicate
them to the other keystone containers. The SP and the IdP use these files
as signing credentials in communications.
* ``shibboleth2.xml``: The ``os-keystone-install.yml`` playbook writes the
file's contents, basing on the structure of the configuration
of the ``keystone_sp`` attribute in the
``/etc/openstack_deploy/user_variables.yml`` file. It contains
the list of trusted IdP's, the entityID by which the SP will
be known and some other facilitating configuration.
* ``attribute-map.xml``: This file's contents are written by the
``os-keystone-install.yml`` playbook based on the configuration
of the ``keystone_sp`` structured attribute in the
the list of trusted IdP's, the entityID by which the SP is known,
and other facilitating configurations.
* ``attribute-map.xml``: The ``os-keystone-install.yml`` playbook writes
the file's contents, basing on the structure of the configuration
of the ``keystone_sp`` attribute in the
``/etc/openstack_deploy/user_variables.yml`` file. It contains
some default attribute mappings which will work for any basic
the default attribute mappings that work for any basic
Shibboleth-type IDP setup, but also contains any additional
attribute mappings which were set out in the ``keystone_sp``
structured attribute.
* ``shibd.logger``: This file is left alone by Ansible, but is useful
when troubleshooting issues with federated authentication or
when trying to discover what attributes published by an IdP
attribute mappings set out in the structure of the ``keystone_sp``
attribute.
* ``shibd.logger``: This file is left alone by Ansible. It is useful
when troubleshooting issues with federated authentication, or
when discovering what attributes published by an IdP
are not currently being understood by your SP's attribute map.
To enable debug logging, change ``log4j.rootCategory=INFO`` to
``log4j.rootCategory=DEBUG`` at the top of the file. The
@ -51,9 +54,9 @@ containers:
References
----------
* http://docs.openstack.org/developer/keystone/configure_federation.html
* http://docs.openstack.org/developer/keystone/extensions/shibboleth.html
* https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration
* `http://docs.openstack.org/developer/keystone/configure_federation.html`_
* `http://docs.openstack.org/developer/keystone/extensions/shibboleth.html`_
* `https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration`_
--------------

72
doc/source/install-guide/configure-federation-sp.rst
View File

@ -1,40 +1,35 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Configure Identity Service (keystone) as a federated service provider
---------------------------------------------------------------------
=====================================================================
The following settings must be set to configure a service provider (SP):
#. ``keystone_public_endpoint`` automatically set by default
to the public endpoint's URI. This ensures that
the redirections performed and token references all refer to the
public endpoint which is accessible to clients and the trusted
IDP.
#. ``keystone_public_endpoint`` is automatically set by default
to the public endpoint's URI. This performs redirections and
ensures token references refer to the public endpoint.
#. ``horizon_keystone_endpoint`` automatically set by default
#. ``horizon_keystone_endpoint`` is automatically set by default
to the public v3 API endpoint URL for keystone. Web-based single
sign-on for horizon requires the use of the keystone v3 API.
The value for this must use the same DNS name or IP address which
is registered in the SSL certificate used for the endpoint.
The value for this must use the same DNS name or IP address
registered in the SSL certificate used for the endpoint.
#. If ADFS is to be used as the IdP, the keystone endpoint is
**required** to have an HTTPS public endpoint. The endpoint may
either be provided by keystone itself, or by an SSL offloading
load balancer.
#. It is a requirement to have a HTTPS public endpoint for the
keystone endpoint if the IdP is ADFS.
Keystone or an SSL offloading load balancer provides the endpoint.
#. ``keystone_service_publicuri_proto`` must be set to https in order
to ensure that the public endpoint is registered with https in the
URL, to ensure that keystone publishes https in its references
and to ensure that Shibboleth is configured to know that it should
expect SSL URL's in the assertions (otherwise it will invalidate
#. Set ``keystone_service_publicuri_proto`` to https.
This ensures keystone publishes https in its references
and ensures that Shibboleth is configured to know that it
expects SSL URL's in the assertions (otherwise it will invalidate
the assertions).
#. ADFS **requires** that a trusted SP have a trusted certificate that
is not self-signed. This means that the certificate used for
keystone must either be signed by a public CA, or an enterprise CA.
#. ADFS requires that a trusted SP have a trusted certificate that
is not self-signed.
#. When using SSL for the keystone endpoint, the endpoint URI and the
certificate must match. For example, if the certificate does not have
#. Ensure the endpoint URI and the certificate match when using SSL for the
keystone endpoint. For example, if the certificate does not have
the IP address of the endpoint, then the endpoint must be published with
the appropriate name registered on the certificate. When
using a DNS name for the keystone endpoint, both
@ -42,7 +37,7 @@ The following settings must be set to configure a service provider (SP):
be set to use the DNS name.
#. ``horizon_endpoint_type`` must be set to ``publicURL`` to ensure that
Horizon makes use of the public endpoint for all its references and
horizon uses the public endpoint for all its references and
queries.
#. ``keystone_sp`` is a dictionary attribute which contains various
@ -84,23 +79,23 @@ The following settings must be set to configure a service provider (SP):
#. ``cert_duration_years`` designates the valid duration for the SP's
signing certificate (for example, ``/etc/shibboleth/sp-key.pem``).
#. ``trusted_dashboard_list`` designates the list of trusted URLs from which
keystone will accept redirects for Web Single-Sign. This
list should contain all URLs that horizon is presented on,
suffixed by ``/auth/websso/`` which is the path for horizon's WebSSO
#. ``trusted_dashboard_list`` designates the list of trusted URLs that
keystone accepts redirects for Web Single-Sign. This
list contains all URLs that horizon is presented on,
suffixed by ``/auth/websso/``. This is the path for horizon's WebSSO
component.
#. ``trusted_idp_list`` is a dictionary attribute containing the list
of settings which pertain to each trusted IdP for the SP.
#. ``trusted_idp_list.name`` is the name by which the IDP is known, is
configured in keystone and is listed in horizon's login selection.
#. ``trusted_idp_list.name`` is IDP's name. Configure this in
in keystone and list in horizon's login selection.
#. ``entity_ids`` is a list of reference entity IDs which specify where
the login request to the SP will be redirected to in order to
authenticate to the IdP.
#. ``entity_ids`` is a list of reference entity IDs. This specify's the
redirection of the login request to the SP when authenticating to
IdP.
#. ``metadata_uri`` is the location of the IdP's metadata which provides
#. ``metadata_uri`` is the location of the IdP's metadata. This provides
the SP with the signing key and all the IdP's supported endpoints.
#. ``metadata_file`` is the file name of the local cached version of
@ -109,12 +104,13 @@ The following settings must be set to configure a service provider (SP):
#. ``metadata_reload`` is the number of seconds between metadata
refresh polls.
#. ``federated_identities`` is a list of domain, project, group and users
which are to be mapped. See `Configure Identity Service (keystone) Domain-Project-Group-Role mappings <configure-federation-mapping.html>`_ for more information.
#. ``federated_identities`` is a mapping list of domain, project, group, and users.
See `Configure Identity Service (keystone) Domain-Project-Group-Role mappings <configure-federation-mapping.html>`_
for more information.
#. ``protocols`` is a list of protocols supported for the IdP and the set
of mappings and attributes for each protocol. Only the protocol with the
name ``saml2`` is supported at this time.
of mappings and attributes for each protocol. This only supports protocols
with the name ``saml2``.
#. ``mapping`` is the local to remote mapping configuration for federated
users. For more information, see `Configure Identity Service (keystone) Domain-Project-Group-Role mappings. <configure-federation-mapping.html>`_

162
doc/source/install-guide/configure-federation-use-case.rst
View File

@ -1,9 +1,9 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Identity Service to Identity Service federation example use-case
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
================================================================
This document describes the configuration steps necessary to reproduce the
The following is the configuration steps necessary to reproduce the
federation scenario described below:
* Federate Cloud 1 and Cloud 2.
@ -14,9 +14,11 @@ federation scenario described below:
* Assign User U to Group B, confirm scope to Role S in Project Y.
Keystone identity provider (IdP) configuration
----------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The configuration for the keystone IdP instance is as follows::
The following is the configuration for the keystone IdP instance:
.. code::
keystone_idp:
certfile: "/etc/keystone/ssl/idp_signing_cert.pem"
@ -31,21 +33,25 @@ The configuration for the keystone IdP instance is as follows::
auth_url: https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth
sp_url: https://cloud2.com:5000/Shibboleth.sso/SAML2/ECP
In the above example, only the last three lines are specific to a particular
In this example, the last three lines are specific to a particular
installation, as they reference the service provider cloud (referred to as
"Cloud 2" in the original scenario). In the example, it is assumed that this
"Cloud 2" in the original scenario). In the example, the
cloud is located at https://cloud2.com, and the unique ID for this cloud
is "cloud2".
Also note that in the ``auth_url`` there is a reference to the IdP cloud (or
"Cloud 1"), as known by the service provider (SP). The ID used for the IdP
cloud in this example is "cloud1".
.. note::
Keystone SP configuration
-------------------------
In the ``auth_url`` there is a reference to the IdP cloud (or
"Cloud 1"), as known by the service provider (SP). The ID used for the IdP
cloud in this example is "cloud1".
The configuration for the Keystone SP is more complex, as it needs to define
the remote-to-local user mappings. The complete configuration is as follows::
Keystone service provider (SP) configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The configuration for keystone SP needs to define the remote-to-local user mappings.
The following is the complete configuration:
.. code::
keystone_sp:
cert_duration_years: 5
@ -102,61 +108,62 @@ the remote-to-local user mappings. The complete configuration is as follows::
- name: openstack_project_domain
id: openstack_project_domain
The ``cert_duration_years`` is used for the self-signed certificate used by
Shibboleth. The ``trusted_dashboard_list`` is only necessary if Horizon SSO
login is going to be implemented. When given, it works as a security measure,
``cert_duration_years`` is for the self-signed certificate used by
Shibboleth. Only implement the ``trusted_dashboard_list`` if horizon SSO
login is necessary. When given, it works as a security measure,
as keystone will only redirect to these URLs.
The ``trusted_idp_list`` is where the IdPs known to the SP are configured. In
this example there is only one IdP, the "Cloud 1", which is configured with
the ID "cloud1", matching the reference in the IdP configuration shown in the
Configure the IdPs known to SP in ``trusted_idp_list``. In
this example there is only one IdP, the "Cloud 1". Configure "Cloud 1" with
the ID "cloud1". This matches the reference in the IdP configuration shown in the
previous section.
The ``entity_ids`` is given the unique URL that represents the "Cloud 1" IdP,
which for this example is assumed to be hosted at https://cloud1.com.
The ``entity_ids`` is given the unique URL that represents the "Cloud 1" IdP.
For this example, it is hosted at: https://cloud1.com.
The three metadata values that follow configure the access to the IdP
metadata. The ``metadata_file`` needs to be different for each IdP, as this is
a filename in the keystone containers of the SP cloud that will hold cached
The ``metadata_file`` needs to be different for each IdP. This is
a filename in the keystone containers of the SP cloud that holds cached
metadata for each registered IdP.
The ``federated_identities`` list defines the sets of identities that will be
used for federated users. In this example there are two sets, Project X/Role R
and Project Y/Role S. To keep things organized, a user group is created
for each set.
The ``federated_identities`` list defines the sets of identities in use
for federated users. In this example there are two sets, Project X/Role R
and Project Y/Role S. A user group is created for each set.
The ``protocols`` section is where the federation protocols are specified. At
this time the only supported protocol is ``saml2``.
The ``protocols`` section is where the federation protocols are specified.
The only supported protocol is ``saml2``.
The ``mapping`` dictionary is where the actual assignments of remote to local
The ``mapping`` dictionary is where the assignments of remote to local
users is defined. A keystone mapping is given a ``name`` and a set of
``rules`` that keystone applies to determine how to map a given user. Each
mapping rule has a ``remote`` and a ``local`` component.
The ``remote`` part of the mapping rule specifies the criteria for the remote
user, based on the attributes exposed by the IdP in the SAML2 assertion. The
user based on the attributes exposed by the IdP in the SAML2 assertion. The
use case for this scenario calls for mapping users in "Group A" and "Group B",
but the group or groups a user belongs to are not exported in the SAML2
assertion. To make the example work, the groups A and B in the use case have
been assumed to be projects, so there are projects A and B, which are exported
in the assertion under the ``openstack_project`` attribute. The two rules
defined above select the corresponding project using the ``any_one_of``
assertion. To make the example work, the groups A and B in the use case are
projects. Export projects A and B in the assertion under the ``openstack_project`` attribute.
The two rules above select the corresponding project using the ``any_one_of``
selector.
The ``local`` part of the mapping rule specifies how keystone should represent
the remote user in the local SP cloud. Since the two federated identities were
configured with their own user group, this part simply maps the user to the
corresponding group, which in turn will expose the correct domain, project and
role. Note that a user name is not specified, so keystone creates an
ephemeral user in the specified group.
The ``local`` part of the mapping rule specifies how keystone represents
the remote user in the local SP cloud. Configuring the two federated identities
with their own user group maps the user to the
corresponding group. This exposes the correct domain, project, and
role.
The final setting of the configuration defines the SAML2 ``attributes`` that
are exported by the IdP. For a keystone IdP these are the five attributes
shown above. The attributes given in this section are configured into the
Shibboleth service, making them available to use in the mappings.
.. note::
Keystone creates a ephemeral user in the specified group as
you cannot specify user names.
The IdP exports the final setting of the configuration defines the SAML2 ``attributes``.
For a keystone IdP, these are the five attributes
shown above. Configure the attributes above into the Shibboleth service. This
ensures they are available to use in the mappings.
Reviewing or modifying the configuration with the OpenStack client
------------------------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use OpenStack command line client to review or make modifications to an
existing federation configuration. The following commands can be used for
@ -165,7 +172,9 @@ the previous configuration.
Service providers on the identity provider
------------------------------------------
To see the list of known SPs::
To see the list of known SPs:
.. code::
$ openstack service provider list
+--------+---------+-------------+-----------------------------------------------------------------------------------------+
@ -174,7 +183,9 @@ To see the list of known SPs::
| cloud2 | True | None | https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth |
+--------+---------+-------------+-----------------------------------------------------------------------------------------+
To view the information for a specific SP::
To view the information for a specific SP:
.. code::
$ openstack service provider show cloud2
+--------------------+----------------------------------------------------------------------------------------------+
@ -188,8 +199,10 @@ To view the information for a specific SP::
| sp_url | http://cloud2.com:5000/Shibboleth.sso/SAML2/ECP |
+--------------------+----------------------------------------------------------------------------------------------+
To make modifications, the ``set`` command is used. Below are the available
options for this command::
To make modifications, use the ``set`` command. The following are the available
options for this command:
.. code::
$ openstack service provider set
usage: openstack service provider set [-h] [--auth-url <auth-url>]
@ -201,7 +214,9 @@ options for this command::
Identity providers on the service provider
------------------------------------------
To see the list of known IdPs::
To see the list of known IdPs:
.. code::
$ openstack identity provider list
+----------------+---------+-------------+
@ -210,7 +225,9 @@ To see the list of known IdPs::
| cloud1 | True | None |
+----------------+---------+-------------+
To view the information for a specific IdP::
To view the information for a specific IdP:
.. code::
$ openstack identity provider show keystone-idp
+-------------+--------------------------------------------------------+
@ -222,8 +239,10 @@ To view the information for a specific IdP::
| remote_ids | [u'http://cloud1.com:5000/v3/OS-FEDERATION/saml2/idp'] |
+-------------+--------------------------------------------------------+
To make modifications, the ``set`` command is used. Below are the available
options for this command::
To make modifications, use the ``set`` command. The following are the available
options for this command:
.. code::
$ openstack identity provider set
usage: openstack identity provider set [-h]
@ -234,9 +253,11 @@ options for this command::
Federated identities on the service provider
--------------------------------------------
The domain, project, role, group and user entities created for the purpose of
federation are regular keystone entities that can be viewed or modified with
the OpenStack command client. For example::
You can use the OpenStack commandline client to view or modify
the created domain, project, role, group, and user entities for the
purpose of federation as these are regular keystone entities. For example:
.. code::
$ openstack domain list
$ openstack project list
@ -244,14 +265,15 @@ the OpenStack command client. For example::
$ openstack group list
$ openstack user list
When using a domain other than the default, the ``--domain`` option must be
added to all the commands above except the first. The ``set`` option is used
to modify these entities.
Add the ``--domain`` option when using a domain other than the default.
Use the ``set`` option to modify these entities.
Federation mappings
-------------------
To view the list of mappings::
To view the list of mappings:
.. code::
$ openstack mapping list
+------------------+
@ -260,7 +282,9 @@ To view the list of mappings::
| cloud1-mapping |
+------------------+
To view a mapping in detail::
To view a mapping in detail:
..code::
$ openstack mapping show cloud1-mapping
+-------+--------------------------------------------------------------------------------------------------------------------------------------------------+
@ -273,8 +297,10 @@ To view a mapping in detail::
+-------+--------------------------------------------------------------------------------------------------------------------------------------------------+
To edit a mapping, use an auxiliary file. Save the JSON mapping shown above
and make the necessary modifications, then use the``set`` command to trigger
an update. For example::
and make the necessary modifications. Use the``set`` command to trigger
an update. For example:
.. code::
$ openstack mapping show cloud1-mapping -c rules -f value | python -m json.tool > rules.json
$ vi rules.json # <--- make any necessary changes
@ -283,8 +309,10 @@ an update. For example::
Federation protocols
--------------------
It is also possible to view or change the association between a federation
protocol and a mapping::
To view or change the association between a federation
protocol and a mapping, use the following command:
.. code::
$ openstack federation protocol list --identity-provider keystone-idp
+-------+----------------+

95
doc/source/install-guide/configure-federation-wrapper.rst
View File

@ -1,77 +1,92 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Using Identity Service to Identity Service federation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using Identity service to Identity service federation
=====================================================
In Identity Service (keystone) to Identity Service (keystone)
In Identity service (keystone) to Identity service (keystone)
federation (K2K) the identity provider (IdP) and service provider (SP)
keystone instances exchange information securely to enable a user on
the IdP cloud to access resources of the SP cloud.
This section applies only to federation between Identity Service IdP
and Identity Service SP. It does not apply to non-keystone IdP.
.. important::
This section applies only to federation between keystone IdP
and keystone SP. It does not apply to non-keystone IdP.
.. note::
For the Kilo release of OpenStack, K2K is only partially supported.
It is possible to perform a federated login using command line clients and
scripting, but Horizon does not support this functionality.
scripting. However, horizon does not support this functionality.
The K2K authentication flow involves the following steps:
#. The client logs in to the IdP with his credentials.
#. The client sends a request to the IdP to generate an assertion for a given
#. You log in to the IdP with your credentials.
#. You sends a request to the IdP to generate an assertion for a given
SP. An assertion is a cryptographically signed XML document that identifies
the user to the SP.
#. The client submits the assertion to the SP on the configured ``sp_url``
#. You submit the assertion to the SP on the configured ``sp_url``
endpoint. The Shibboleth service running on the SP receives the assertion
and verifies it. If it is valid, it starts a session with the client and
and verifies it. If it is valid, a session with the client starts and
returns the session ID in a cookie.
#. The client now connects to the SP on the configured ``auth_url`` endpoint,
#. You now connect to the SP on the configured ``auth_url`` endpoint,
providing the Shibboleth cookie with the session ID. The SP responds with
an unscoped token that the client can use to access the SP.
#. The client connects to the keystone service on the SP with the unscoped
token, and the desired domain and/or project, and receives a scoped token
an unscoped token that you use to access the SP.
#. You connect to the keystone service on the SP with the unscoped
token, and the desired domain and project, and receive a scoped token
and the service catalog.
#. The client, now in possession of a token, can make API requests to the
#. You, now in possession of a token, can make API requests to the
endpoints in the catalog.
Identity Service to Identity Service federation authentication wrapper
----------------------------------------------------------------------
Identity service to Identity service federation authentication wrapper
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unfortunately, many of the steps above involve manually sending API requests.
The infrastructure for the command line utilities to perform all these steps
for the user does not yet exist.
The following steps above involve manually sending API requests.
To simplify the task of obtaining access to a SP cloud, OpenStack-Ansible provides a script that wraps the above steps. The script is called ``federated-login.sh`` and is
used as follows::
.. note::
# ./scripts/federated-login.sh -p project [-d domain] sp_id
The infrastructure for the command line utilities that performs these steps
for the user does not exist.
Where ``project`` is the project in the SP cloud that the user wants to access,
``domain`` is the domain in which the project lives (the default domain is
used if this argument is not given) and ``sp_id`` is the unique ID of the SP,
as given in the IdP configuration.
To obtain access to a SP cloud, OpenStack-Ansible provides a script that wraps the
above steps. The script is called ``federated-login.sh`` and is
used as follows:
.. code::
# ./scripts/federated-login.sh -p project [-d domain] sp_id
* ``project`` is the project in the SP cloud that you want to access.
* ``domain`` is the domain in which the project lives (the default domain is
used if this argument is not given).
* ``sp_id`` is the unique ID of the SP. This is given in the IdP configuration.
The script outputs the results of all the steps in the authentication flow to
the console, and at the end prints the available endpoints from the catalog
the console. At the end, it prints the available endpoints from the catalog
and the scoped token provided by the SP.
The endpoints and token can be used with the openstack command line client as
follows::
Use the endpoints and token with the openstack command line client as follows:
# openstack --os-token=<token> --os-url=<service-endpoint> [options]
.. code::
or alternatively::
# openstack --os-token=<token> --os-url=<service-endpoint> [options]
# export OS_TOKEN=<token>
# export OS_URL=<service-endpoint>
# openstack [options]
Or, alternatively:
The user must select the appropriate endpoint for the desired
operation. For example, if the user wants to work with servers, the ``OS_URL``
argument must be set to the compute endpoint. At this time the openstack
client is unable to find endpoints in the service catalog when using a
federated login. This is likely to be supported in the near future.
.. code::
# export OS_TOKEN=<token>
# export OS_URL=<service-endpoint>
# openstack [options]
Ensure you select the appropriate endpoint for your operation.
For example, if you want to work with servers, the ``OS_URL``
argument must be set to the compute endpoint.
.. note::
At this time, the OpenStack client is unable to find endpoints in
the service catalog when using a federated login.
--------------

13
doc/source/install-guide/configure-federation.rst
View File

@ -1,7 +1,7 @@
`Home <index.html>`__ OpenStack-Ansible Installation Guide
Configuring Identity Service federation (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuring Identity service (keystone) federation (optional)
=============================================================
.. toctree::
@ -13,16 +13,17 @@ Configuring Identity Service federation (optional)
configure-federation-mapping.rst
configure-federation-use-case.rst
In Identity Service federation, the identity provider (IdP) and service
In keystone federation, the identity provider (IdP) and service
provider (SP) exchange information securely to enable a user on the IdP cloud
to access resources of the SP cloud.
.. note::
For the Kilo release of OpenStack, federation is only partially supported.
It is possible to perform a federated login using command line clients and
scripting, but Dashboard (horizon) does not support this functionality.
The following procedure describes how set up federation.
The following procedure describes how to set up federation.
#. `Configure Identity Service (keystone) service providers. <configure-federation-sp.html>`_
@ -38,8 +39,8 @@ The following procedure describes how set up federation.
#. `Run the authentication wrapper to use Identity Service to Identity Service federation. <configure-federation-wrapper.html>`_
For examples of how to set up Identity Service to Identity
Service federation, see the `Identity Service to Identity Service
For examples of how to set up keystone to keystone federation,
see the `Identity Service to Identity Service
federation example use-case. <configure-federation-use-case.html>`_
--------------

53
doc/source/install-guide/configure-network-services-fwaas.rst
View File

@ -1,53 +0,0 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Firewall Service (Optional)
---------------------------
The following procedure describes how to modify the
``/etc/openstack_deploy/user_variables.yml`` file to enable FWaaS.
#. Override the default list of Neutron plugins to include
``firewall``:
.. code-block:: yaml
neutron_plugin_base:
- firewall
- ...
#. The complete `neutron_plugin_base`, at the time of this writing, is as follows:
.. code-block:: yaml
neutron_plugin_base:
- router
- firewall
- lbaas
- vpnaas
- metering
- qos
#. Execute the Neutron install playbook in order to update the configuration:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
#. Execute the Horizon install playbook in order to update the Horizon
configuration to show the FWaaS panels:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-horizon-install.yml
The FWaaS default configuration options may be changed through the
`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
dict.
.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
--------------
.. include:: navigation.txt

94
doc/source/install-guide/configure-network-services-lbaas.rst
View File

@ -1,94 +0,0 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Load Balancing Service (Optional)
---------------------------------
OpenStack-Ansible currently provides the OpenStack Neutron LBaaS service using
HAProxy as the load balancer. LBaaS has two implementations available: v1 and
v2.
Both implementations use agents that manage `HAProxy`_ daemons. However, LBaaS
v1 has a limitation of one port per load balancer. LBaaS v2 allows for multiple
ports (called *listeners*) per load balancer.
.. note::
Horizon panels for LBaaS v2 are not yet available.
.. _HAProxy: http://www.haproxy.org/
Deploying LBaaS v1
~~~~~~~~~~~~~~~~~~
.. note::
LBaaS v1 was deprecated during the Liberty release and is not recommended
for new deployments.
#. Start by adding the LBaaS v1 plugin to the ``neutron_plugin_base`` variable
within ``/etc/openstack_deploy/user_variables.yml``.
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- lbaas
Ensure that ``neutron_plugin_base`` includes all of the plugins that you
want to deploy with Neutron **in addition** to the LBaaS plugin.
#. Run the Neutron and Horizon playbooks to deploy the LBaaS v1 agent and enable
the LBaaS panels in Horizon.
.. code-block:: console
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
# openstack-ansible os-horizon-install.yml
Deploying LBaaS v2
~~~~~~~~~~~~~~~~~~
#. Start by adding the LBaaS v2 plugin to the ``neutron_plugin_base`` variable
within ``/etc/openstack_deploy/user_variables.yml``.
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- neutron_lbaas.services.loadbalancer.plugin.LoadBalancerPluginv2
Ensure that ``neutron_plugin_base`` includes all of the plugins that you
want to deploy with Neutron **in addition** to the LBaaS plugin.
#. Run the Neutron playbook to deploy the LBaaS v2 agent:
.. code-block:: console
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
Special notes about LBaaS
~~~~~~~~~~~~~~~~~~~~~~~~~
The LBaaS default configuration options may be changed through the
`conf override`_ mechanism using the ``neutron_lbaas_agent_ini_overrides``
dict.
LBaaS v1 and v2 agents cannot run at the same time. If a deployer switches from
LBaaS v1 to v2, the v2 agent will be the only agent running. The LBaaS v1 agent
will be stopped along with any load balancers provisioned under the v1 agent.
The same is true if a deployer chooses to move from LBaaS v2 to v1.
Load balancers are not migrated between LBaaS v1 and v2 automatically. Each
implementation has different code paths and database tables. Deployers will need
to manually delete load balancers, pools, and members before switching LBaaS
versions. Those objects will need to be re-created afterwards.
.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
--------------
.. include:: navigation.txt

50
doc/source/install-guide/configure-network-services-vpnaas.rst
View File

@ -1,50 +0,0 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Virtual Private Network Service (Optional)
------------------------------------------
The following procedure describes how to modify the
``/etc/openstack_deploy/user_variables.yml`` file to enable VPNaaS.
#. Override the default list of Neutron plugins to include
``vpnaas``:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
#. The complete `neutron_plugin_base`, at the time of this writing, is as follows:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- vpnaas
#. Execute the Neutron install playbook in order to update the configuration:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
#. Execute the Horizon install playbook in order to update the Horizon
configuration to show the VPNaaS panels:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-horizon-install.yml
The VPNaaS default configuration options may be changed through the
`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
dict.
.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
--------------
.. include:: navigation.txt

194
doc/source/install-guide/configure-network-services.rst
View File

@ -1,17 +1,191 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Configuring the Network Services (Optional)
-------------------------------------------
Configuring the Networking service (neutron) (optional)
=======================================================
.. toctree::
configure-network-services-fwaas.rst
configure-network-services-lbaas.rst
configure-network-services-vpnaas.rst
The OpenStack Networking service (neutron) includes the following services:
The OpenStack Networking Service, Neutron, includes the following services:
- Firewall as a Service (FWaaS) allows for the configuration of a firewall that filters traffic from the router.
- Load Balancer as a Service (LBaaS) allows for the configuration of a load balancer that directs traffic to the specified instances.
- VPN as a Service (VPNaaS) allows for the configuration of a virtual private network allowing the extension of the private network across a public network.
* Firewall as a Service (FWaaS) allows for the configuration of a firewall
that filters traffic from the router.
* Load Balancer as a Service (LBaaS) allows for the configuration of a
load balancer that directs traffic to the specified instances.
* VPN as a Service (VPNaaS) allows for the configuration of a virtual
private network allowing the extension of the private network across a public network.
Firewall service (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following procedure describes how to modify the
``/etc/openstack_deploy/user_variables.yml`` file to enable FWaaS.
#. Override the default list of neutron plugins to include
``firewall``:
.. code-block:: yaml
neutron_plugin_base:
- firewall
- ...
#. ``neutron_plugin_base`` is as follows:
.. code-block:: yaml
neutron_plugin_base:
- router
- firewall
- lbaas
- vpnaas
- metering
- qos
#. Execute the neutron install playbook in order to update the configuration:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
#. Execute the horizon install playbook to show the FWaaS panels:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-horizon-install.yml
The FWaaS default configuration options may be changed through the
`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
dict.
Load balancing service (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OpenStack-Ansible currently provides the OpenStack neutron LBaaS service using
HAProxy as the load balancer. LBaaS has two implementations available: v1 and
v2.
Both implementations use agents that manage `HAProxy`_ daemons. However, LBaaS
v1 has a limitation of one port per load balancer. LBaaS v2 allows for multiple
ports (called listeners) per load balancer.
.. note::
Horizon panels for LBaaS v2 are not yet available.
.. _HAProxy: http://www.haproxy.org/
Deploying LBaaS v1
------------------
.. note::
We do not recommend LBaaS v1 for new deployments as it is deprecated as of Liberty.
#. Add the LBaaS v1 plugin to the ``neutron_plugin_base`` variable
in ``/etc/openstack_deploy/user_variables.yml``:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- lbaas
Ensure that ``neutron_plugin_base`` includes all of the plugins that you
want to deploy with neutron in addition to the LBaaS plugin.
#. Run the neutron and horizon playbooks to deploy the LBaaS v1 agent and enable
the LBaaS panels in horizon:
.. code-block:: console
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
# openstack-ansible os-horizon-install.yml
Deploying LBaaS v2
------------------
#. Add the LBaaS v2 plugin to the ``neutron_plugin_base`` variable
in ``/etc/openstack_deploy/user_variables.yml``:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- neutron_lbaas.services.loadbalancer.plugin.LoadBalancerPluginv2
Ensure that ``neutron_plugin_base`` includes all of the plugins that you
want to deploy with neutron in addition to the LBaaS plugin.
#. Run the neutron playbook to deploy the LBaaS v2 agent:
.. code-block:: console
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
Special notes about LBaaS
-------------------------
The LBaaS default configuration options are changed through the
`conf override`_ mechanism using the ``neutron_lbaas_agent_ini_overrides``
dict.
LBaaS v1 and v2 agents are unable to run at the same time. If you switch
LBaaS v1 to v2, the v2 agent is the only agent running. The LBaaS v1 agent
stops along with any load balancers provisioned under the v1 agent.
The same is true if you choose to move from LBaaS v2 to v1.
Load balancers are not migrated between LBaaS v1 and v2 automatically. Each
implementation has different code paths and database tables. You need
to manually delete load balancers, pools, and members before switching LBaaS
versions. Recreate these objects afterwards.
Virtual private network service (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following procedure describes how to modify the
``/etc/openstack_deploy/user_variables.yml`` file to enable VPNaaS.
#. Override the default list of neutron plugins to include
``vpnaas``:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
#. ````neutron_plugin_base`` is as follows:
.. code-block:: yaml
neutron_plugin_base:
- router
- metering
- vpnaas
#. Execute the neutron install playbook in order to update the configuration:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-neutron-install.yml
#. Execute the horizon install playbook to show the VPNaaS panels:
.. code-block:: shell-session
# cd /opt/openstack-ansible/playbooks
# openstack-ansible os-horizon-install.yml
The VPNaaS default configuration options are changed through the
`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
dict.
.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
--------------

47
doc/source/install-guide/configure-openstack.rst
View File

@ -1,19 +1,22 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Overriding OpenStack Configuration Defaults
-------------------------------------------
Overriding OpenStack configuration defaults
===========================================
OpenStack has many configuration options available in configuration files
which take the form of ``.conf`` files (in a standard ``INI`` file format),
policy files (in a standard ``JSON`` format) and also in ``YAML`` files (only
in the Ceilometer project at this time).
which are in the form of ``.conf`` files (in a standard ``INI`` file format),
policy files (in a standard ``JSON`` format) and also ``YAML`` files.
OpenStack-Ansible provides the facility to include any options referenced in
.. note::
``YAML`` files are only in the ceilometer project at this time.
OpenStack-Ansible provides the facility to include reference to any options in
the `OpenStack Configuration Reference`_ through the use of a simple set of
configuration entries in ``/etc/openstack_deploy/user_variables.yml``.
This section provides guidance for how to make use of this facility. Further
guidance is available in the Developer Documentation in the section titled
guidance is available in the developer documentation in the section titled
`Setting overrides in configuration files`_.
.. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/
@ -23,11 +26,10 @@ Overriding .conf files
~~~~~~~~~~~~~~~~~~~~~~
The most common use-case for implementing overrides are for the
``<service>.conf`` files (eg: ``nova.conf``). These files use a standard
``<service>.conf`` files (for example, ``nova.conf``). These files use a standard
``INI`` file format.
As an example, if a deployer wishes to add the following parameters
to ``nova.conf``:
For example, if you add the following parameters to ``nova.conf``:
.. code-block:: ini
@ -42,7 +44,7 @@ to ``nova.conf``:
idle_timeout = 300
max_pool_size = 10
This would be accomplished through the use of the following configuration
This is accomplished through the use of the following configuration
entry in ``/etc/openstack_deploy/user_variables.yml``:
.. code-block:: yaml
@ -76,22 +78,21 @@ configuration in ``/etc/openstack_deploy/openstack_user_config.yml``:
idle_timeout: 300
max_pool_size: 10
This method may be used for any INI file format for all OpenStack projects
Use this method for any ``INI`` file format for all OpenStack projects
deployed in OpenStack-Ansible.
To assist deployers in finding the appropriate variable name to use for
To assist you in finding the appropriate variable name to use for
overrides, the general format for the variable name is:
``<service>_<filename>_<file extension>_overrides``.
Overriding .json files
~~~~~~~~~~~~~~~~~~~~~~
Deployers may wish to adjust the default policies applied by services in order
to implement access controls which are different to the norm. Policy files
are in a JSON format.
You can adjust the default policies applied by services in order
to implement access controls which are different to a standard OpenStack
environment. Policy files are in a ``JSON`` format.
As an example, the deployer wishes to add the following policy in
Keystone's ``policy.json``:
For example, you can add the following policy in keystone's ``policy.json``:
.. code-block:: json
@ -100,7 +101,7 @@ Keystone's ``policy.json``:
"identity:bar": "rule:admin_required"
}
This would be accomplished through the use of the following configuration
Accomplish this through the use of the following configuration
entry in ``/etc/openstack_deploy/user_variables.yml``:
.. code-block:: yaml
@ -109,17 +110,17 @@ entry in ``/etc/openstack_deploy/user_variables.yml``:
identity:foo: "rule:admin_required"
identity:bar: "rule:admin_required"
This method may be used for any JSON file format for all OpenStack projects
Use this method for any ``JSON`` file format for all OpenStack projects
deployed in OpenStack-Ansible.
To assist deployers in finding the appropriate variable name to use for
To assist you in finding the appropriate variable name to use for
overrides, the general format for the variable name is
``<service>_policy_overrides``.
Currently Available Overrides
Currently available overrides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For convenience, this is a (possibly incomplete) list of overrides available:
The following is a list of overrides available:
Galera:
* galera_client_my_cnf_overrides

99
doc/source/install-guide/configure-sslcertificates.rst
View File

@ -1,10 +1,10 @@
`Home <index.html>`_ OpenStack-Ansible Installation Guide
Securing services with SSL certificates
---------------------------------------
=======================================
Providing secure communication between various services in an OpenStack
deployment is highly recommended in the `OpenStack Security Guide`_.
The `OpenStack Security Guide`_ recommends providing secure communication
between various services in an OpenStack deployment.
.. _OpenStack Security Guide: http://docs.openstack.org/security-guide/secure-communication.html
@ -16,25 +16,27 @@ certificates for secure communication with the following services:
* Keystone
* RabbitMQ
For each service, deployers have the option to use self-signed certificates
generated during the deployment process or they can provide SSL certificates,
keys and CA certificates from their own trusted certificate authority. Highly
secured environments should use trusted, user-provided, certificates for as
For each service, you have the option to use self-signed certificates
generated during the deployment process or provide SSL certificates,
keys, and CA certificates from your own trusted certificate authority. Highly
secured environments use trusted, user-provided, certificates for as
many services as possible.
All SSL certificate configuration should be done within
``/etc/openstack_deploy/user_variables.yml`` and not within the playbook
roles themselves.
.. note::
Conduct all SSL certificate configuration in
``/etc/openstack_deploy/user_variables.yml`` and not in the playbook
roles themselves.
Self-signed certificates
~~~~~~~~~~~~~~~~~~~~~~~~
Self-signed certificates make it easy to get started quickly and they ensure
data is encrypted in transit, but they don't provide a high level of trust
for highly secure environments. The use of self-signed certificates is
Self-signed certificates ensure you are able to start quickly and you are able to
encrypt data in transit. However, they do not provide a high level of trust
for highly secure environments. The use of self-signed certificates is
currently the default in OpenStack-Ansible. When self-signed certificates are
being used, certificate verification must be disabled using the following
user variables depending on your configuration. These variables can be added
user variables depending on your configuration. Add these variables
in ``/etc/openstack_deploy/user_variables.yml``.
.. code-block:: yaml
@ -43,12 +45,12 @@ in ``/etc/openstack_deploy/user_variables.yml``.
keystone_service_internaluri_insecure: true
Setting self-signed certificate subject data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------------------------------
The subject data of any self-signed certificate can be changed using
configuration variables. The configuration variable for each service is
``<servicename>_ssl_self_signed_subject``. To change the SSL certificate
subject data for HAProxy, simply make this adjustment in ``/etc/openstack_deploy/user_variables.yml``:
Change the subject data of any self-signed certificate using
configuration variables. The configuration variable for each service is
``<servicename>_ssl_self_signed_subject``. To change the SSL certificate
subject data for HAProxy, adjust ``/etc/openstack_deploy/user_variables.yml``:
.. code-block:: yaml
@ -60,23 +62,27 @@ refer to OpenSSL's documentation on the `req subcommand`_.
.. _req subcommand: https://www.openssl.org/docs/manmaster/apps/req.html
Generating and regenerating self-signed certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------------------------
Self-signed certificates for each service are generated during the first run
of the playbook. Subsequent runs of the playbook **will not** generate new SSL
certificates unless the user sets ``<servicename>_ssl_self_signed_regen`` to
``true``.
Generate self-signed certificates for each service during the first run
of the playbook.
To force a self-signed certificate to regenerate you can pass the variable to
.. note::
Subsequent runs of the playbook do not generate new SSL
certificates unless you set ``<servicename>_ssl_self_signed_regen`` to
``true``.
To force a self-signed certificate to regenerate, you can pass the variable to
``openstack-ansible`` on the command line:
.. code-block:: shell-session
# openstack-ansible -e "horizon_ssl_self_signed_regen=true" os-horizon-install.yml
To force a self-signed certificate to regenerate **with every playbook run**,
simply set the appropriate regeneration option to ``true``. For example, if
you've already run the ``os-horizon`` playbook, but you want to regenerate the
To force a self-signed certificate to regenerate with every playbook run,
set the appropriate regeneration option to ``true``. For example, if
you have already run the ``os-horizon`` playbook, but you want to regenerate the
self-signed certificate, set the ``horizon_ssl_self_signed_regen`` variable to
``true`` in ``/etc/openstack_deploy/user_variables.yml``:
@ -84,31 +90,32 @@ self-signed certificate, set the ``horizon_ssl_self_signed_regen`` variable to
horizon_ssl_self_signed_regen: true
Note that regenerating self-signed certificates will replace the existing
certificates whether they are self-signed or user-provided.
.. note::
Regenerating self-signed certificates replaces the existing
certificates whether they are self-signed or user-provided.
User-provided certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~
Deployers can provide their own SSL certificates, keys, and CA certificates
for added trust in highly secure environments. Acquiring certificates from a
trusted certificate authority is outside the scope of this document, but `The
Linux Documentation Project`_ has a section called `Certificate Management`_
that explains to create your own certificate authority and sign certificates.
You can provide your own SSL certificates, keys, and CA certificates
for added trust in highly secure environments. Acquiring certificates from a
trusted certificate authority is outside the scope of this document, but the
`Certificate Management`_ section of the Linux Documentation Project explains
how to create your own certificate authority and sign certificates.
.. _The Linux Documentation Project: http://www.tldp.org/
.. _Certificate Management: http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/c118.html
Deploying user-provided SSL certificates is a three step process:
#. Copy your SSL certificate, key, and CA certificate to the *deployment host*
#. Specify the path to your SSL certificate, key and CA certificate in
``/etc/openstack_deploy/user_variables.yml``
#. Run the playbook for that service
#. Copy your SSL certificate, key, and CA certificate to the deployment host.
#. Specify the path to your SSL certificate, key, and CA certificate in
``/etc/openstack_deploy/user_variables.yml``.
#. Run the playbook for that service.
As an example, if you wanted to deploy user-provided certificates for RabbitMQ,
start by copying those certificates to the deployment host. Then, edit
For example, to deploy user-provided certificates for RabbitMQ,
copy the certificates to the deployment host, edit
``/etc/openstack_deploy/user_variables.yml`` and set the following three
variables:
@ -118,18 +125,18 @@ variables:
rabbitmq_user_ssl_key: /tmp/example.com.key
rabbitmq_user_ssl_ca_cert: /tmp/ExampleCA.crt
Simply run the playbook to apply the certificates:
Run the playbook to apply the certificates:
.. code-block:: shell-session
# openstack-ansible rabbitmq-install.yml
The playbook will deploy your user-provided SSL certificate, key, and CA
The playbook deploys your user-provided SSL certificate, key, and CA
certificate to each RabbitMQ container.
The process is identical with other services as well. Simply replace
The process is identical to the other services. Replace
``rabbitmq`` in the configuration variables shown above with ``horizon``,
``haproxy``, or ``keystone``, to deploy user-provided certificates to those
``haproxy``, or ``keystone`` to deploy user-provided certificates to those
services.
--------------