# Overview

This intent of this document is to serve as a basic guide for getting started with r10k and a fresh Puppet installation, including the following:

* Installing Puppet and its dependencies
* Installing Hiera and its dependencies.
* Installing r10k and its dependencies
* Configuring all components to support r10k
* Configuring your git repository and initial files

# Pre-Requisites

* Clean install of CentOS 6.5 or Debian 7.0 with root access / sudo rights. 
* Clean github repository with a deploy key generated by the server above.

# Installing Puppetmaster on Centos 6.5

Install and enable the official Puppet Labs package repositories.

```
rpm -ivh http://yum.puppetlabs.com/puppetlabs-release-el-6.noarch.rpm
```

Clean all yum data and rebuild the metadata cache.

```
yum clean all && yum makecache
```

Install the Puppet master.

```
yum install puppet-server
```

# Installing Puppetmaster on Debian 7

Install and enable the official Puppet Labs package repositories

```
wget http://apt.puppetlabs.com/puppetlabs-release-wheezy.deb
dpkg -i puppetlabs-release-wheezy.deb
apt-get update
```

Install the Pupppet master
```
apt-get install puppetmaster-passenger=3.7.1-1puppetlabs1
```
Above command will install 3.7.1-1puppetlabs but there are many versions to choose. To see available versions run: apt-cache show puppetmaster-passenger|grep ^Version

# Configuring Puppet 

Configure the Puppet master by editing `/etc/puppet/puppet.conf` and ensuring it has the following contents:

```
[main]
    # The Puppet log directory.
    # The default value is '$vardir/log'.
    logdir = /var/log/puppet

    # Where Puppet PID files are kept.
    # The default value is '$vardir/run'.
    rundir = /var/run/puppet

    # Where SSL certificates are kept.
    # The default value is '$confdir/ssl'.
    ssldir = $vardir/ssl

    dns_alt_names = $_Insert FQDN of Puppet Master Here_$

    environmentpath = $confdir/environments

[agent]
    # The file in which puppetd stores a list of the classes
    # associated with the retrieved configuratiion.  Can be loaded in
    # the separate ``puppet`` executable using the ``--loadclasses``
    # option.
    # The default value is '$confdir/classes.txt'.
    classfile = $vardir/classes.txt

    # Where puppetd caches the local configuration.  An
    # extension indicating the cache format is added automatically.
    # The default value is '$confdir/localconfig'.
    localconfig = $vardir/localconfig

    server = $_Insert FQDN of Puppet Master Here_$
```

Restart the Puppet master service.

```
service puppetmaster restart
```

Ensure the certificate for the Puppet master was created.

```
# puppet cert list --all

+ "puppet-master.domain.local" (SHA256) 3F:F3:63:BB:EE:57:46:A4:7B:03:AB:9D:FD:97:0F:8F:73:87:40:3B:6D:E5:DC:FC:C3:49:F5:C9:B6:F4:DE:B8 (alt names: "DNS:puppet-master.domain.local")
```

Notice for Debian users: apt post-configure will build the certificate for the server BEFORE you configure it. Therefore you should rebuild your certs after done with /etc/puppet/puppet.conf configuration.
To do so you need to remove old certs and restart puppetmaster:
```
service puppetmaster stop
find $(puppet master --configprint ssldir) -name "$(puppet master --configprint certname).pem" -delete
puppet master --no-daemonize --verbose
```

# Install and Configure R10k

Install r10k via Ruby Gems.

```
gem install r10k
```

Configure r10k by editing `/etc/r10k.yaml` and ensuring it has the following contents:

```
# The location to use for storing cached Git repos
:cachedir: '/var/cache/r10k'

# A list of git repositories to create
:sources:
  # This will clone the git repository and instantiate an environment per
  # branch in /etc/puppet/environments
  :my-org:
    remote: 'git@github.com:$_Insert GitHub Organization Here_$/$_Insert GitHub Repository That Will Be Used For Your Puppet Code Here_$'
    basedir: '/etc/puppet/environments'
```
# Install and Configure Hiera

Hiera is installed as part of the Puppet master installation.

Configure Hiera by editing `/etc/hiera.yaml` and ensuring it has the following contents:

```
---
:backends:
  - yaml
:hierarchy:
  - "nodes/%{fqdn}"
  - common

:yaml:
   :datadir: /etc/puppet/environments/%{environment}/hiera
```

Create a symlink to the Hiera configuration in the Puppet directory.

```
ln -s /etc/hiera.yaml /etc/puppet/hiera.yaml
```

# Configure Puppet Code Repository

Populate the repository by cloning it locally and performing each of the following actions within it:

```
mkdir -p {modules,site/profile/manifests,hiera}
touch hiera/common.yaml
touch site/profile/manifests/base.pp
touch environment.conf
touch Puppetfile
touch site.pp
```

Edit the `environment.conf` file and ensure it has the following contents:

```
manifest = site.pp
modulepath = modules:site
```

Edit the `site.pp` file and ensure it has the following contents:

```
hiera_include('classes')
```

Edit the `hiera/common.yaml file and ensure it has the following contents:

```
---
classes:
 - 'profile::base'

ntp::servers:
  - 0.us.pool.ntp.org
  - 1.us.pool.ntp.org
```

Edit the `Puppetfile` file and ensure it has the following contents:

```
forge 'forge.puppetlabs.com'

# Forge Modules
mod 'puppetlabs/ntp', '3.0.3'
mod 'puppetlabs/stdlib'
```

Edit the `site/profile/manifests/base.pp` file and ensure it has the following contents:

```
class profile::base {
  class { '::ntp': }
}
```

# Summary

We now have the following functional pieces:

1. Puppet master
2. Hiera
3. r10k
4. Puppet code repository
5. Initial 'profile' named 'base' that will configure NTP on our servers.

This base will allow us to do all sorts of useful things. Most interesting (to me and for the purposes of this tutorial) is the ability to now utilize Git branches to help manage infrastructure as part of your software development lifecycle. Now, when you want to test a new profile, you can do the following:

1. Create a new branch of the Puppet code repository
2. Create your Puppet code in this new branch
3. Push the new branch up to the repository
4. Deploy it as a new environment using the `r10k deploy environment -p` command.

From any agent node (including the master), you may run the agent against the new environment by specifying it on the command line. For example, if you create the branch `test`, run puppet as:
```
puppet agent -t --environment test
```
You can also modify the `/etc/puppet/puppet.conf` file on a node and add the environment setting to the agent section to make the change permanent:
```
...
[agent]
environment = test
```
Voila - you're testing code without impacting your production environment!