[Docs] Move network architecture into reference

Move all the design considerations into reference.

Change-Id: I5e5b4e85140b73871f2ba6a4d5264cb21de9f337

deploy-guide/source/app.rst

@@ -6,8 +6,6 @@ Appendices
    :maxdepth: 2
 
    app-custom-layouts.rst
-   app-security.rst
-   app-networking.rst
    app-limited-connectivity.rst
    app-advanced-config-sslcertificates.rst
    app-resources.rst

deploy-guide/source/overview-network-arch.rst

@@ -9,7 +9,9 @@ hosts requires manual configuration because it varies from one use case to
 another. This section describes the network configuration that must be
 implemented on all target hosts.
 
-For more information about how networking works, see :ref:`network-appendix`.
+For more information about how networking works, see the
+:dev_docs:`OpenStack-Ansible Reference Architecture, section Container
+Networking <reference/architecture/index.html>`.
 
 Host network bridges
 ~~~~~~~~~~~~~~~~~~~~

doc/source/reference/architecture/container-networking.rst

@@ -1,8 +1,8 @@
-.. _network-appendix:
+.. _container-networking:
 
-================================
-Appendix G: Container networking
-================================
+====================
+Container networking
+====================
 
 OpenStack-Ansible deploys Linux containers (LXC) and uses Linux
 bridging between the container and the host interfaces to ensure that
@@ -53,7 +53,7 @@ namespaces.
 The following image demonstrates how the container network interfaces are
 connected to the host's bridges and physical network interfaces:
 
-.. image:: figures/networkcomponents.png
+.. image:: ../figures/networkcomponents.png
 
 Network diagrams
 ~~~~~~~~~~~~~~~~
@@ -64,7 +64,7 @@ Hosts with services running in containers
 The following diagram shows how all of the interfaces and bridges interconnect
 to provide network connectivity to the OpenStack deployment:
 
-.. image:: figures/networkarch-container-external.png
+.. image:: ../figures/networkarch-container-external.png
 
 The interface ``lxcbr0`` provides connectivity for the containers to the
 outside world, thanks to dnsmasq (dhcp/dns) + NAT.
@@ -84,7 +84,7 @@ OpenStack-Ansible deploys the Compute service on the physical host rather than
 in a container. The following diagram shows how to use bridges for
 network connectivity:
 
-.. image:: figures/networkarch-bare-external.png
+.. image:: ../figures/networkarch-bare-external.png
 
 Neutron traffic
 ---------------
@@ -96,12 +96,12 @@ networking-agents container. The diagram shows how DHCP agents provide
 information (IP addresses and DNS servers) to the instances, and how routing
 works on the image.
 
-.. image:: figures/networking-neutronagents.png
+.. image:: ../figures/networking-neutronagents.png
 
 The following diagram shows how virtual machines connect to the ``br-vlan`` and
 ``br-vxlan`` bridges and send traffic to the network outside the host:
 
-.. image:: figures/networking-compute.png
+.. image:: ../figures/networking-compute.png
 
 .. _openstack-user-config-reference:
 
@@ -112,7 +112,7 @@ The ``openstack_user_config.yml.example`` file is heavily commented with the
 details of how to do more advanced container networking configuration. The
 contents of the file are shown here for reference.
 
-.. literalinclude:: ../../etc/openstack_deploy/openstack_user_config.yml.example
+.. literalinclude:: ../../../../etc/openstack_deploy/openstack_user_config.yml.example
    :language: yaml
    :start-after: under the License.
 

doc/source/reference/architecture/index.rst

@@ -0,0 +1,15 @@
+============
+Architecture
+============
+
+Many operational requirements have been taken into consideration for
+the design of the OpenStack-Ansible project.
+
+In this chapter, you can find details about `why` OpenStack-Ansible
+was architected in this way.
+
+.. toctree::
+   :maxdepth: 1
+
+   security.rst
+   container-networking.rst

doc/source/reference/architecture/security.rst

@@ -1,15 +1,11 @@
-====================
-Appendix F: Security
-====================
+Security
+========
 
 Security is one of the top priorities within OpenStack-Ansible (OSA), and many
 security enhancements for OpenStack clouds are available in deployments by
-default. This appendix provides a detailed overview of the most important
+default. This section provides a detailed overview of the most important
 security enhancements.
 
-For more information about configuring security, see
-:deploy_guide:`Appendix H <app-advanced-config-options.html>`.
-
 .. note::
 
    Every deployer has different security requirements.
@@ -33,7 +29,8 @@ certificates, keys, and CA certificates.
 
 To learn more about how to customize the deployment of encrypted
 communications, see
-:deploy_guide:`Securing services with SSL certificates <app-advanced-config-sslcertificates.html>`.
+:deploy_guide:`Securing services with SSL
+certificates <app-advanced-config-sslcertificates.html>`.
 
 Host security hardening
 ~~~~~~~~~~~~~~~~~~~~~~~

doc/source/reference/index.rst

@@ -25,5 +25,6 @@ see the :dev_docs:`Contributors Guide <contributor/index.html>`.
    conventions.rst
    inventory/inventory.rst
    configuration/advanced-config.rst
+   architecture/index.rst
    commands/reference.rst
    upgrades/reference.rst