website/simplerpc/index.md

   1 ---
   2 layout: default
   3 title: SimpleRPC Introduction
   4 toc: false
   5 ---
   6 [WritingAgents]: /mcollective/reference/basic/basic_agent_and_client.html
   7 [SimpleRPCAgents]: /mcollective/simplerpc/agents.html
   8 [SimpleRPCClients]: /mcollective/simplerpc/clients.html
   9 [SimpleRPCAuditing]: /mcollective/simplerpc/auditing.html
  10 [SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
  11 [DDL]: /mcollective/reference/plugins/ddl.html
  12 [SimpleRPCMessageFormat]: /mcollective/simplerpc/messageformat.html
  13 [RPCUtil]: /mcollective/reference/plugins/rpcutil.html
  14 [WritingAgentsScreenCast]: http://mcollective.blip.tv/file/3808928/
  15 [RestGateway]: http://github.com/puppetlabs/marionette-collective/blob/master/ext/mc-rpc-restserver.rb
  16
  17 MCollective is a framework for writing feature full agents and clients and provides a [rich system to do that][WritingAgents].  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.
  18
  19 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.
  20
  21 SimpleRPC is a framework that provides the following:
  22
  23  * Provide simple conventions for writing [agents][SimpleRPCAgents] and [clients][SimpleRPCClients], favoring convention over custom design
  24  * Very easy to write agents including input validation and a sensible feedback mechanism in case of error
  25  * Provide [audit logging][SimpleRPCAuditing] abilities of calls to agents
  26  * Provide the ability to do [fine grain Authorization][SimpleRPCAuthorization] of calls to agents and actions.
  27  * Has a [Data Definition Language][DDL] used to describe agents and assist in giving hints to auto generating user interfaces.
  28  * The provided generic calling tool should be able to speak to most compliant agents
  29  * Should you need to you can still write your own clients, this should be very easy too
  30  * 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.
  31  * The full capabilities of the standard Client classes shouldddl still be exposed in case you want to write advanced agents and clients
  32  * A documented [standard message format][SimpleRPCMessageFormat] built ontop of the core format.
  33
  34
  35 We've provided full tutorials on [Writing Simple RPC Agents][SimpleRPCAgents] and [Clients][SimpleRPCClients].  There is also a [screencast that will give you a quick look at what is involved in writing agents][WritingAgentsScreenCast].
  36
  37
  38 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:
  39
  40 {% highlight ruby linenos %}
  41 module MCollective
  42   module Agent
  43     class Helloworld<RPC::Agent
  44       # Basic echo server
  45       def echo_action
  46         validate :msg, String
  47
  48         reply.data = request[:msg]
  49       end
  50     end
  51   end
  52 end
  53 {% endhighlight %}
  54
  55 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:
  56
  57 {% highlight console %}
  58  % mco rpc helloworld echo msg="Welcome to MCollective Simple RPC"
  59  Determining the amount of hosts matching filter for 2 seconds .... 1
  60
  61  devel.your.com                          : OK
  62      "Welcome to MCollective Simple RPC"
  63
  64
  65
  66  ---- rpctest#echo call stats ----
  67             Nodes: 1
  68        Start Time: Wed Dec 23 20:49:14 +0000 2009
  69    Discovery Time: 0.00ms
  70        Agent Time: 54.35ms
  71        Total Time: 54.35ms
  72 {% endhighlight %}
  73
  74 Note: This example is not complete. Please see the [agents][SimpleRPCAgents] and [clients][SimpleRPCClients] pages for a walkthrough.
  75
  76 You could also use *mco rpc* like this and achieve the same result:
  77
  78 {% highlight console %}
  79  % mco rpc helloworld echo msg="Welcome to MCollective Simple RPC"
  80 {% endhighlight %}
  81
  82 For multiple options just add more *key=val* pairs at the end
  83
  84 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:
  85
  86 {% highlight ruby linenos %}
  87 #!/usr/bin/ruby
  88
  89 require 'mcollective'
  90
  91 include MCollective::RPC
  92
  93 mc = rpcclient("helloworld")
  94
  95 printrpc mc.echo(:msg => "Welcome to MCollective Simple RPC")
  96
  97 printrpcstats
  98 {% endhighlight %}
  99
 100 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][RestGateway].
 101
 102 A helper agent called [_rpcutil_][RPCUtil] is included that helps you gather stats, inventory etc about the running daemon.