Skip to content

Latest commit

 

History

History
201 lines (147 loc) · 5.8 KB

quickstart.mkd

File metadata and controls

201 lines (147 loc) · 5.8 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 r10k and its dependencies
  • Configuring all components to support r10k
  • Configuring your git repository and initial files

This document is based around Puppet 4+, specifically using the Puppet Collection repositories provided by Puppet Labs.

Pre-Requisites

  • Clean install of CentOS 7 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 7

Install and enable the official Puppet Labs package repositories.

yum localinstall http://yum.puppetlabs.com/puppetlabs-release-pc1-el-7.noarch.rpm

Clean all yum data and rebuild the metadata cache.

yum clean all && yum makecache

Install the Puppet master.

yum install puppetserver

Installing Puppetmaster on Debian 7

Install and enable the official Puppet Labs package repositories

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

Install the Pupppet master

apt-get install puppetserver

Configuring Puppet

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

[main]
    dns_alt_names = $_Insert FQDN of Puppet Master Here_$

[agent]
    server = $_Insert FQDN of Puppet Master Here_$

Restart the Puppet master service.

service puppetserver restart

Ensure the certificate for the Puppet master was created.

# /opt/puppetlabs/bin/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/puppetlabs/puppet/puppet.conf configuration. To do so you need to remove old certs and restart puppetmaster:

service puppetserver stop
find $(/opt/puppetlabs/bin/puppet master --configprint ssldir) -name "$(/opt/puppetlabs/bin/puppet master --configprint certname).pem" -delete
service puppetserver start

Install and Configure R10k

Install r10k via Ruby Gems.

/opt/puppetlabs/puppet/bin/gem install r10k

Configure r10k by creating the following directory structure and file /etc/puppetlabs/r10k/r10k.yaml and ensuring it has the following contents:

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

# A list of git repositories to create
:sources:
  # This will clone the git repository and instantiate an environment per
  # branch in /etc/puppetlabs/code/environments
  :my-org:
    remote: '[email protected]:$_Insert GitHub Organization Here_$/$_Insert GitHub Repository That Will Be Used For Your Puppet Code Here_$'
    basedir: '/etc/puppetlabs/code/environments'

Configure Puppet Code Repository

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

Note that puppet defaults to the production environment. You may wish to change your default git branch from master to production in order to match this. Alternatively, you can set your agents' environment to master.

mkdir -p {modules,site/profile/manifests,hieradata}
touch hieradata/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 `hieradata/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', '4.1.0'
mod 'puppetlabs/stdlib'

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

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

Ensure that the user r10k runs as (typically root) can access the git repository. See the [git environment guide] (git-environments.mkd) for more detail. You can test the access by using su/sudo to perform git clone yourrepoURL as the correct user.

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 /opt/puppetlabs/puppet/bin/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/puppetlabs/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!