From f1a7525570f8a30cc9e335f00fb3007a52ed6344 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Evrard Date: Thu, 22 Feb 2018 21:46:21 +0000 Subject: [PATCH] [Docs] Migrate security into user guide Migrate all the security related user configurations into a user story. Change-Id: I4dfc5941abfd834d1d53a9c737db7afcce2841a0 --- deploy-guide/source/app-resources.rst | 6 +-- deploy-guide/source/app.rst | 1 - .../reference/architecture/security.rst | 23 +---------- doc/source/user/index.rst | 1 + doc/source/user/security/hardening.rst | 29 ++++++++++++++ doc/source/user/security/index.rst | 12 ++++++ .../source/user/security/ssl-certificates.rst | 39 +++++++++++-------- 7 files changed, 70 insertions(+), 41 deletions(-) create mode 100644 doc/source/user/security/hardening.rst create mode 100644 doc/source/user/security/index.rst rename deploy-guide/source/app-advanced-config-sslcertificates.rst => doc/source/user/security/ssl-certificates.rst (89%) diff --git a/deploy-guide/source/app-resources.rst b/deploy-guide/source/app-resources.rst index 903ac56754..fbada8c4cc 100644 --- a/deploy-guide/source/app-resources.rst +++ b/deploy-guide/source/app-resources.rst @@ -1,6 +1,6 @@ -================================ -Appendix K: Additional resources -================================ +==================== +Additional resources +==================== Ansible resources: diff --git a/deploy-guide/source/app.rst b/deploy-guide/source/app.rst index adadcf8395..c846febdc7 100644 --- a/deploy-guide/source/app.rst +++ b/deploy-guide/source/app.rst @@ -5,5 +5,4 @@ Appendices .. toctree:: :maxdepth: 2 - app-advanced-config-sslcertificates.rst app-resources.rst diff --git a/doc/source/reference/architecture/security.rst b/doc/source/reference/architecture/security.rst index 34a4ec633a..efc0fb540f 100644 --- a/doc/source/reference/architecture/security.rst +++ b/doc/source/reference/architecture/security.rst @@ -1,3 +1,5 @@ +.. _security-design: + Security ======== @@ -52,27 +54,6 @@ to all deployments. The role has been carefully designed to perform as follows: * Balance security with OpenStack performance and functionality * Run as quickly as possible -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 the value of -the ``apply_security_hardening`` variable in the ``user_variables.yml`` file -to ``false``: - -.. code-block:: yaml - - apply_security_hardening: false - -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 - - # Apply security hardening configurations - openstack-ansible security-hardening.yml - - # 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 `security hardening role`_ documentation. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 49ad9637a3..dac25f870e 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -28,3 +28,4 @@ For in-depth technical information, see the limited-connectivity/index.rst l3pods/example.rst ceph/full-deploy.rst + security/index.rst diff --git a/doc/source/user/security/hardening.rst b/doc/source/user/security/hardening.rst new file mode 100644 index 0000000000..e07322a147 --- /dev/null +++ b/doc/source/user/security/hardening.rst @@ -0,0 +1,29 @@ +Apply ansible-hardening +======================= + +The ``ansible-hardening`` 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 the value of +the ``apply_security_hardening`` variable in the ``user_variables.yml`` file +to ``false``: + +.. code-block:: yaml + + apply_security_hardening: false + +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 + + # Apply security hardening configurations + openstack-ansible security-hardening.yml + + # 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 +`security hardening role`_ documentation. + +.. _security hardening role: http://docs.openstack.org/developer/ansible-hardening/ diff --git a/doc/source/user/security/index.rst b/doc/source/user/security/index.rst new file mode 100644 index 0000000000..5721211bdd --- /dev/null +++ b/doc/source/user/security/index.rst @@ -0,0 +1,12 @@ +================= +Security settings +================= + +This chapter contains information to configure specific security +settings for your OpenStack-Ansible cloud. + +For understanding security design, please see +:ref:`security-design`. + +.. include:: ssl-certificates.rst +.. include:: hardening.rst diff --git a/deploy-guide/source/app-advanced-config-sslcertificates.rst b/doc/source/user/security/ssl-certificates.rst similarity index 89% rename from deploy-guide/source/app-advanced-config-sslcertificates.rst rename to doc/source/user/security/ssl-certificates.rst index 8efe1ad96c..911a40a722 100644 --- a/deploy-guide/source/app-advanced-config-sslcertificates.rst +++ b/doc/source/user/security/ssl-certificates.rst @@ -1,4 +1,3 @@ -======================================= Securing services with SSL certificates ======================================= @@ -12,24 +11,17 @@ communication between services: All public endpoints reside behind haproxy, resulting in the only certificate management most environments need are those for haproxy. -When deploying with OpenStack-Ansible, 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 -many services as possible. +When deploying with OpenStack-Ansible, 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 many services as possible. .. note:: Perform all SSL certificate configuration in - ``/etc/openstack_deploy/user_variables.yml`` file and not in the playbooks - or roles themselves. The variables to set which provide the path on the deployment - node to the certificates for HAProxy configuration are: - -.. code-block:: yaml - - haproxy_user_ssl_cert: /etc/openstack_deploy/ssl/example.com.crt - haproxy_user_ssl_key: /etc/openstack_deploy/ssl/example.com.key - haproxy_user_ssl_ca_cert: /etc/openstack_deploy/ssl/ExampleCA.crt + ``/etc/openstack_deploy/user_variables.yml`` file. Do not edit the playbooks + or roles themselves. Self-signed certificates ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -113,7 +105,22 @@ OpenStack-Ansible: the ``/etc/openstack_deploy/user_variables.yml`` file. #. Run the playbook for that service. -For example, to deploy user-provided certificates for RabbitMQ, +HAProxy example +--------------- + +The variables to set which provide the path on the deployment +node to the certificates for HAProxy configuration are: + +.. code-block:: yaml + + haproxy_user_ssl_cert: /etc/openstack_deploy/ssl/example.com.crt + haproxy_user_ssl_key: /etc/openstack_deploy/ssl/example.com.key + haproxy_user_ssl_ca_cert: /etc/openstack_deploy/ssl/ExampleCA.crt + +RabbitMQ example +---------------- + +To deploy user-provided certificates for RabbitMQ, copy the certificates to the deployment host, edit the ``/etc/openstack_deploy/user_variables.yml`` file and set the following three variables: