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 <rip@devco.net>
     Version: 0.1
     License: ASL 2.0
     Timeout: 0
   Home Page: https://docs.puppetlabs.com/mcollective/

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.

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

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:

metadata    :name        => "flatfile",
            :description => "Flatfile based discovery for node identities",
            :author      => "R.I.Pienaar <rip@devco.net>",
            :license     => "ASL 2.0",
            :version     => "0.1",
            :url         => "https://docs.puppetlabs.com/mcollective/",
            :timeout     => 0

discovery do
    capabilities :identity
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.

↑ Back to top