Issue 122 - Puppet ENC via Hiera

README.md

Index: README.md
===================================================================
--- a/README.md
+++ b/README.md
@@ -6,17 +6,46 @@
 
 Our Puppet manifests are only tested with Ubuntu 12.04 right now.
 
-Private files
--------------
+Host specific setup

[Felix Dahlke, 2015/03/03 16:43:32]

Is that really "Host specific"? You're calling servers "hosts" below, so IMO
this is a bit confusing. Maybe something like "Environment specific setup"? Or
just "Private files" or maybe "Private resources"? :)

[mathias, 2015/03/04 12:32:37]

Done.

+-------------------
 
-Some parts of our infrastructure are, obviously, confidential. We have
-htpasswd files, SSH keys and SSL certificates that we need to be
-careful with.
+Some infrastructure parts are specific to the environment (such as e.g.
+*development*, *test* and *production*) whilst passwords, for example,
+are confidential. In order to allow for such specific configuration, the
+repository requires a set of manual operations during the initial setup:
 
-That's why _modules/private_ is missing, and needs to be placed there
-manually. We provide stub versions of all those files in
-_modules/private-stub_, so just linking or copying that to
-_modules/private_ will make everything work locally.
+### `modules/private`
+
+The `private` module is destined to store confidential information such as
+[RSA](http://en.wikipedia.org/wiki/RSA_%28cryptosystem%29) keys, `htpasswd`
+files and so on. The repository provides a `private-stub` module containing
+defaults suitable for development and testing purpose. One can create a
+symbolic link to start using the resource:
+
+    # UNIX-oid

[Felix Dahlke, 2015/03/03 16:43:32]

Why the "-old" here?

Also, I would go for something like a #### headline instead of code comments
here. Also because "#" doesn't introduce a comment in batch scripts, so it
doesn't really make sense for the Windows part below.

[Wladimir Palant, 2015/03/03 20:00:19]

I guess using "Unix-like" will avoid that confusion...

[mathias, 2015/03/04 12:32:37]

Done.

+    user@host:~/infrastructure$ ln -s private-stub modules/private

[Felix Dahlke, 2015/03/03 16:43:32]

I'd opt for just having `$ ln -s private-stub modules/private` - the rest of the
prompt doesn't matter, and it's quite customary to leave it out.

[mathias, 2015/03/04 12:32:37]

Done.

+
+    # Windows
+    C:\infrastructure\> MKLINK /D modules\private private-stub
+
+When creating a custom version, one may inspect the `modules/private-stub`
+directory to determine which resources have to be provided.
+
+### `hiera/private`
+
+Analogous to `modules/private`, [Hiera](https://docs.puppetlabs.com/hiera/1/)
+configuration files specific to the current environment are expected to be
+found in `hiera/private`. Default resources for development (and testing)
+purpose are provided within `modules/private-stub/hiera`:
+
+    # UNIX-oid
+    user@host:~/infrastructure$ ln -s ../modules/private-stub/hiera hiera/private
+
+    # Windows
+    C:\infrastructure\> MKLINK /D ..\modules\private-stub\hiera hiera\private
+
+Note that custom versions are recommended to be tracked together with the
+custom `private` module, if any.
 
 Development environment
 -----------------------
@@ -33,7 +62,7 @@
 
 * [VirtualBox](https://www.virtualbox.org/)
 * [Vagrant](http://vagrantup.com/)
-* _modules/private_ exists (see above)
+* Both `modules/private` and `hiera/private` exist (see above)
 
 ### Start a VM
 
@@ -64,24 +93,30 @@
 
 The default password for this user (required for the _sudo_ command) is "test".
 
-Adding a server
----------------
+Adding a host
+-------------
 
-To set up a new server, you should first add it to the development
-environment and test the setup, then set up a corresponding production
-server.
+To set up a new host, extend the custom `hiera/private/host.yaml` by another
+`servers:` item, e.g.:
 
-### Development environment
+    # ...
+    custom1:
+        ip: [10.8.0.254]
+        dns: foobar.example.com
+        ssh_public_key: AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAA...
+        role: codereviewserver
 
-1. Add entries in _Vagrantfile_ and _manifests/vagrant.pp_
+See `modules/base/manifests/init.pp`, especially the `explicit_host_record()`
+named type within class `base`, for more information on the possible option
+keys and values.
 
-2. Add the host name to one of the manifests imported by
-_manifests/nodes.pp_
+Configuring Puppet

[Felix Dahlke, 2015/03/03 16:43:32]

This part of "Adding a host", so it should rather be a ### headline I'd say.

[mathias, 2015/03/04 12:32:37]

Not exclusively, it also applies to the master. Nonetheless I've extended the
above section, and updated this one. That should improve it in the sense of your
comment.

+------------------
 
-3. Make sure the server uses the _nagios::client_ class and add a
-_nagios\_host_ to _manifests/monitoringserver.pp_
+Below please find brief instructions for setting up Puppet on both master

[Felix Dahlke, 2015/03/03 16:43:32]

Sounds awfully formal and doesn't really add anything IMO, I'd just get rid of
this paragraph :)

[mathias, 2015/03/04 12:32:37]

Done.

+and agents:
 
-### Production environment
+### Prerequisites
 
 1. Install Ubuntu Server 12.04 LTS
 2. Perform an update and install Puppet