diff --git a/doc/source/install-guide/configure-ceph.rst b/doc/source/install-guide/configure-ceph.rst index f389dba418..618cbedb97 100644 --- a/doc/source/install-guide/configure-ceph.rst +++ b/doc/source/install-guide/configure-ceph.rst @@ -1,11 +1,11 @@ `Home `_ 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 diff --git a/doc/source/install-guide/configure-configurationintegrity.rst b/doc/source/install-guide/configure-configurationintegrity.rst index c080871f48..91e1cbbaa9 100644 --- a/doc/source/install-guide/configure-configurationintegrity.rst +++ b/doc/source/install-guide/configure-configurationintegrity.rst @@ -1,28 +1,29 @@ `Home `_ 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: ``_ -#. Check the integrity of your yaml files using a yaml linter. +#. Check the integrity of your YAML files: .. note:: Here is an online linter: ``_ -#. 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. -------------- diff --git a/doc/source/install-guide/configure-federation-idp-adfs.rst b/doc/source/install-guide/configure-federation-idp-adfs.rst index 63d84ded7b..cadbd4e7c7 100644 --- a/doc/source/install-guide/configure-federation-idp-adfs.rst +++ b/doc/source/install-guide/configure-federation-idp-adfs.rst @@ -1,7 +1,7 @@ `Home `__ 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 `_ 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://: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/`_ -------------- diff --git a/doc/source/install-guide/configure-federation-idp.rst b/doc/source/install-guide/configure-federation-idp.rst index 769b40c5cb..e50d0f4f97 100644 --- a/doc/source/install-guide/configure-federation-idp.rst +++ b/doc/source/install-guide/configure-federation-idp.rst @@ -1,11 +1,13 @@ `Home `__ 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 ``/OS-FEDERATION/saml2/idp`` +* ``idp_entity_id`` is the entity ID. The service providers + use this as a unique identifier for each IdP. ``/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 - ``/OS-FEDERATION/saml2/sso>`` +* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. + ``/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. -------------- diff --git a/doc/source/install-guide/configure-federation-mapping.rst b/doc/source/install-guide/configure-federation-mapping.rst index b0cda56634..9c1b4a8945 100644 --- a/doc/source/install-guide/configure-federation-mapping.rst +++ b/doc/source/install-guide/configure-federation-mapping.rst @@ -1,7 +1,7 @@ `Home `__ 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 `_. -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``. diff --git a/doc/source/install-guide/configure-federation-sp-overview.rst b/doc/source/install-guide/configure-federation-sp-overview.rst index 7d9a6dd5d6..870aa28ee1 100644 --- a/doc/source/install-guide/configure-federation-sp-overview.rst +++ b/doc/source/install-guide/configure-federation-sp-overview.rst @@ -1,49 +1,52 @@ `Home `__ 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`_ -------------- diff --git a/doc/source/install-guide/configure-federation-sp.rst b/doc/source/install-guide/configure-federation-sp.rst index ea99e0ff39..6a14117441 100644 --- a/doc/source/install-guide/configure-federation-sp.rst +++ b/doc/source/install-guide/configure-federation-sp.rst @@ -1,40 +1,35 @@ `Home `__ 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 `_ 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 `_ + 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. `_ diff --git a/doc/source/install-guide/configure-federation-use-case.rst b/doc/source/install-guide/configure-federation-use-case.rst index 926abef5fb..0c97bdeb12 100644 --- a/doc/source/install-guide/configure-federation-use-case.rst +++ b/doc/source/install-guide/configure-federation-use-case.rst @@ -1,9 +1,9 @@ `Home `__ 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 ] @@ -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 +-------+----------------+ diff --git a/doc/source/install-guide/configure-federation-wrapper.rst b/doc/source/install-guide/configure-federation-wrapper.rst index b7b6fc2aa2..84d90b3aa5 100644 --- a/doc/source/install-guide/configure-federation-wrapper.rst +++ b/doc/source/install-guide/configure-federation-wrapper.rst @@ -1,77 +1,92 @@ `Home `__ 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= --os-url= [options] +.. code:: -or alternatively:: + # openstack --os-token= --os-url= [options] - # export OS_TOKEN= - # export OS_URL= - # 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= + # export OS_URL= + # 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. -------------- diff --git a/doc/source/install-guide/configure-federation.rst b/doc/source/install-guide/configure-federation.rst index b9e85bcd3a..00f23ef76f 100644 --- a/doc/source/install-guide/configure-federation.rst +++ b/doc/source/install-guide/configure-federation.rst @@ -1,7 +1,7 @@ `Home `__ 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. `_ @@ -38,8 +39,8 @@ The following procedure describes how set up federation. #. `Run the authentication wrapper to use Identity Service to Identity Service federation. `_ - 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. `_ -------------- diff --git a/doc/source/install-guide/configure-network-services-fwaas.rst b/doc/source/install-guide/configure-network-services-fwaas.rst deleted file mode 100644 index 8153bf75ce..0000000000 --- a/doc/source/install-guide/configure-network-services-fwaas.rst +++ /dev/null @@ -1,53 +0,0 @@ -`Home `_ 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 \ No newline at end of file diff --git a/doc/source/install-guide/configure-network-services-lbaas.rst b/doc/source/install-guide/configure-network-services-lbaas.rst deleted file mode 100644 index c21e910845..0000000000 --- a/doc/source/install-guide/configure-network-services-lbaas.rst +++ /dev/null @@ -1,94 +0,0 @@ -`Home `_ 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 diff --git a/doc/source/install-guide/configure-network-services-vpnaas.rst b/doc/source/install-guide/configure-network-services-vpnaas.rst deleted file mode 100644 index 4214c985f4..0000000000 --- a/doc/source/install-guide/configure-network-services-vpnaas.rst +++ /dev/null @@ -1,50 +0,0 @@ -`Home `_ 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 \ No newline at end of file diff --git a/doc/source/install-guide/configure-network-services.rst b/doc/source/install-guide/configure-network-services.rst index aa78a65996..8a4ca77b37 100644 --- a/doc/source/install-guide/configure-network-services.rst +++ b/doc/source/install-guide/configure-network-services.rst @@ -1,17 +1,191 @@ `Home `_ 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 -------------- diff --git a/doc/source/install-guide/configure-openstack.rst b/doc/source/install-guide/configure-openstack.rst index 5cb2fa71d7..1bce391f10 100644 --- a/doc/source/install-guide/configure-openstack.rst +++ b/doc/source/install-guide/configure-openstack.rst @@ -1,19 +1,22 @@ `Home `_ 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 -``.conf`` files (eg: ``nova.conf``). These files use a standard +``.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: ``___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 ``_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 diff --git a/doc/source/install-guide/configure-sslcertificates.rst b/doc/source/install-guide/configure-sslcertificates.rst index 56bb14b35b..157827f7bf 100644 --- a/doc/source/install-guide/configure-sslcertificates.rst +++ b/doc/source/install-guide/configure-sslcertificates.rst @@ -1,10 +1,10 @@ `Home `_ 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 -``_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 +``_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 ``_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 ``_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. --------------