Skip to content

Latest commit

 

History

History
241 lines (177 loc) · 6.5 KB

quickstart.mkd

File metadata and controls

241 lines (177 loc) · 6.5 KB
Raw

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: '[email protected]:$_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!