Node Sets

Node Sets are how you tell the playbook about groups of nodes that exist on your network, today you can use MCollective Discovery, PQL Queries, YAML files, Shell Scripts and Terraform outputs to create the node sets.

In all cases the node sets must produce a list of certnames that will match what MCollective expects, in cases where you want to use MCollective based tasks. In the future task types will be pluggable and you just have to produce whatever node sets your type of task needs.

Common Node Set options

There are a few common options you can supply to all node sets, here’s a sample shell discovery with some common options set, these apply to all discovery types:

$nodes = choria::discover("shell",
  "script" => "/usr/local/bin/nodes.sh",
  "at_least" => 1,
  "when_empty" => "Could not find any nodes from nodes.sh",
  "limit" => 10,
  "test" => true,
  "uses" => {
    "appmgr" => "> 1.0.1"}
  }
)

MCollective Nodes

The most basic MCollective node set can be:

$nodes = choria::discover(
  "discovery_method" => "choria",
  "test" => true,
  "classes" => ["apache"],
  "uses" => {"rpcutil" => "~ 1.0.0"},
  "facts" => ["country=uk"]
)

You can also make it explicit that this is an mcollective type discovery:

$nodes = choria::discover("mcollective",
  "discovery_method" => "choria",
  "test" => true,
  "classes" => ["apache"],
  "uses" => {"rpcutil" => "~ 1.0.0"}
)

This tells it to use the MCollective choria discovery method and since that is based on PuppetDB I set test => true to cause it to ping the nodes it discovered to verify their connectivity.

It uses a classes filter to limit the nodes, other examples below, and declare these nodes to use the rpcutil agent.

The rpcutil agent above in the uses section is specified as needing version ~ 1.0.0 - a SemVer range - and it will verify that this is true on the discovered nodes.

YAML Nodes

A YAML file is supported as an input format, it can have groups inside it like the example here:

web_servers:
  - node1.example.net
  - node2.example.net

db_servers:
  - db1.example.net
  - db2.example.net

Put this in a file and you can use it as a Node Set source:

$nodes = choria::discover("yaml",
  "group" => "web_servers",
  "source" => "/etc/your_co/nodes.yaml"
)

PQL Nodes

While the Choria discovery method supports PQL it’s a bit strict on format, within the playbook system we have some more freedom so you can just make arbitrary PQL queries:

$nodes = choria::discover("pql",
  "query" => "facts { name = 'country' and value = '${country}' }",
  "test" => true
)

All non deactivated certnames will be extracted and used as discovery source. This also shows how to use a input variable and a reminder you should test MCollective connectivity to this sort of node set.

Shell Nodes

A shell script - or any program really - can be used to extract your nodes:

$nodes = choria::discover("shell",
  "script" => "/usr/local/bin/nodes.sh"
)

The script should just output one certname per line. It supports any arguments you might need and of course you can use variable interpolation to put inputs there.

Terraform Nodes

Retrieves a Terraform output from a state file, only outputs of the list type are supported. No effort to first pull remote states is currently made.

$nodes = choria::discover("terraform",
  "statefile" => "/path/to/terraform.tfstate",
  "output" => "webservers"
)

This would run terraform output -state /path/to/terraform.tfstate -json webservers