4 changes: 4 additions & 0 deletions CHANGELOG
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
2.7.1 - Alex Scoble & esalberg & annaken
* Fix webhook directory permissions #144
* Fix gem dep regression #154
* Update gem version for pulled release.
2.7.0 - Zack Smith
* Updates for Puppet Enterprise 3.8 and its embeded r10k
* Update default r10k version with that which will ship in PE 3.8
Expand Down
255 changes: 197 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,27 +3,38 @@
[![Github Tag](https://img.shields.io/github/tag/acidprime/r10k.svg)](https://github.com/acidprime/r10k)
[![Build Status](https://travis-ci.org/acidprime/r10k.png?branch=master)](https://travis-ci.org/acidprime/r10k)

This is the r10k setup module. It has a base class to configure r10k to
synchronize [dynamic environments](https://github.com/adrienthebo/r10k/blob/master/doc/dynamic-environments.mkd). You can be simply used by declaring it:
#### Table of Contents

```puppet
class { 'r10k':
remote => 'git@github.com:someuser/puppet.git',
}
```
1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
3. [Setup - The basics of getting started with r10k](#setup)
* [What r10k affects](#what-r10k-affects)
* [Setup requirements](#setup-requirements)
* [Beginning with r10k](#beginning-with-r10k)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)

Installing into the puppet enterprise ruby stack
```puppet
class { 'r10k':
remote => 'git@github.com:someuser/puppet.git',
provider => 'pe_gem',
}
```
Note: On Puppet Enterprise 3.8 and higher the package is not declared as 3.8
ships with an embdedded r10k gem installed via the PE packages
## Overview

This module was built to install and configure r10k. It has a base class to configure r10k to
synchronize [dynamic environments](https://github.com/adrienthebo/r10k/blob/master/doc/dynamic-environments.mkd).
It also has a series of lateral scripts and tools that assist in general workflow, that will be seperated into
their own modules into the future.

## Module Description

This module is meant to manage the installation and configuration of r10k using multiple installation methods on multiple platforms.

## Setup

Please refer to the official [r10k docs](https://github.com/puppetlabs/r10k/tree/master/doc) for specific configuration patterns.

### Prefix Example
Instead of passing a single `remote`, you can pass a puppet [hash](https://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#hashes) as the `sources`
parameter. This allows you to configure r10k with [prefix](https://github.com/puppetlabs/r10k/blob/910709a2924d6167e2e53e03d64d2cc1a64827d4/doc/dynamic-environments/configuration.mkd#prefix) support. This often used when multiple teams use seperate repos, or if hiera and puppet are distributed across two repos.

### Prefixes
Installing using prefixes for multiple control repos.
```puppet
class { 'r10k':
sources => {
Expand All @@ -40,9 +51,20 @@ class { 'r10k':
},
}
```
### What r10k affects

* Installation of the r10k `gem`
* Installation of git
* Installation of ruby when not using an existing ruby stack i.e. when using `pe_gem`
* Installation of ruby if not using an existing ruby stack i.e. when using `pe_gem`.
* Management of the `r10k.yaml` in /etc
* Instllation and configuration of a sinatra app when using the [webhook](#webhook-support).


## Version chart
#### Version chart

Gem installation is pinned to a default version in this module, the following chart shows the gem installation tested with the respective module version.
You can override this by passing the `version` parameter.

| Module Version | r10k Version |
| -------------- | ------------ |
Expand All @@ -56,11 +78,16 @@ class { 'r10k':
| v2.2.8 | 1.3.1 |
| v2.2.x | 1.1.0 |

This will configure `/etc/r10k.yaml` and install the r10k gem after installing
ruby using the [puppetlabs/ruby](http://forge.puppetlabs.com/puppetlabs/ruby) module.

### Setup Requirements

r10k connects via ssh and does so silently in the background, this typically requires ssh keys to be deployed in advance of configuring
r10k. This includes the known host ( public ) key of the respective git server, and the user running r10k's private key used to authenticate
git/ssh during background runs.

Here is an example of deploying the ssh keys needed for r10k to connect to a repo called puppet/control on a gitlab server.
This is helpful when you need to automatically deploy new masters

```puppet
#https://docs.puppetlabs.com/references/latest/type.html#sshkey
sshkey { "your.internal.gitlab.server.com":
Expand All @@ -81,48 +108,38 @@ git_deploy_key { 'add_deploy_key_to_puppet_control':
provider => 'gitlab',
}
```
A simple example of creating a ssh private key would using an exec to call `yes y | ssh-keygen -t dsa -C "r10k" -f /root/.ssh/id_dsa -q -N ''`.
The example above shows using `git_deploy_key` which would deploy that key to the remote git server via its api. This is often required in the programtic creation of compile masters.

Given r10k will likely be downloading your modules, often on the first server
its ran on you will have to puppet apply this module to bootstrap this
configuration and allow for ongoing management from there.

## Helper classes
It also has a few helper classes that do
some useful things. The following entry in Hiera will add a `postrun_command` to puppet.conf.

```
r10k::include_postrun_command: true
```

The concept here is that this is declared on the puppet master(s) that have
been configured with r10k. This will cause r10k to synchronize before each
puppet run. Any errors synchronizing will be logged to the standard puppet run.

This module requires the [puppetlabs-ruby](https://github.com/puppetlabs/puppetlabs-ruby.git) module. In the event that your environment already includes
the module with some customization, you can use the `manage_ruby_dependency`
parameter to adjust how this module expresses that requirement.
The supported values are `include`,`declare`, or `ignore`. The values' behavior
is outlined below:
### Beginning with r10k

* *declare* **default** This will explicitly declare the ruby module.
Additional declarations of the ruby module will result in an inability to
compile a catalog.

* *include* This will simply include the ruby module. When combined with class
ordering, this will permit the user to manage the instantiation of the ruby module elsewhere, potentially with non-standard parameter values.
The simplest example of using it would to declare a single remote that would be written to r10k.yaml.

* *ignore* This will assume that ruby is handled via some other mechanism than
a puppet module named `ruby`. It is left to the user to insure the
requirement be met.
```puppet
class { 'r10k':
remote => 'git@github.com:someuser/puppet.git',
}
```
This will configure `/etc/r10k.yaml` and install the r10k gem after installing
ruby using the [puppetlabs/ruby](http://forge.puppetlabs.com/puppetlabs/ruby) module.

## symlink to r10k.yaml
These entries in Hiera will create a symlink at `/etc/r10k.yaml` that points to the config file at `/etc/puppet/r10k.yaml`
It also supports installation via multiple providers, such as installation in the puppet_enterprise ruby stack in versions less than 3.8

```yaml
---
r10k::configfile: /etc/puppet/r10k.yaml
r10k::manage_configfile_symlink: true
r10k::configfile_symlink: /etc/r10k.yaml
Installing into the puppet enterprise ruby stack
```puppet
class { 'r10k':
remote => 'git@github.com:someuser/puppet.git',
provider => 'pe_gem',
}
```
_Note: On Puppet Enterprise 3.8 and higher the package is not declared as 3.8
ships with an embdedded r10k gem installed via the PE packages_

## Example installs
## Usage

Installing using a proxy server

Expand Down Expand Up @@ -206,6 +223,15 @@ class { 'r10k':
}
```

The mcollective agent can be configured to supply r10k/git environment `http_proxy`, `https_proxy` variables via the following example

```puppet
class { '::r10k::mcollective':
http_proxy => 'http://proxy.example.lan:3128',
git_ssl_verify => 1,
}
```

### Mcollective Support
![alt tag](http://imageshack.com/a/img674/3070/NWvnSn.png)

Expand Down Expand Up @@ -290,8 +316,6 @@ For version control systems that use web driven post-receive processes you can u
This webhook currently only runs on Puppet Enterprise and uses mcollective to automatically synchronize your environment across multiple masters.
The webhook must be configured on the respective "control" repository a master that has mco installed and can contact the other masters in your fleet.

Currently this is a feature Puppet Enterprise only.

### Webhook Github Enterprise - Non Authenticated
This is an example of using the webhook without authentication
The `git_webhook` type will using the [api token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to add the webhook to the "control" repo that contains your puppetfile. This is typically useful when you want all automate the addtion of the webhook to the repo.
Expand Down Expand Up @@ -447,7 +471,122 @@ git_webhook { 'web_post_receive_webhook' :
```
### Webhook FOSS support

Currently the webhook relies on existing certificates for its ssl configuration.
See this following [ticket](https://github.com/acidprime/r10k/issues/140) for more information.
Until then , its possible to re-use you existing FOSS mcollective certificates.

Here is an working example on Ubuntu 14.04.2 LTS

```puppet
class { '::r10k::webhook::config':
protected => false,
public_key_path => '/etc/mcollective/server_public.pem', # Mandatory for FOSS
private_key_path => '/etc/mcollective/server_private.pem', # Mandatory for FOSS
notify => Service['webhook'],
}
class { '::r10k::webhook':
user => 'puppet', # Mandatory for FOSS
group => 'puppet', # Mandatory for FOSS
require => Class['::r10k::webhook::config'],
}
```
## Reference

####Class: `r10k`
This is the main public class to be declared , handingly installation and configuration declarations

**Parameters within `r10k`:**

##### `remote`
A string to be passed in as the source with a hardcode prefix of `puppet`

##### `sources`
A hash of all sources, this gets read out into the file as yaml. Must not be declared with `remote`

##### `purgedirs`
A single string setting the `r10k.yaml` configuration value of the same name

##### `cachedir`
A single string setting the `r10k.yaml` configuration value of the same name

##### `configfile`
A path to the configuration file to manage. Be aware Puppet Enterprise 4.0 and higher may conflict if you manage `/etc/puppetlabs/puppet/r10k.yaml`

##### `version`
A value passed to the package resource for managing the gem version

##### `modulepath`
Deprecated: for older [configfile](https://docs.puppetlabs.com/puppet/latest/reference/environments_classic.html) environments configuration of modulepath in puppet.conf

##### `manage_modulepath`
Deprecated: declare a resource for managing `modulepath` in Puppet.conf

##### `manage_ruby_dependency`
When using system ruby , options on how to declare

##### `r10k_basedir`
This module requires the [puppetlabs-ruby](https://github.com/puppetlabs/puppetlabs-ruby.git) module. In the event that your environment already includes
the module with some customization, you can use the `manage_ruby_dependency`
parameter to adjust how this module expresses that requirement.
The supported values are `include`,`declare`, or `ignore`. The values' behavior
is outlined below:

* *declare* **default** This will explicitly declare the ruby module.
Additional declarations of the ruby module will result in an inability to
compile a catalog.

* *include* This will simply include the ruby module. When combined with class
ordering, this will permit the user to manage the instantiation of the ruby module elsewhere, potentially with non-standard parameter values.

* *ignore* This will assume that ruby is handled via some other mechanism than
a puppet module named `ruby`. It is left to the user to insure the
requirement be met.
##### `package_name`
The name of the package to be installed via the provider

##### `provider`
The supported installation modes for this module

* portage
* yum
* bundle
* pe_gem
* gem
* zypper

##### `gentoo_keywords`
See `r10k::install::portage` class for more information

##### `install_options`
Options to pass to the `provider` declaration

##### `mcollective`
Install mcollective application and agents. This does NOT configure mcollective automatically

##### `manage_configfile_symlink`
Manage a symlink to the configuration file, for systems installed in weird file system configurations

##### `configfile_symlink`
boolean if to manage symlink

##### `include_prerun_command`
Deprecated: Add [prerun_command](https://docs.puppetlabs.com/references/latest/configuration.html#preruncommand) to puppet.conf to run r10k when the agent on the master runs.
Suggest instead declaring `r10k::postrun_command ` as that will run after the agent runs which prevents r10k from stopping configuration management of masters from occuring as it does with `prerun_command`s

##### `include_postrun_command`
```
r10k::include_postrun_command: true
```

The concept here is that this is declared on the puppet master(s) that have
been configured with r10k. This will cause r10k to synchronize after each
puppet run. Any errors synchronizing will be logged to the standard puppet run.

## Limitations
This module is likely going to be broken up into 2/3 modules i.e. r10k_webhook, r10k_mcollective in the future. Puppet Enterprise 4.0 will likely being shipping its own configuration module for r10k and so this module will migrate to managing FOSS installations i.e. `/etc/r10k.yaml` vs PE's configuration file `/etc/puppetlabs/puppet/r10k.yaml`. As of PE 3.8 you can still use this module to manage the `/etc/r10k.yaml` file and it will be loaded but package/version management of r10k and its symlinks has been disabled to not conflict with the pe packages ability to install and upgrade the gem as part of Puppet Enterprise.


##Support
Expand All @@ -466,7 +605,7 @@ Read the complete module [contribution guide](https://docs.puppetlabs.com/forge/

###Running tests

This project contains tests for both [rspec-puppet](http://rspec-puppet.com/) and [beaker-rspec](https://github.com/puppetlabs/beaker-rspec) to verify functionality. For in-depth information please see their respective documentation.
This project contains tests for [rspec-puppet](http://rspec-puppet.com/) to verify functionality. For in-depth information please see their respective documentation.

Quickstart:

Expand Down
15 changes: 8 additions & 7 deletions manifests/init.pp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,22 @@
$manage_configfile_symlink = $r10k::params::manage_configfile_symlink,
$configfile_symlink = $r10k::params::configfile_symlink,
$include_prerun_command = false,
$include_postrun_command = false,
) inherits r10k::params {

$ruby_dependency_options=['include','declare','ignore']
validate_re($manage_ruby_dependency,$ruby_dependency_options)
if is_string($include_prerun_command) {
$include_prerun_command_real = str2bool($include_prerun_command)
} else {
$include_prerun_command_real = $include_prerun_command
}
validate_bool($include_prerun_command_real)

if $include_prerun_command_real == true {
# TODO: Clean this up when 3.0 to require a boolean
if $include_prerun_command == true or $include_prerun_command == 'true'{
include r10k::prerun_command
}

if $include_postrun_command == true or $include_postrun_command == 'true'{
include r10k::postrun_command
}


class { 'r10k::install':
install_options => $install_options,
keywords => $gentoo_keywords,
Expand Down
2 changes: 1 addition & 1 deletion manifests/install/pe_gem.pp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Puppet Enterprise 3.8 ships code to manage this symlink on install
# This conditional should not effect FOSS customers based on the fact
unless versioncmp($::pe_version, '3.8.0') >= 0 {
unless versioncmp($::pe_version, '3.8.0') >= 0 {
file { '/usr/bin/r10k':
ensure => link,
target => '/opt/puppet/bin/r10k',
Expand Down
Loading