Docs: SimpleRPC Introduction


SimpleRPC Introduction

MCollective is a framework for writing feature full agents and clients and provides a rich system to do that. MCollective’s native Client though is very low level, a bit like TCP/IP is to HTTP. Like TCP/IP the native client does not provide any Authentication, Authorization etc.

MCollective Simple RPC is a framework on top of the standard client that abstracts away a lot of the complexity and provides a lot of convention and standards. It’s a bit like using HTTP ontop of TCP/IP to create REST services.

SimpleRPC is a framework that provides the following:

  • 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
  • Provide the ability to do fine grain Authorization of calls to agents and actions.
  • Has a Data Definition Language used to describe agents and assist in giving hints to auto generating user interfaces.
  • 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 DDL is used here to improve the standard one-size-fits-all methods.
  • The full capabilities of the standard Client classes shouldddl still be exposed in case you want to write advanced agents and clients
  • A documented standard message format built ontop of the core format.

We’ve provided full tutorials on Writing Simple RPC Agents and Clients. There is also a screencast that will give you a quick look at what is involved in writing agents.

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:

 1 module MCollective
 2   module Agent
 3     class Helloworld<RPC::Agent
 4       # Basic echo server
 5       def echo_action
 6         validate :msg, String
 7 
 8         reply.data = request[:msg]
 9       end
10     end
11   end
12 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:

 % mco rpc helloworld echo msg="Welcome to MCollective Simple RPC"
 Determining the amount of hosts matching filter for 2 seconds .... 1

 devel.your.com                          : OK
     "Welcome to MCollective Simple RPC"



 ---- 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

Note: This example is not complete. Please see the agents and clients pages for a walkthrough.

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

 % mco 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:

 1 #!/usr/bin/ruby
 2 
 3 require 'mcollective'
 4 
 5 include MCollective::RPC
 6 
 7 mc = rpcclient("helloworld")
 8 
 9 printrpc mc.echo(:msg => "Welcome to MCollective Simple RPC")
10 
11 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.

A helper agent called rpcutil is included that helps you gather stats, inventory etc about the running daemon.

↑ Back to top