Pro Puppet (59 page)

Similar to the server configuration file, the operator configures the pre-shared key that MCollective uses to authenticate messages. In addition, the Stomp server the client will connect to is configured as
stomp.example.com,
with the username
mcollective
and the password
iwillchangethispassword
.

With the client configured, the operator uses the
mc-ping
command, as shown in
Listing 11-20
, to test communication with the MCollective server processes. The operator has also configured the MCollective server on the example.com web and mail servers.

The
mc-ping
command informs the operator that the MCollective server is running and responding to messages on both the web server and the mail server. This command verifies that the configuration settings in the RabbitMQ middleware and the MCollective server and client configuration files are working.

TROUBLESHOOTING MCOLLECTIVE

With the MCollective server and client processes configured, the operator is in a position to execute Puppet runs on an ad-hoc basis using MCollective. Let's see how he accomplishes this now.

MCollective is extensible in a number of ways. The most common way to extend MCollective is to re-use already written agent plugins. These small Ruby libraries enable MCollective to execute custom commands on the entire collective.

An agent plugin usually contains a Ruby library that must be distributed to all of the nodes running the MCollective agent. In addition, a data definition file provides a description of the input parameters the plugin accepts. This DDL file should be installed on the MCollective client systems. Finally, a script to execute MCollective using the specified agent plugin should also be installed on all of the MCollective client systems.

In this section, you'll learn about a number of MCollective agent plugins. Additional plugins are also available at
https://github.com/puppetlabs/mcollective-plugins
. These plugins provide a good example of how to write your own agent plugins for MCollective to execute additional commands specific to the tasks you need to manage.

MCollective does not contain an agent for Puppet out of the box. An agent plugin is provided, however, in the plugin repository located at
http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
.

In this section, you'll learn how the Example.com operator downloads and installs the MCollective Puppet agent plugin (
puppetd.rb
). This plugin allows the operator to execute Puppet agent runs on-demand. He does not need to wait for the run interval of the Puppet agent, or kick off jobs using other tools.

First, the mcollective-plugins repository should be downloaded to gain access to the Puppet agent plugins. This download is easily accomplished with the
git clone
command, as shown in
Listing 11-21
.

Alternatively, if Git is not available, the GitHub site provides a downloadable tar archive of the repository. Simply download the tar archive and unpack into the current working directory to obtain the Puppet agent MCollective plugin.

Next, the operator distributes the Puppet agent Ruby library and data definition,
puppetd.rb
and
puppetd.ddl,
to all of the MCollective agent systems. MCollective plugins should be placed in the directory specified by the
libdir
setting in the
server.cfg
configuration file. Puppet is an excellent way to distribute these plugins. On the Debian test system, the operator puts the plugin into place using the commands shown in
Listing 11-22
.

Once the plugin directory has been located, the operator copies into place the
puppetd
agent files from the mcollective-plugins repository (see
Listing 11-23
). The operator has cloned the mcollective-plugins repository into his home directory.

We see the operator has copied the puppet.rb plugin library and the data definition into the agent subdirectory. This directory is a subdirectory of the library path specified in the MCollective
server.cfg
configuration file.

With the plugin installed, the MCollective daemon needs to reload all of the agent configuration files. The operator uses the
mc-controller
command in
Listing 11-24
on a MCollective client to tell all servers to reload their agent plugins.

Once the MCollective servers finish reloading their agent plugins, the next step is to verify that the new plugin is available. In order to verify the list of available agent plugins, the operator uses the
mc-rpc
command as shown in
Listing 11-25
to obtain an inventory of available agents. In this example, the operator calls the
agent_inventory
action on the
rpcutil
agent.

Notice the
:agent => "puppet"
line in the output report of the available agents on the system named Debian. The output of the agent inventory RPC command indicates that the MCollective server running on the Debian system has properly loaded the newly-installed Puppet agent plugin.

With the Puppet agent installed on a MCollective server, the operator decides to kick off a Puppet agent run using MCollective. To do so, he executes the
mc-puppetd
script on a MCollective client system. The
mc-puppetd
script is a convenience wrapper around the remote procedure call agent and associated actions. The
mc-puppetd
command may be copied from the plugin directory into the
/usr/sbin/
directory on the MCollective client systems. Alternatively, the
mc-rpc
command that comes with the MCollective packages may be used to call agent actions, as shown in
Listing 11-26
.

Here the operator used the
mc-puppetd
command, turned on verbose output using the
-v
flag, and commanded all of the MCollective servers to run the Puppet agent once. This is equivalent to executing
puppetd --runonce
on all of the systems in the collection.

MULTIPLE INSTANCES OF PUPPET AGENT

When Puppet is run with the
--runonce
option, the agent will fork to the background. The actual Puppet agent run may not have succeeded, even though MCollective successfully launches Puppet. The Puppet reports should be inspected for the overall status results of each Puppet agent run. The OK result from MCollective indicates only that the MCollective server was able to successfully start the
puppetd
process and did not receive any output.

The
mc-puppetd
command is useful to work with the Puppet agent directly. However, as additional agents are installed, it may become cumbersome to keep track of a large number of different commands on the MCollective client systems. As an alternative to the
mc-puppetd
command, most agents are callable through the
mc-rpc
command. The
mc-rpc
command has the added benefit of reading the DDL file for each agent when the client is invoked. Let's see how
mc-rpc
is able to provide information about
the input and output parameters of an MCollective agent by reading the DDL file for the agent, shown in
Listing 11-27
.