puppet master deployment doc related to Fuel Infra

Related-Bug: #1510463
Change-Id: I215611fa592d5b6055d39ade1d67ade6b0903635

docs/index.rst

@@ -14,5 +14,6 @@ Table of contents
    infra/jenkins_master_deployment
    infra/jenkins_slave_deployment
    infra/overview
+   infra/puppet_master_deployment
    infra/third_party
    packaging

docs/infra/puppet_master_deployment.rst

@@ -0,0 +1,128 @@
+Puppet Master
+=============
+
+Puppet is a tool which provides ability to manage configuration of systems in an
+automatic way using the declarative language. The so called 'manifests' are
+used for describing particular system configuration.
+
+Deployment
+----------
+
+In order to install Puppet Master on the brand new server running Ubuntu please
+proceed with the following steps:
+
+#. Install Ubuntu 14.04 with SSH service and set FQDN to puppet-master.test.local
+
+#. Install git and clone Puppet Manifests repository into /etc/puppet directory:
+
+   .. code-block:: console
+
+     apt-get install -y git
+     git clone https://github.com/fuel-infra/puppet-manifests.git /etc/puppet
+
+#. Execute the Puppet Master's install script:
+
+   .. code-block:: console
+
+     /etc/puppet/bin/install_puppet_master.sh
+
+The script does the following:
+
+* upgrades all packages on the system
+* installs required puppet modules
+* installs Puppet Master packages
+* runs puppet apply to setup Puppet Master
+* runs puppet agent to do a second pass and verify if installation is usable
+
+When script finishes successfully, the Puppet Master installation is completed.
+
+-----------
+Using Hiera
+-----------
+
+Puppet can use Hiera to look for data. Hiera allows to override manifest
+parameter values during the deployment, thus it is possible to create
+a specific data configuration for easier code re-use and easier management of
+data that needs to differ across nodes.
+All related Hiera structure is placed under the ``/var/lib/hiera`` directory.
+
+The Hiera hierarchy
+-------------------
+
+    #. common.yaml - the most general,
+    #. locations/%{::location}.yaml - can override common's data,
+    #. roles/%{::role}.yaml - can override location's and common's data
+    #. nodes/%{::clientcert}.yaml - can override data specified in common,
+       location and role.
+
+The ``common`` and ``nodes`` are used within every deployment when exist. But in
+contrast, the ``location`` and ``role`` needs to be passed explicitly as a
+variable within ``puppet agent`` run, in order to use them. An example:
+
+   .. code-block:: console
+
+     FACTER_ROLE=websrv FACTER_LOCATION=us1 puppet agent -tvd
+
+To include puppet's class in a role, it is required to use the ``classes``
+keyword on the role's beginning. An example:
+
+   .. code-block:: ini
+
+     ---
+     classes:
+       - '::class1::class2'
+
+.. note::
+   avoid including classes in more than one place since this will lead to
+   duplicate class declaration error.
+
+Other example - create a role's stub for 'docker_registry' module and make
+sure that each of the nodes running that role have its own, custom, service's
+FQDN set in Nginx's Vhost.
+
+#. File 'roles/docker_registry.yaml'
+
+   .. code-block:: ini
+
+     ---
+     classes:
+       - '::docker_registry'
+       - '::fuel_project::nginx'
+       - '::fuel_project::apps::firewall'
+       - '::fuel_project::common'
+
+     docker_registry::service_fqdn: '%{::fqdn}'
+
+#. File 'nodes/srv01-us.infra.test.local.yaml'
+
+   .. code-block:: ini
+
+     ---
+
+     docker_registry::service_fqdn: 'registry-us1.infra.test.local'
+
+#. File 'nodes/srv01-cz.infra.test.local.yaml'
+
+   .. code-block:: ini
+
+     ---
+
+     docker_registry::service_fqdn: 'registry-cz1.infra.test.local'
+
+On a ``srv01-us.infra.test.local`` node, during the deployment of a
+``docker_registry`` role, a default value for ``service_fqdn`` class parameter
+has been overridden.
+
+After the deployment using FACTER variable a facter file is created containing
+the used FACTERs variables. For instance:
+
+   .. code-block:: console
+
+     cat /etc/facter/facts.d/facts.sh
+     #!/bin/bash
+
+     echo "location=us1"
+     echo "role=docker_registry"
+
+Having these, now every next puppet agent run will not require ``FACTER`` variables
+to be passed (if no role nor location is to be changed).