Introduction

MCollective is a framework for writing feature full agents and clients and provides a rich system to do that. Sometimes though you just have simpler needs than the full Client provides or need to prototype something quickly. MCollective Simple RPC is a framework ontop of the standard client that abstracts away a lot of the complexity.

We've written a simple to use framework that is integrated into MCollective that aims to tick all of these boxes:

• Provide simple conventions for writing agents and clients, favoring convention over custom design
• Very easy to write agents including input validation and a sensible feedback mechanism in case of error
• Provide audit logging abilities of calls to agents
• The provided generic calling tool should be able to speak to most compliant agents
• Should you need to you can still write your own clients, this should be very easy too
• Return data should be easy to print, in most cases the framework should be able to print a sensible output with a single, provided, function
• The full capabilities of the standard Client classes should still be exposed in case you want to write advanced agents and clients

NOTE: This feature is available from version 0.4 of MCollective

We've provided full tutorials on Writing Simple RPC Agents and Clients.

A bit of code probably says more than lots of english, so here's a simple hello world Agent, it just echo's back everything you send it in the :msg argument:

module Mcollective
    module Agent
        class Helloworld<RPC::Agent
            # Basic echo server
            def echo_action
                validate :msg, String
     
                reply.data = request[:msg]
            end
        end
    end
end

The nice thing about using a standard abstraction for clients is that you often won't even need to write a client for it, we ship a standard client that you can use to call the agent above:

$ mc-rpc --agent helloworld --action echo --arg msg="Welcome to MCollective Simple RPC"
Determining the amount of hosts matching filter for 2 seconds .... 1
                                        
devel.your.com                          : OK
    "hello world"



---- rpctest#echo call stats ----
           Nodes: 1
      Start Time: Wed Dec 23 20:49:14 +0000 2009
  Discovery Time: 0.00ms
      Agent Time: 54.35ms
      Total Time: 54.35ms

You could also use mc-rpc like this and achieve the same result:

$ mc-rpc helloworld echo msg="Welcome to MCollective Simple RPC"

For multiple options just add more key=val pairs at the end

But you can still write your own clients, it's incredibly simple, full details of a client is out of scope for the introduction - see the SimpleRPCClients page instead for full details - but here is some sample code to do the same call as above including full discovery and help output:

#!/usr/bin/ruby
 
require 'mcollective'
 
include MCollective::RPC
 
mc = rpcclient("helloworld")

printrpc mc.echo(:msg => "Welcome to MCollective Simple RPC")

printrpcstats

With a standard interface come a lot of possibilities, just like the standard one-size-fits-all CLI client above you can make web interfaces, there's a simple MCollective <-> REST bridge in the ext directory.