X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=website%2Freference%2Fplugins%2Fdiscovery.md;fp=website%2Freference%2Fplugins%2Fdiscovery.md;h=0dbc4e4c7972ef77730797c1117c31710151bdba;hb=b87d2f4e68281062df1913440ca5753ae63314a9;hp=0000000000000000000000000000000000000000;hpb=ab0ea530b8ac956091f17b104ab2311336cfc250;p=packages%2Fprecise%2Fmcollective.git diff --git a/website/reference/plugins/discovery.md b/website/reference/plugins/discovery.md new file mode 100644 index 0000000..0dbc4e4 --- /dev/null +++ b/website/reference/plugins/discovery.md @@ -0,0 +1,158 @@ +--- +layout: default +title: Discovery Plugins +--- +[DDL]: /mcollective/reference/plugins/ddl.html + +## 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: + +{% highlight console %} +% 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 +{% endhighlight %} + +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: + +{% highlight console %} +$ mco plugin doc flatfile +flatfile +======== + +Flatfile based discovery for node identities + + Author: R.I.Pienaar + Version: 0.1 + License: ASL 2.0 + Timeout: 0 + Home Page: http://marionette-collective.org/ + +DISCOVERY METHOD CAPABILITIES: + Filter based on mcollective identity +{% endhighlight %} + +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: + +{% highlight console %} +$ mco rpc rpcutil ping --dm flatfile --do /some/text/file +{% endhighlight %} + +In the case of the flatfile plugin there is a convenient shortcut +available on all client applications that has the same effect as above: + +{% highlight console %} +$ mco rpc rpcutil ping --nodes /some/text/file +{% endhighlight %} + +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. + +{% highlight ruby linenos %} +module MCollective + class Discovery + class Flatfile + def self.discover(filter, timeout, limit=0, client=nil) + unless client.options[:discovery_options].empty? + file = client.options[:discovery_options].first + else + raise "The flatfile discovery method needs a path to a text file" + end + + raise "Cannot read the file %s specified as discovery source" % file unless File.readable?(file) + + discovered = [] + + hosts = File.readlines(file).map{|l| l.chomp} + + unless filter["identity"].empty? + filter["identity"].each do |identity| + identity = Regexp.new(identity.gsub("\/", "")) if identity.match("^/") + + if identity.is_a?(Regexp) + discovered = hosts.grep(identity) + elsif hosts.include?(identity) + discovered << identity + end + end + else + discovered = hosts + end + + discovered + end + end + end +end +{% endhighlight %} + +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: + +{% highlight ruby linenos %} +metadata :name => "flatfile", + :description => "Flatfile based discovery for node identities", + :author => "R.I.Pienaar ", + :license => "ASL 2.0", + :version => "0.1", + :url => "http://marionette-collective.org/", + :timeout => 0 + +discovery do + capabilities :identity +end +{% endhighlight %} + +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.