Discovery Plugins
Overview
Up to MCollective 2.0.0 the discovery system could only discover against the network by doing broadcasts over the middleware.
The direct addressing capability introduced in 2.0.0 enables users to communicate with a node without doing broadcast if they know the configured identity of that node.
In version 2.1.0 we are introducing a new kind of plugin that works on the client system to do discovery against any data source that can return a list of identities such as flatfiles or databases.
Configuring and using discovery plugins
Your mcollective client has a setting called default_discovery_method that defaults to mc, if you change this in your client.cfg to another known plugin you can use that instead.
To get a list of known discovery plugins use the mco plugin application:
% mco plugin doc
Please specify a plugin. Available plugins are:
Discovery Methods:
flatfile Flatfile based discovery for node identities
mc MCollective Broadcast based discovery
mongo MongoDB based discovery for databases built using registration
Each plugin can have a different set of capabilities, for example a flatfile with only hostnames cannot do class or fact based filters and you will receive an error if you tried to do so. You can see the capabilities of each plugin using the mco plugin application:
$ mco plugin doc flatfile
flatfile
========
Flatfile based discovery for node identities
Author: R.I.Pienaar <[email protected]>
Version: 0.1
License: ASL 2.0
Timeout: 0
Home Page: http://marionette-collective.org/
DISCOVERY METHOD CAPABILITIES:
Filter based on mcollective identity
Here you can see the only capability that this plugin has is to filter against identities.
These plugins require DDL files to be written and distributed when installing each plugin.
When using the mcollective CLI you can choose which plugin to use per request, some plugins require arguments like the file to discover against:
$ mco rpc rpcutil ping --dm flatfile --do /some/text/file
In the case of the flatfile plugin there is a convenient shortcut available on all client applications that has the same effect as above:
$ mco rpc rpcutil ping --nodes /some/text/file
Any request that uses the compound filters using -S will be forced to use the network broadcast discovery method.
Writing a discovery plugin
Writing your own discovery plugin is very simple, you need to provide one method that returns an array of node names.
The plugins only need to be present on the client machines but no harm in installing them on all machines. They need to be installed into the discovery directory in the usual plugin directory. You can use the mco plugin package command to create RPM or DEB packages for these plugins.
1 module MCollective
2 class Discovery
3 class Flatfile
4 def self.discover(filter, timeout, limit=0, client=nil)
5 unless client.options[:discovery_options].empty?
6 file = client.options[:discovery_options].first
7 else
8 raise "The flatfile discovery method needs a path to a text file"
9 end
10
11 raise "Cannot read the file %s specified as discovery source" % file unless File.readable?(file)
12
13 discovered = []
14
15 hosts = File.readlines(file).map{|l| l.chomp}
16
17 unless filter["identity"].empty?
18 filter["identity"].each do |identity|
19 identity = Regexp.new(identity.gsub("\/", "")) if identity.match("^/")
20
21 if identity.is_a?(Regexp)
22 discovered = hosts.grep(identity)
23 elsif hosts.include?(identity)
24 discovered << identity
25 end
26 end
27 else
28 discovered = hosts
29 end
30
31 discovered
32 end
33 end
34 end
35 end
This is the flatfile plugin that is included in the distribution. You can see it using the client.options[:discovery_options] array to get access to the file supplied using the –do command line argument, reading that file and doing either string or Regular Expression matching against it finally returning the list of nodes.
As mentioned each plugin needs a DDL, the DDL for this plugin is very simple:
1 metadata :name => "flatfile",
2 :description => "Flatfile based discovery for node identities",
3 :author => "R.I.Pienaar <[email protected]>",
4 :license => "ASL 2.0",
5 :version => "0.1",
6 :url => "http://marionette-collective.org/",
7 :timeout => 0
8
9 discovery do
10 capabilities :identity
11 end
Here we expose just the one capability, valid capabilities would be :classes, :facts, :identity, :agents and :compound. In practise you cannot create a plugin that supports the :compound capability as mcollective will force the use of the mc plugin if you use those.