diff --git a/doc/source/install-guide/app-advanced-config-affinity.rst b/doc/source/install-guide/app-advanced-config-affinity.rst index 108fd19f4a..ac8af5f298 100644 --- a/doc/source/install-guide/app-advanced-config-affinity.rst +++ b/doc/source/install-guide/app-advanced-config-affinity.rst @@ -2,12 +2,12 @@ Affinity ======== -OpenStack-Ansible's dynamic inventory generation has a concept called -`affinity`. This determines how many containers of a similar type are deployed -onto a single physical host. +When OpenStack-Ansible generates its dynamic inventory, the affinity +setting determines how many containers of a similar type are deployed on a +single physical host. -Using `shared-infra_hosts` as an example, consider this -``openstack_user_config.yml``: +Using ``shared-infra_hosts`` as an example, consider this +``openstack_user_config.yml`` configuration: .. code-block:: yaml @@ -21,13 +21,13 @@ Using `shared-infra_hosts` as an example, consider this Three hosts are assigned to the `shared-infra_hosts` group, OpenStack-Ansible ensures that each host runs a single database container, -a single memcached container, and a single RabbitMQ container. Each host has -an affinity of 1 by default, and that means each host will run one of each +a single Memcached container, and a single RabbitMQ container. Each host has +an affinity of 1 by default, which means that each host runs one of each container type. -You can skip the deployment of RabbitMQ altogether. This is -helpful when deploying a standalone swift environment. If you need -this configuration, your ``openstack_user_config.yml`` would look like this: +If you are deploying a stand-alone Object Storage (swift) environment, +you can skip the deployment of RabbitMQ. If you use this configuration, +your ``openstack_user_config.yml`` file would look as follows: .. code-block:: yaml @@ -45,6 +45,6 @@ this configuration, your ``openstack_user_config.yml`` would look like this: rabbit_mq_container: 0 ip: 172.29.236.103 -The configuration above deploys a memcached container and a database -container on each host, without the RabbitMQ containers. +This configuration deploys a Memcached container and a database container +on each host, but no RabbitMQ containers. diff --git a/doc/source/install-guide/app-advanced-config-options.rst b/doc/source/install-guide/app-advanced-config-options.rst index 209f0d510a..b2dbeedb1f 100644 --- a/doc/source/install-guide/app-advanced-config-options.rst +++ b/doc/source/install-guide/app-advanced-config-options.rst @@ -2,6 +2,9 @@ Appendix F: Advanced configuration =================================== +.. TODO: include intro on what advanced configuration is, whether it’s required + or optional, and when someone should do it + .. toctree:: :maxdepth: 2 diff --git a/doc/source/install-guide/app-advanced-config-override.rst b/doc/source/install-guide/app-advanced-config-override.rst index 4d778de0b1..c253d36b68 100644 --- a/doc/source/install-guide/app-advanced-config-override.rst +++ b/doc/source/install-guide/app-advanced-config-override.rst @@ -2,33 +2,35 @@ Overriding OpenStack configuration defaults =========================================== -OpenStack has many configuration options available in configuration files -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 has many configuration options available in ``.conf`` files +(in a standard ``INI`` file format), +policy files (in a standard ``JSON`` format) and ``YAML`` files. .. 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``. +OpenStack-Ansible enables you to reference any options in the +`OpenStack Configuration Reference`_ through the use of a simple set of +configuration entries in the ``/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 -`Setting overrides in configuration files`_. +This section describes how to use the configuration entries in the +``/etc/openstack_deploy/user_variables.yml`` file to override default +configuration settings. For more information, see the +`Setting overrides in configuration files`_ section in the developer +documentation. .. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/ .. _Setting overrides in configuration files: ../developer-docs/extending.html#setting-overrides-in-configuration-files -Overriding ``.conf`` files -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Overriding .conf files +~~~~~~~~~~~~~~~~~~~~~~ -The most common use-case for implementing overrides are for the -``.conf`` files (for example, ``nova.conf``). These files use a -standard ``INI`` file format. +Most often, overrides are implemented for the ``.conf`` files +(for example, ``nova.conf``). These files use a standard INI file format. -For example, if you add the following parameters to ``nova.conf``: +For example, you might want to add the following parameters to the +``nova.conf`` file: .. code-block:: ini @@ -43,8 +45,8 @@ For example, if you add the following parameters to ``nova.conf``: idle_timeout = 300 max_pool_size = 10 -This is accomplished through the use of the following configuration -entry in ``/etc/openstack_deploy/user_variables.yml``: +To do this, you use the following configuration entry in the +``/etc/openstack_deploy/user_variables.yml`` file: .. code-block:: yaml @@ -58,8 +60,16 @@ entry in ``/etc/openstack_deploy/user_variables.yml``: idle_timeout: 300 max_pool_size: 10 -Overrides may also be applied on a per host basis with the following -configuration in ``/etc/openstack_deploy/openstack_user_config.yml``: +.. note:: + + The general format for the variable names used for overrides is + ``___overrides``. For example, the variable + name used in these examples to add parameters to the ``nova.conf`` file is + ``nova_nova_conf_overrides``. + +You can also apply overrides on a per-host basis with the following +configuration in the ``/etc/openstack_deploy/openstack_user_config.yml`` +file: .. code-block:: yaml @@ -77,21 +87,18 @@ configuration in ``/etc/openstack_deploy/openstack_user_config.yml``: idle_timeout: 300 max_pool_size: 10 -Use this method for any ``INI`` file format for all OpenStack projects +Use this method for any files with the ``INI`` format for in OpenStack projects deployed in OpenStack-Ansible. -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 +~~~~~~~~~~~~~~~~~~~~~~ -Overriding ``.json`` files -~~~~~~~~~~~~~~~~~~~~~~~~~~ +To implement access controls that are different from the ones in a standard +OpenStack environment, you can adjust the default policies applied by services. +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. - -For example, you can add the following policy in keystone's ``policy.json``: +For example, you might want to add the following policy in the ``policy.json`` +file for the Identity service (keystone): .. code-block:: json @@ -100,8 +107,8 @@ For example, you can add the following policy in keystone's ``policy.json``: "identity:bar": "rule:admin_required" } -Accomplish this through the use of the following configuration -entry in ``/etc/openstack_deploy/user_variables.yml``: +To do this, you use the following configuration entry in the +``/etc/openstack_deploy/user_variables.yml`` file: .. code-block:: yaml @@ -109,26 +116,34 @@ entry in ``/etc/openstack_deploy/user_variables.yml``: identity:foo: "rule:admin_required" identity:bar: "rule:admin_required" -Use this method for all OpenStack projects -deployed in OpenStack-Ansible with ``JSON`` file formats. +.. note:: + + The general format for the variable names used for overrides is + ``_policy_overrides``. For example, the variable name used in this + example to add a policy to the Identity service (keystone) ``policy.json`` file + is ``keystone_policy_overrides``. + +Use this method for any files with the ``JSON`` format in OpenStack projects +deployed in OpenStack-Ansible. To assist you in finding the appropriate variable name to use for overrides, the general format for the variable name is ``_policy_overrides``. -Overriding YAML files +Overriding .yml files ~~~~~~~~~~~~~~~~~~~~~~~~~~ You can override ``.yml`` file values by supplying replacement YAML content. .. note:: - All default YAML file content will be completely overwritten by - the provided overrides, so the entire YAML source (both the existing - content and your changes) must be provided. + All default YAML file content is completely overwritten by the overrides, + so the entire YAML source (both the existing content and your changes) + must be provided. -For example, you can define a meter exclusion for all hardware items -in the default content of ceilometer's ``pipeline.yml``: +For example, you might want to define a meter exclusion for all hardware +items in the default content of the ``pipeline.yml`` file for the +Telemetry service (ceilometer): .. code-block:: yaml @@ -142,8 +157,8 @@ in the default content of ceilometer's ``pipeline.yml``: - name: foo_source value: foo -You can accomplish this through the use of the following configuration -entry in ``/etc/openstack_deploy/user_variables.yml``: +To do this, you use the following configuration entry in the +``/etc/openstack_deploy/user_variables.yml`` file: .. code-block:: yaml @@ -158,14 +173,17 @@ entry in ``/etc/openstack_deploy/user_variables.yml``: - name: source_foo value: foo -To assist you in finding the appropriate variable name to use for -overrides, the general format for the variable name is -``___overrides``. +.. note:: + + The general format for the variable names used for overrides is + ``___overrides``. For example, the variable + name used in this example to define a meter exclusion in the ``pipeline.yml`` file + for the Telemetry service (ceilometer) is ``ceilometer_pipeline_yaml_overrides``. Currently available overrides ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following is a list of overrides available: +The following override variables are available. Galera: * galera_client_my_cnf_overrides @@ -173,7 +191,7 @@ Galera: * galera_cluster_cnf_overrides * galera_debian_cnf_overrides -Ceilometer: +Telemetry service (ceilometer): * ceilometer_policy_overrides * ceilometer_ceilometer_conf_overrides * ceilometer_api_paste_ini_overrides @@ -181,13 +199,13 @@ Ceilometer: * ceilometer_event_pipeline_yaml_overrides * ceilometer_pipeline_yaml_overrides -Cinder: +Block Storage (cinder): * cinder_policy_overrides * cinder_rootwrap_conf_overrides * cinder_api_paste_ini_overrides * cinder_cinder_conf_overrides -Glance: +Image service (glance): * glance_glance_api_paste_ini_overrides * glance_glance_api_conf_overrides * glance_glance_cache_conf_overrides @@ -198,7 +216,7 @@ Glance: * glance_glance_scheme_json_overrides * glance_policy_overrides -Heat: +Orchestration service (heat): * heat_heat_conf_overrides * heat_api_paste_ini_overrides * heat_default_yaml_overrides @@ -206,13 +224,13 @@ Heat: * heat_aws_rds_dbinstance_yaml_overrides * heat_policy_overrides -Keystone: +Identity service (keystone): * keystone_keystone_conf_overrides * keystone_keystone_default_conf_overrides * keystone_keystone_paste_ini_overrides * keystone_policy_overrides -Neutron: +Networking service (neutron): * neutron_neutron_conf_overrides * neutron_ml2_conf_ini_overrides * neutron_dhcp_agent_ini_overrides @@ -224,13 +242,13 @@ Neutron: * neutron_metadata_agent_ini_overrides * neutron_metering_agent_ini_overrides -Nova: +Compute service (nova): * nova_nova_conf_overrides * nova_rootwrap_conf_overrides * nova_api_paste_ini_overrides * nova_policy_overrides -Swift: +Object Storage service (swift): * swift_swift_conf_overrides * swift_swift_dispersion_conf_overrides * swift_proxy_server_conf_overrides diff --git a/doc/source/install-guide/app-advanced-config-security.rst b/doc/source/install-guide/app-advanced-config-security.rst index 4137c354b1..e4ac94352a 100644 --- a/doc/source/install-guide/app-advanced-config-security.rst +++ b/doc/source/install-guide/app-advanced-config-security.rst @@ -5,39 +5,35 @@ Security hardening ================== OpenStack-Ansible automatically applies host security hardening configurations -using the `openstack-ansible-security`_ role. The role uses a version of the +by using the `openstack-ansible-security`_ role. The role uses a version of the `Security Technical Implementation Guide (STIG)`_ that has been adapted for Ubuntu 14.04 and OpenStack. The role is applicable to physical hosts within an OpenStack-Ansible deployment that are operating as any type of node, infrastructure or compute. By -default, the role is enabled. You can disable it by changing a variable -within ``user_variables.yml``: +default, the role is enabled. You can disable it by changing the value of +the ``apply_security_hardening`` variable in the ``user_variables.yml`` file +to ``false``: .. code-block:: yaml apply_security_hardening: false -When the variable is set to ``true``, the ``setup-hosts.yml`` playbook applies -the role during deployments. - -You can apply security configurations to an existing environment or audit -an environment using a playbook supplied with OpenStack-Ansible: +You can apply security hardening configurations to an existing environment or +audit an environment by using a playbook supplied with OpenStack-Ansible: .. code-block:: bash - # Perform a quick audit using Ansible's check mode - openstack-ansible --check security-hardening.yml - # Apply security hardening configurations - openstack-ansible security-hardening.yml + openstack-ansible security-hardening.yml -Refer to the `openstack-ansible-security`_ documentation for more details on -the security configurations. Review the `Configuration`_ -section of the openstack-ansible-security documentation to find out how to -fine-tune certain security configurations. + # Perform a quick audit by using Ansible's check mode + openstack-ansible --check security-hardening.yml + +For more information about the security configurations, see the +`OpenStack-Ansible host security`_ hardening documentation. .. _openstack-ansible-security: http://docs.openstack.org/developer/openstack-ansible-security/ .. _Security Technical Implementation Guide (STIG): https://en.wikipedia.org/wiki/Security_Technical_Implementation_Guide -.. _Configuration: http://docs.openstack.org/developer/openstack-ansible-security/configuration.html +.. _OpenStack-Ansible host security: http://docs.openstack.org/developer/openstack-ansible-security/ .. _Appendix H: ../install-guide/app-custom-layouts.html diff --git a/doc/source/install-guide/app-advanced-config-sslcertificates.rst b/doc/source/install-guide/app-advanced-config-sslcertificates.rst index 3ee09b6b6a..9a8eb96571 100644 --- a/doc/source/install-guide/app-advanced-config-sslcertificates.rst +++ b/doc/source/install-guide/app-advanced-config-sslcertificates.rst @@ -3,91 +3,91 @@ Securing services with SSL certificates ======================================= The `OpenStack Security Guide`_ recommends providing secure communication -between various services in an OpenStack deployment. +between various services in an OpenStack deployment. The OpenStack-Ansible +project currently offers the ability to configure SSL certificates for secure +communication with the following services: .. _OpenStack Security Guide: http://docs.openstack.org/security-guide/secure-communication.html -The OpenStack-Ansible project currently offers the ability to configure SSL -certificates for secure communication with the following services: - * HAProxy -* Horizon -* Keystone +* Dashboard (horizon) +* Identity (keystone) * RabbitMQ -For each service, you have the option to use self-signed certificates +For each service, you can either use self-signed certificates that are 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 +secured environments use trusted, user-provided certificates for as many services as possible. .. note:: - Conduct all SSL certificate configuration in - ``/etc/openstack_deploy/user_variables.yml`` and not in the playbook + Perform all SSL certificate configuration in + ``/etc/openstack_deploy/user_variables.yml`` file and not in the playbook roles themselves. Self-signed certificates ~~~~~~~~~~~~~~~~~~~~~~~~ -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. Add these variables -in ``/etc/openstack_deploy/user_variables.yml``. +Self-signed certificates enable you to start quickly and encrypt data in +transit. However, they do not provide a high level of trust for highly +secure environments. By default, self-signed certificates are used in +OpenStack-Ansible. When self-signed certificates are used, you must disable +certificate verification by using the following user variables, depending on +your configuration. Add these variables in the +``/etc/openstack_deploy/user_variables.yml`` file. .. code-block:: yaml keystone_service_adminuri_insecure: true keystone_service_internaluri_insecure: true -Setting self-signed certificate subject data --------------------------------------------- +Setting subject data for self-signed certificates +------------------------------------------------- -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``: +Change the subject data of any self-signed certificate by using +configuration variables. The configuration variable for each service +is formatted as ``_ssl_self_signed_subject``. For example, to +change the SSL certificate subject data for HAProxy, adjust the +``/etc/openstack_deploy/user_variables.yml`` file as follows: .. code-block:: yaml haproxy_ssl_self_signed_subject: "/C=US/ST=Texas/L=San Antonio/O=IT/CN=haproxy.example.com" + For more information about the available fields in the certificate subject, -refer to OpenSSL's documentation on the `req subcommand`_. +see the OpenSSL documentation for the `req subcommand`_. .. _req subcommand: https://www.openssl.org/docs/manmaster/apps/req.html Generating and regenerating self-signed certificates ---------------------------------------------------- -Generate self-signed certificates for each service during the first run -of the playbook. +Self-signed certificates are generated for each service during the first +run of the playbook. -.. note:: +To generate a new self-signed certificate for a service, you must set +the ``_ssl_self_signed_regen`` variable to true in one of the +following ways: - 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: -To force a self-signed certificate to regenerate, you can pass the variable to -``openstack-ansible`` on the command line: + .. code-block:: shell-session -.. code-block:: shell-session + # openstack-ansible -e "horizon_ssl_self_signed_regen=true" os-horizon-install.yml - # 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, + 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 the ``/etc/openstack_deploy/user_variables.yml`` + file: -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``: + .. code-block:: yaml -.. code-block:: yaml - - horizon_ssl_self_signed_regen: true + horizon_ssl_self_signed_regen: true .. note:: @@ -98,25 +98,27 @@ to ``true`` in ``/etc/openstack_deploy/user_variables.yml``: User-provided certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can provide your own SSL certificates, keys, and CA certificates -for added trust in highly secure environments. Acquiring certificates from a +For added trust in highly secure environments, you can provide your own SSL +certificates, keys, and CA certificates. 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. .. _Certificate Management: http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/c118.html -Deploying user-provided SSL certificates is a three step process: +Use the following process to deploy user-provided SSL certificates in +OpenStack-Ansible: -#. Copy your SSL certificate, key, and CA certificate to the deployment host. +#. Copy your SSL certificate, key, and CA certificate files to the deployment + host. #. Specify the path to your SSL certificate, key, and CA certificate in - ``/etc/openstack_deploy/user_variables.yml``. + the ``/etc/openstack_deploy/user_variables.yml`` file. #. Run the playbook for that service. 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: +the ``/etc/openstack_deploy/user_variables.yml`` file and set the following +three variables: .. code-block:: yaml @@ -124,7 +126,7 @@ variables: rabbitmq_user_ssl_key: /tmp/example.com.key rabbitmq_user_ssl_ca_cert: /tmp/ExampleCA.crt -Run the playbook to apply the certificates: +Then, run the playbook to apply the certificates: .. code-block:: shell-session @@ -133,7 +135,7 @@ Run the playbook to apply the certificates: The playbook deploys your user-provided SSL certificate, key, and CA certificate to each RabbitMQ container. -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 -services. +The process is identical for the other services. Replace `rabbitmq` in +the preceding configuration variables with `horizon`, `haproxy`, or `keystone`, +and then run the playbook for that service to deploy user-provided certificates +to those services. diff --git a/doc/source/install-guide/app-advanced-role-docs.rst b/doc/source/install-guide/app-advanced-role-docs.rst index e861178176..49995c3db1 100644 --- a/doc/source/install-guide/app-advanced-role-docs.rst +++ b/doc/source/install-guide/app-advanced-role-docs.rst @@ -4,11 +4,11 @@ Advanced service configuration ============================== -OpenStack-Ansible has many options which can be used for the advanced -configuration of services. Each role's documentation provides more -insight into the options available and what they are used for. +OpenStack-Ansible has many options that you can use for the advanced +configuration of services. Each role's documentation provides information +about the available options. -The following options are not necessary to set - they are entirely optional. +The following options are optional. Infrastructure service roles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~