Ansible puppet module

When puppet and ansible work together for better orchestration

Definitions
Description
Requirements
Installation
How to use the puppet ansible module
Development
Documentation
Credits
Licence
References

Definitions

In the following :

the Ansible master is the host where Ansible is installed and where you run your playbooks
the Ansible nodes are the hosts managed by the ansible master

Description

The goals of the ansible puppet module are :

installing Ansible on the ansible master
allowing ssh connections from the ansible master to a pool of ansible nodes
creating an ansible user on all hosts (master and nodes)
allowing the ansible user to run command as root with sudo

The module use public key authentication and manage the /etc/ssh/ssh_known_hosts file of the ansible master.

Requirements

A puppet master with "storeconfigs" enabled, because this module uses exported ressources.

This module is created for Debian (Squeeze/Wheezy) and compatible with puppet agent (> 2.7).

This module use puppetlabs-stdlib (> 4.2.2).

The module has been tested on:

Debian 6
Debian 7

This module could be used on Ubuntu or CentOs (actually Debian and RedHat operating system family), but tests has been light and support cannot be guaranteed.

Installation and upgrade

From the forge, go to nvogel/ansible

Or with Librarian puppet, for example add to your Puppetfile :

  mod 'ansible',
    :git => 'https://github.com/nvogel/puppet-ansible',
    :ref => '3.0.0'

Each version number follows the rules defined by semantic versioning.

You should read the changelog file before upgrading to a new version and use only a tagged version.

How to use the puppet ansible module

Deploy ansible

Puppet side

Imagine you want to install Ansible on a host named master.fqdn.tld.

You can use hiera, an enc, or a plain text manifest.

You can have several ansible master hosts, each one will have its own pool of ansible nodes.

You have to make 2 runs of the puppet agent to complete the configuration process.

Ansible is installed by default with pip.

You can also use the default package provider of the platform, in this case you may have to enable a specific repository where you can find the ansible package (for example wheezy-backport or epel).

Plain text manifest

For the master node :

include ansible

class { 'ansible':
  ensure => master
}

or if you want to use the default (apt/yum) provider

include { 'ansible::master':
  provider => automatic
}

For each ansible node :

class { 'ansible':
  ensure => node,
  master => 'master.fqdn.tld'
}

class { 'ansible::node' :
  master  => 'master.fqdn.tld'
}

Hiera

Example with a pool of hosts named pool1.

Each host have the same value for the fact pool.

There is one host in the pool which is the ansible master (master.fqdn.tld).

hiera.yaml :

---
:backends:
  - yaml
:yaml:
  :datadir: /etc/puppet/%{environment}/hieradata
:hierarchy:
  - "node/%{::clientcert}"
  - "pool/%{::pool}"
  - common

hieradata directory :

hieradata/
├── pool
│   └── pool1.yaml
└── node
    └── master.fqdn.tld.yaml

pool1.yaml :

---
classes: ansible
ansible::ensure: node
ansible::master: master.fqdn.tld

master.fqdn.tld.yaml :

---
ansible::ensure: master
ansible::master: false

Ansible side

On the ansible master host, all you have to do is to use the ansible user. By default, the ansible user is set with a non valid password so you have to be root to use this account.

su - ansible

On the ansible nodes, the only package installed is sudo. So, you may have to deploy additional python packages which are required for some ansible modules.

Upgrade ansible

By default, puppet install the current version of ansible but will not upgrade it if already present.

You can change ansible version by setting the ansible::install::version parameter.

Example with hiera :

Latest version with apt

---
ansible::ensure: master
ansible::master: false
ansible::master::provider: automatic
ansible::install::version: latest

Specific version with pip

---
ansible::ensure: master
ansible::master: false
ansible::install::version: "1.8.2"

Manage playbooks

You can define a directory owned by the user ansible where you can store your playbooks (by default /etc/ansible).

For examples:

---
classes: ansible::playbooks
ansible::ensure: master
ansible::master: false

include ansible::playbooks

Development

Contributing

You're welcome to propose enhancements or submit bug reports (even typos).

When you perform modifications inside the puppet module :

You MUST run the test suite (see Testing section)
You MUST write (or update) the test suite
You MUST update the documentation

Thanks in advance.

Branch management

The master branch corresponds to the release under development. Could be unstable. All stable release are tagged.

Installation

gem install bundler
mkdir modules
cd modules
git clone git://github.com/nvogel/puppet-ansible.git ansible
cd ansible
bundle install --path vendor/bundle

Testing

How to list the available tasks

bundle exec rake

How to run syntax, lint and rspec

bundle exec rake test

How to check the syntax

bundle exec rake syntax

How to lint

bundle exec rake lint

How to run rspec on the manifests

bundle exec rake spec

How to run test automatically when you change any of the manifest

bundle exec guard

Documentation

How to generate the documentation of the module

mkdir -p /tmp/doc/ansible && touch /tmp/doc/manifest
cd /path/to/module/directory/ansible
ln -s "$(pwd)/lib" /tmp/doc/ansible
ln -s "$(pwd)/manifests" /tmp/doc/ansible
#generate module documentation in /path/to/ansible_doc from /tmp/doc
bundle exec puppet doc --charset UTF-8 --outputdir /path/to/ansible_doc --mode rdoc --manifest /tmp/doc/manifest --modulepath /tmp/doc

Credits

Nicolas Vogel
All contributors

Licence

Puppet ansible module is released under the MIT License. Check the LICENSE file for details.

nvogel/puppet-ansible