The mcoconfig module

Table of Contents

1. Overview
2. Module Description
3. What mcoconfig affects
4. Beginning with mcoconfig
5. Usage
6. Reference
7. Limitations
8. Development

Overview

The mcoconfig module is a helper module that works with the puppetlabs-mcollective module to install MCollective onto Puppet nodes.

Module Description

MCollective is an orchestration tool that can manage administrative functions across a range of servers. MCollective requires a middleware server where other servers and clients publish and subscribe to messages.

The Puppetlabs MCollective module manages the MCollective packages and configuration files.

This module assumes that the Puppet master will act as the MCollective middleware server. It installs and configures ActiveMQ on the Puppet master and uses the puppet CA to create and manage private keys and certificates. It uses the Puppet file server to distribute the keys and certificates to the other MCollective servers and clients.

What mcoconfig affects

• Generates private keys and certificates within the Puppet CA.
• Copies private keys and certificates into its own areas on the Puppet file server.
• Installs and configures ActiveMQ on the middleware node (usually the Puppet master) alongside MCollective.
• Configures the root user on the Puppet master to be an MCollective client.
• Can install the MCollective server on nodes.
• Can configure additional MCollective clients on nodes.

Beginning with mcoconfig

Some manual steps are required on the Puppet master.

Configure agent

If you are not running an agent on the Puppet master, install the Puppet agent package:

apt-get install -y puppet

Add the agent configuration to the end of /etc/puppet/puppet.conf:

[agent]
    server = puppet.domain.com
    environment = production

Then run the agent in test mode to check that the configuration works:

puppet agent -tv --noop

The --noop argument will ensure that the agent will not apply any configuration to the Puppet master inadvertently. Please make sure that the agent will not run any manifests that might adversely affect the operation of the Puppet master. In particular, please review any configuration that you apply to all nodes.

To start the agent, edit /etc/defaults/puppet and changing the START variable to yes:

START=yes

Then launch the agent in the background:

puppet agent

However, I recommend continuing to run the agent in the foreground until MCollective is up and running correctly.

Configure Puppet file server

This module uses the Puppet file server to distribute keys and certificates to nodes.

Add these mount points to /etc/puppet/fileserver.conf:

[mco_shared]
    path /etc/puppet/mco_files/shared
    allow *

[mco_clients]
    path /etc/puppet/mco_files/clients
    allow *

[mco_private]
    path /etc/puppet/mco_files/private/%H
    allow *

Edit /etc/puppet/auth.conf, find the path /file line and add these permissions for the mount points before it:

path ~ ^/file_(metadata|content)/mco_shared/
auth yes
allow *

path ~ ^/file_(metadata|content)/mco_clients/
auth yes
allow *

path ~ ^/file_(metadata|content)/mco_private/([^/]+)/
auth yes
allow $1

Install the module

Install the module on the Puppet master:

puppet module install dmcnicks-mcoconfig

Create a manifest

Add the following code to a manifest that will be applied to the Puppet master:

$mcollective_password = hiera("mcoconfig::mcollective_password")
$admin_password = hiera("mcoconfig::admin_password")
$keystore_password = hiera("mcoconfig::keystore_password")
$mcollective_plugins = hiera_array("mcoconfig::mcollective_plugins")

class { "mcoconfig::middleware":
    mcollective_password => $mcollective_password,
    admin_password => $admin_password,
    keystore_password => $keystore_password
    mcollective_plugins => $mcollective_plugins
}

Create data in Hiera

Add the following data to a Hiera file that will apply to the Puppet master:

mcoconfig::mcollective_password: "NNNNNNNN"
mcoconfig::admin_password: "MMMMMMMM"
mcoconfig::keystore_password: "OOOOOOOO"
mcoconfig::mcollective_plugins:
    - "package"
    - "puppet"
    - "service"
    - "shell"

Run the agent

Run the Puppet agent manually once more:

puppet agent -tv

If everything has been set up correctly you should be able to run the following on the Puppet master as the root user:

mco ping

And see something like the following:

puppet.domain.com                       time=99.52 ms


---- ping statistics ----
1 replies max: 99.52 min: 99.52 avg: 99.52 

Usage

The main entry points into the module are the mcoconfig class and the mcoconfig::puppetmaster class:

• The mcoconfig class will configure nodes as MCollective masters.

• The mcoconfig::puppetmaster class contains additional configuration to set up the file server structure, create and distribute certificates, install and configure ActiveMQ and configure the root user as an MCollective client.

There are also two defined types available that are used to configure new clients:

• The mcoconfig::addclient defined type can be called on the Puppet master to create and distribute certificates for new clients.

• The mcoconfig::user defined type can be called by other nodes to configure a user as a client and collect the required certificates from the Puppet master.

Every node that a client wishes to connect to must have a copy of the client certificate. When mcoconfig::addclient is called, a copy of the new client certificate will be placed on the file server where the other nodes will automatically collect it on their next agent run.

This means that there will be a period of time after the client configuration is added to the Puppet master and the client node when the client will not be recognised.

Apply to all nodes

If you use the roles and profiles metaphor you can create a single profile for MCollective that can be applied to all nodes:

class profiles::mcollective () {

    $middleware_node = hiera("profiles::mcollective::middleware_node")
    $mcollective_password = hiera("profiles::mcollective::mcollective_password")
    $admin_password = hiera("profiles::mcollective::admin_password")
    $keystore_password = hiera("profiles::mcollective::keystore_password")
    $mcollective_plugins = hiera_array("profiles::mcollective::mcollective_plugins")

    if $middleware_node == $::fqdn {

        class { "mcoconfig::puppetmaster":
            mcollective_password => $mcollective_password,
            admin_password => $admin_password,
            keystore_password => $keystore_password,
            mcollective_plugins => $mcollective_plugins
        }

    } else {

        class { "mcoconfig":
            middleware_node => $middleware_node,
            mcollective_password => $mcollective_password,
            mcollective_plugins => $mcollective_plugins
        }
    }
}

Then you can add the profile to the default role:

class roles::default () {

    include profiles::mcollective
}

And then add all of the MCollective data to the common Hiera level:

hiera_level: "common"
classes: "roles::default"

profiles::mcollective::middleware_node: "puppet.domain.com"
profiles::mcollective::mcollective_password: "AAAAAAAA"
profiles::mcollective::admin_password: "BBBBBBBB"
profiles::mcollective::keystore_password: "CCCCCCCC"
profiles::mcollective::mcollective_plugins:
    - "package"
    - "puppet"
    - "service"
    - "shell"

Add new clients

If you want to add new clients, configuration will need to be added in two places. The Puppet master will need to create the required keys and certificates and the node the client is for will need the configuration files created.

It make sense to do all of the Puppet master configuration in the one place so a profile can be used. For example:

class profiles::mco_clients {

    mcoconfig::addclient { "gitlab.domain.com":
        username => "git"
    }

    mcoconfig::addclient { "app1_webserver.domain.com":
        client_fqdn => "webserver.domain.com",
        username => "app1"
    }

    mcoconfig::addclient { "app2_webserver.domain.com":
        client_fqdn => "webserver.domain.com",
        username => "app2"
    }
}

The first resource in this example creates a key and certificate for the git user on gitlab.domain.com. The other two show how to create multiple clients on the same node. The name of the defined type has to be unique so you can join the username and hostname there, then specify a separate client_fqdn parameter.

Each client node will also require configuration. Continuing with the example, the following would have to be added to the gitlab node:

mcoconfig::user { "git": }

And the following would have to be added to the web server node:

mcoconfig::user { "app1": }
mcoconfig::user { "app2": }

Alternatively:

mcoconfig::user { [ "app1", "app2" ]: }

Reference

The mcoconfig class

The mcoconfig class configures a node to become an MCollective server.

Parameters

middleware_node

String: required. The fully qualified domain name of the node that is running the ActiveMQ middleware. This will most likely be the Puppet master.

mcollective_password

String: required. The password for the mcollective user in ActiveMQ. This is the username that the MCollective servers and clients will use to connect to ActiveMQ.

mcollective_plugins

Array of strings: required. An array of MCollective plugins that should be installed and enabled on servers.

The mcoconfig::puppetmaster class

The mcoconfig::puppetmaster class configures the Puppet master to run as the MCollective middleware server. The Puppet CA is used to create the required private keys and certificates. The Puppet file server is configured to share keys and certificates with nodes. ActiveMQ is installed and configured. The root user is configured as an MCollective client.

Parameters

mcollective_password

String: required. The password for the mcollective user in ActiveMQ. This is the username that the MCollective servers and clients will use to connect to ActiveMQ.

admin_password

String: required. The password for the admin user in ActiveMQ. This username has administrative rights in ActiveMQ and is not used elsewhere.

keystore_password

String: required. The password used to encrypt the Java truststore and keystore that ActiveMQ uses to store its private key, certificate and the Puppet CA certificate.

mcollective_plugins

Array of strings: required. An array of MCollective plugins that should be installed and enabled on servers.

The mcoconfig::addclient defined type

The mcoconfig::addclient defined type creates private keys and certificates on the Puppet master for MCollective clients.

Parameters

username

String: required. The username that will be using the created key and certificate.

client_fqdn

String: optional. The FQDN of the client node. The client_fqdn is set to the title of the defined type by default. It can be overriden explicitly if the title has to be changed to remain unique.

The mcoconfig::user defined type

The mcoconfig::user defined type configures a user to become an MCollective client on a node. Keys and certificates must be created on the Puppet master using the mcoconfig::addclient defined type for each user being configured on each node.

Parameters

username

String: required. The username of the local user.

homedir

String: optional. The home directory of the local user. Set to /home/$username by default.

The mcoconfig::filestore private class

The mcoconfig::filestore class is used by the module to create the structure of the file store and populate it with the required keys, certificates and CA certificate. The class makes use of four parameters to determine where and how to create the file store. The default parameters are defined in a separate mcoconfig::params class.

There is currently no explicit way to override the paths that mcoconfig::filestore uses, although Hiera automatic lookups could be used to set them. The correct way to fix any file store issues is to use case statements in the mcoconfig::params class to account for discrepancies between operating systems, Puppet versions etc.

The class parameters are noted here for reference.

Parameters

filestore_root

String: optional. The root directory of the file store. Defaults to /etc/puppet/mco_files.

filestore_shared

String: optional. The name of the subdirectory used to store shared certificates and the CA certificate. Defaults to shared.

filestore_clients

String: optional. The name of the subdirectory used to store client certificates. Defaults to clients.

filestore_private

String: optional. The name of the subdirectory used to store private keys. Individual nodes will have subdirectories named after their CN under this directory. The auth.conf file should be configured to only allow nodes to connect to their own private areas. Defaults to private.

The mcoconfig::activemq private class

The mcoconfig::activemq class is responsible for installing and configuring ActiveMQ. The actual work is done by the mcoconfig::activemq::install and mcoconfig::activemq::config classes. Parameters are set in the mcoconfig::activemq::params class.

As with the file store, any issues should be corrected by modifying the mcoconfig::activemq::params class to take into account discrepancies between operating systems etc.

Limitations

Currently this module only supports Debian. This is a package management issue so it should be possible to support more operating systems once I have the appropriate test platforms set up.

Development

I am happy to receive pull requests.