Configuration

There are a number of steps you have to perform to get Tasks working, as these include changes to your Puppet Server it is not enabled by default.

Puppet Server

Your Puppet Server have to be quite recent - at least version 5.0.0 but 5.1.x or newer is best.

You have to enable the Tasks file end points and ensure all your nodes are authenticated to read from them. The Choria client and Servers will fetch Task Metadata and Task Files from the Puppet Server.

I use the puppet_authorization module in the example, add rules as follows:

puppet_authorization::rule { "puppetlabs tasks file contents":
  match_request_path   => "/puppet/v3/file_content/tasks",
  match_request_type   => "path",
  match_request_method => "get",
  allow                => ["*"],
  sort_order           => 510,
  path                 => "/etc/puppetlabs/puppetserver/conf.d/auth.conf",
}

puppet_authorization::rule { "puppetlabs tasks":
  match_request_path   => "/puppet/v3/tasks",
  match_request_type   => "path",
  match_request_method => "get",
  allow                => ["*"],
  sort_order           => 510,
  path                 => "/etc/puppetlabs/puppetserver/conf.d/auth.conf",
}

Servers and Clients

You have to install an extra plugin in your environment which includes the Task helpers

mcollective::plugin_classes:
  - mcollective_agent_bolt_tasks

RBAC

Basic RBAC rules are shown here, but refer to a later section in this guide for further details and tips about RBAC for Tasks

mcollective_agent_bolt_tasks::policies:
  - action: "allow"
    callers: "choria=rip.mcollective"
    actions: "*"
    facts: "*"
    classes: "*"

Change choria=rip.mcollective here with your own certificate name, this will give you full control of the tasks feature and all tasks.

Obtain some tasks

Tasks are delivered using Puppet modules much like anything else in the Puppet world. Uniquely to Tasks you only have to put the files on your Puppet Server module paths, you do not need to include any classes etc.

Tip

At present Choria will only consult your production environment for tasks.

You can therefore use puppet module, r10k or librarian puppet to place your modules in the production environment and that should be enough for them to be used by Choria

End to End Testing

A test task is included in the mcollective_agent_bolt_tasks module, you can verify the functionality of your network using it:

$ mco tasks run choria::ping --message "hello world"
Retrieving task metadata for task choria::ping from the Puppet Server
Attempting to download and run task choria::ping on 33 nodes

Downloading and verifying 1 file(s) from the Puppet Server to all nodes: ✓  33 / 33
Running task choria::ping and waiting up to 60 seconds for it to complete



Summary for task 884525e46b015b0789e57c019cd5f990

                       Task Name: choria::ping
                          Caller: choria=rip.mcollective
                       Completed: 33
                         Running: 0

                      Successful: 33
                          Failed: 0

                Average Run Time: 0.13s

After execution you can retrieve the output of each command:

$ mco tasks status 884525e46b015b0789e57c019cd5f990 -v
Discovering hosts using the choria method .... 33

node1.example.net
   {"message":"hello world","timestamp":"2018-03-19 13:21:18 +0000"}

.......

Summary for task 884525e46b015b0789e57c019cd5f990

                       Task Name: choria::ping
                          Caller: choria=rip.mcollective
                       Completed: 33
                         Running: 0

                      Successful: 33
                          Failed: 0

                Average Run Time: 0.13s

You may also see the results in JSON format with the -j flag.

Next Steps

At this point your tasks feature is working, you have a number of next steps to follow: