Pro Puppet (59 page)
Authors: Jeffrey McCune James Turnbull
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 asstomp.example.com,with the usernamemcollectiveand the passwordiwillchangethispassword.
With the client configured, the operator uses themc-pingcommand, 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.
Listing 11-20.
Using the mc-ping command
$ mc-ping
webserver time=43.11 ms
mailserver time=46.81 ms
---- ping statistics ----
2 replies max: 46.81 min: 43.11 avg: 44.96 Agents
Themc-pingcommand 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
If the mc-ping command does not return results for the MCollective servers running on your network, the following things may be the source of the problem:
- The pre-shared key in the client and server configuration files does not match.
- The Stomp user name or password are not correct in the client or server configuration.
- RabbitMQ is not listening on TCP port 6163.
Debugging information for RabbitMQ is located in /var/log/rabbitmq, and may contain information about invalid logins if the Stomp username and password are not correct. In addition, the MCollective log file is located at /var/log/mcollective.log and may contain useful troubleshooting information.
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 athttps://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 athttp://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 thegit clonecommand, as shown in
Listing 11-21
.
Listing 11-21.
Cloning the mcollective-plugins repository
$ git clone git://github.com/puppetlabs/mcollective-plugins.git
Initialized empty Git repository in /Users/jeff/plabs/mcollective/mcollective-plugins/.git/
remote: Counting objects: 1233, done.
remote: Compressing objects: 100% (817/817), done.
remote: Total 1233 (delta 463), reused 864 (delta 287)
Receiving objects: 100% (1233/1233), 162.19 KiB, done.
Resolving deltas: 100% (463/463), done.
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.rbandpuppetd.ddl,to all of the MCollective agent systems. MCollective plugins should be placed in the directory specified by thelibdirsetting in theserver.cfgconfiguration 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
.
Listing 11-22.
Determining the plugin directory
$ sudo grep libdir /etc/mcollective/server.cfg
libdir = /usr/share/mcollective/plugins
Once the plugin directory has been located, the operator copies into place thepuppetdagent files from the mcollective-plugins repository (see
Listing 11-23
). The operator has cloned the mcollective-plugins repository into his home directory.
Listing 11-23.
Installing the Puppet agent plugin on an MCollective agent
$ cd /usr/share/mcollective/plugins/mcollective
$ cp ~/mcollective-plugins/agent/puppetd/puppetd.rb ./agent/
$ cp ~/mcollective-plugins/agent/puppetd/puppetd.ddl ./agent/
$ ls /usr/share/mcollective/plugins/agent/
discovery.rb
puppetd.ddl
puppetd.rb
rpcutil.ddl
rpcutil.rb
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 MCollectiveserver.cfgconfiguration file.
With the plugin installed, the MCollective daemon needs to reload all of the agent configuration files. The operator uses themc-controllercommand in
Listing 11-24
on a MCollective client to tell all servers to reload their agent plugins.
Listing 11-24.
Commanding MCollective daemons to reload agents
$ mc-controller reload_agents
Determining the amount of hosts matching filter for 2 seconds .... 1
www> reloaded all agents
---- mcollectived controller summary ----
Nodes: 1 / 1
Start Time: Sun Mar 13 20:43:43 -0400 2011
Discovery Time: 2002.84ms
Agent Time: 46.47ms
Total Time: 2049.32ms
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 themc-rpccommand as shown in
Listing 11-25
to obtain an inventory of available agents. In this example, the operator calls theagent_inventoryaction on therpcutilagent.
Listing 11-25.
Using the mc-rpc rpcutil agent_inventory command
$ mc-rpc rpcutil agent_inventory
www
Agents:
[{:license=>"Apache License, Version 2",
:agent=>"discovery",
:author=>"R.I.Pienaar "},
{:license=>"Apache License 2.0",
:timeout=>20,
:description=>"Agent to manage the puppet daemon",
:agent=>"puppetd",
:version=>"1.3",
:author=>"R.I.Pienaar",
:name=>"SimpleRPC Puppet Agent",
:url=>"http://mcollective-plugins.googlecode.com/"},
{:license=>"Apache License, Version 2.0",
:timeout=>10,
:description=>
"General helpful actions that expose stats and internals to SimpleRPC clients",
:agent=>"rpcutil",
:version=>"1.0",
:author=>"R.I.Pienaar ",
:name=>"Utilities and Helpers for SimpleRPC Agents",
:url=>"http://marionette-collective.org/"}]
Finished processing hosts in 44.89 ms
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 themc-puppetdscript on a MCollective client system. Themc-puppetdscript is a convenience wrapper around the remote procedure call agent and associated actions. Themc-puppetdcommand may be copied from the plugin directory into the/usr/sbin/directory on the MCollective client systems. Alternatively, themc-rpccommand that comes with the MCollective packages may be used to call agent actions, as shown in
Listing 11-26
.
Listing 11-26.
Executing mc-puppetd to start Puppet agent runs
$ mc-puppetd -v runonce
Determining the amount of hosts matching filter for 2 seconds .... 1
www : OK
{:output=>""}
---- rpc stats ----
Nodes: 1 / 1
Pass / Fail: 1 / 0
Start Time: Sun Mar 13 20:55:53 -0400 2011
Discovery Time: 2002.94ms
Agent Time: 1926.36ms
Total Time: 3929.30ms
Here the operator used themc-puppetdcommand, turned on verbose output using the-vflag, and commanded all of the MCollective servers to run the Puppet agent once. This is equivalent to executingpuppetd --runonceon all of the systems in the collection.
MULTIPLE INSTANCES OF PUPPET AGENT
When running Puppet from MCollective, the Puppet agent daemon on all managed nodes may be disabled. MCollective will spawn a new Puppet process each time thepuppetdagent is invoked using themc-puppetdcommand. This process will be in addition to any already running Puppet agent daemon, duplicating functionality.
If the Puppet agent daemon is disabled, periodic catalog runs will no longer take place, so please make sure to trigger periodic runs using mc-puppetd or configure the agent to run periodically throughcron.In any case, if multiple Puppet processes run simultaneously, only one will perform a catalog run at once. Multiple simultaneous catalog runs are prevented by the use of a lock file at /var/lib/puppet/state/puppetdlock. This file may be in a different location on your system and may be found using the command:puppet agent --configprint puppetdlockfile.
When Puppet is run with the--runonceoption, 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 thepuppetdprocess and did not receive any output.
Themc-puppetdcommand 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 themc-puppetdcommand, most agents are callable through themc-rpccommand. Themc-rpccommand has the added benefit of reading the DDL file for each agent when the client is invoked. Let's see howmc-rpcis 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
.
Listing 11-27.
Using mc-rpc to obtain actions from an agent
# mc-rpc --agent-help puppetd
SimpleRPC Puppet Agent
======================
Agent to manage the puppet daemon
Author: R.I.Pienaar
Version: 1.3
License: Apache License 2.0
Timeout: 20
Home Page: http://mcollective-plugins.googlecode.com/
ACTIONS:
========
disable, enable, runonce, status
disable action:
---------------
Disables the Puppetd
INPUT:
OUTPUT:
output:
Description: String indicating status
Display As: Status
enable action:
--------------
Enables the Puppetd
INPUT:
OUTPUT:
output:
Description: String indicating status
Display As: Status
runonce action:
---------------
Initiates a single Puppet run
INPUT:
OUTPUT:
output:
Description: Output from puppetd
Display As: Output
status action:
--------------
Status of the Puppet daemon
INPUT:
OUTPUT:
enabled:
Description: Is the agent enabled
Display As: Enabled
lastrun:
Description: When last did the agent run
Display As: Last Run
output:
Description: String displaying agent status
Display As: Status
running:
Description: Is the agent running
Display As: Running
