website/reference/plugins/discovery.md

   1 ---
   2 layout: default
   3 title: Discovery Plugins
   4 ---
   5 [DDL]: /mcollective/reference/plugins/ddl.html
   6
   7 ## Overview
   8 Up to MCollective 2.0.0 the discovery system could only discover against
   9 the network by doing broadcasts over the middleware.
  10
  11 The _direct addressing_ capability introduced in 2.0.0 enables users to
  12 communicate with a node without doing broadcast if they know the
  13 configured identity of that node.
  14
  15 In version 2.1.0 we are introducing a new kind of plugin that works on
  16 the client system to do discovery against any data source that can
  17 return a list of identities such as flatfiles or databases.
  18
  19 ## Configuring and using discovery plugins
  20 Your mcollective client has a setting called *default_discovery_method*
  21 that defaults to *mc*, if you change this in your _client.cfg_ to
  22 another known plugin you can use that instead.
  23
  24 To get a list of known discovery plugins use the _mco plugin_
  25 application:
  26
  27 {% highlight console %}
  28 % mco plugin doc
  29 Please specify a plugin. Available plugins are:
  30
  31 Discovery Methods:
  32   flatfile        Flatfile based discovery for node identities
  33         mc              MCollective Broadcast based discovery
  34         mongo           MongoDB based discovery for databases built using registration
  35 {% endhighlight %}
  36
  37 Each plugin can have a different set of capabilities, for example a
  38 flatfile with only hostnames cannot do class or fact based filters and
  39 you will receive an error if you tried to do so.  You can see the
  40 capabilities of each plugin using the _mco plugin_ application:
  41
  42 {% highlight console %}
  43 $ mco plugin doc flatfile
  44 flatfile
  45 ========
  46
  47 Flatfile based discovery for node identities
  48
  49       Author: R.I.Pienaar <rip@devco.net>
  50      Version: 0.1
  51      License: ASL 2.0
  52      Timeout: 0
  53    Home Page: http://marionette-collective.org/
  54
  55 DISCOVERY METHOD CAPABILITIES:
  56       Filter based on mcollective identity
  57 {% endhighlight %}
  58
  59 Here you can see the only capability that this plugin has is to filter
  60 against identities.
  61
  62 These plugins require DDL files to be written and distributed when
  63 installing each plugin.
  64
  65 When using the mcollective CLI you can choose which plugin to use per
  66 request, some plugins require arguments like the file to discover
  67 against:
  68
  69 {% highlight console %}
  70 $ mco rpc rpcutil ping --dm flatfile --do /some/text/file
  71 {% endhighlight %}
  72
  73 In the case of the flatfile plugin there is a convenient shortcut
  74 available on all client applications that has the same effect as above:
  75
  76 {% highlight console %}
  77 $ mco rpc rpcutil ping --nodes /some/text/file
  78 {% endhighlight %}
  79
  80 Any request that uses the compound filters using *-S* will be forced to
  81 use the network broadcast discovery method.
  82
  83 ## Writing a discovery plugin
  84 Writing your own discovery plugin is very simple, you need to provide
  85 one method that returns an array of node names.
  86
  87 The plugins only need to be present on the client machines but no harm
  88 in installing them on all machines.  They need to be installed into the
  89 *discovery* directory in the usual plugin directory.  You can use the
  90 *mco plugin package* command to create RPM or DEB packages for these
  91 plugins.
  92
  93 {% highlight ruby linenos %}
  94 module MCollective
  95   class Discovery
  96     class Flatfile
  97       def self.discover(filter, timeout, limit=0, client=nil)
  98         unless client.options[:discovery_options].empty?
  99           file = client.options[:discovery_options].first
 100         else
 101           raise "The flatfile discovery method needs a path to a text file"
 102         end
 103
 104         raise "Cannot read the file %s specified as discovery source" % file unless File.readable?(file)
 105
 106         discovered = []
 107
 108         hosts = File.readlines(file).map{|l| l.chomp}
 109
 110         unless filter["identity"].empty?
 111           filter["identity"].each do |identity|
 112             identity = Regexp.new(identity.gsub("\/", "")) if identity.match("^/")
 113
 114             if identity.is_a?(Regexp)
 115               discovered = hosts.grep(identity)
 116             elsif hosts.include?(identity)
 117               discovered << identity
 118             end
 119           end
 120         else
 121           discovered = hosts
 122         end
 123
 124         discovered
 125       end
 126     end
 127   end
 128 end
 129 {% endhighlight %}
 130
 131 This is the *flatfile* plugin that is included in the distribution.  You
 132 can see it using the *client.options\[:discovery_options\]* array to get
 133 access to the file supplied using the *--do* command line argument,
 134 reading that file and doing either string or Regular Expression matching
 135 against it finally returning the list of nodes.
 136
 137 As mentioned each plugin needs a DDL, the DDL for this plugin is very
 138 simple:
 139
 140 {% highlight ruby linenos %}
 141 metadata    :name        => "flatfile",
 142             :description => "Flatfile based discovery for node identities",
 143             :author      => "R.I.Pienaar <rip@devco.net>",
 144             :license     => "ASL 2.0",
 145             :version     => "0.1",
 146             :url         => "http://marionette-collective.org/",
 147             :timeout     => 0
 148
 149 discovery do
 150     capabilities :identity
 151 end
 152 {% endhighlight %}
 153
 154 Here we expose just the one capability, valid capabilities would be
 155 *:classes*, *:facts*, *:identity*, *:agents* and *:compound*.  In
 156 practise you cannot create a plugin that supports the *:compound*
 157 capability as mcollective will force the use of the *mc* plugin if you
 158 use those.