Playbook Design Specification

Introduction

See the playbooks section for intro material

Features

This is a rough feature set, individual pieces are explored in more detail below:

General

  • It should support metadata like author, version, tags etc suitable for searching and cataloging on a web interface
  • It should support many groups of named node sets, node set sources can be MCollective or many other sources
  • It should support many named inputs usable from the CLI
  • It should support declaring desired versions of MCollective agents and support verifying that nodes match expectation
  • It should support tasks with common behaviours like retries and soft/hard failures etc
  • It should support many types of task like MCollective RPC, Webhooks, Slack, Ticket systems etc
  • It should support hook tasks to run on success, failure, between other tasks etc
  • It should have a flexible playbook language that is pure data and support templating to fill in input data and reference node sets
  • It should be standalone runable from the CLI
  • It should be non interactive runs with rich reporting while being paramaterised
  • It should have a custom logger format that shows the context as it moves through the playbook flow
  • It should have support for distributed key/value stores used in locks, inputs, node sets and tasks
  • It should produce reports that can be stored in JSON or in a webservice for later retrieval (#88)
  • It should support macros that ship with mcollective agent plugins and bring reusable self container utility logic
  • It should support versioned playbook schemas so we can ensure an incoming playbook is usable by the system (#87)
  • It should have JSON schemas for the full playbook schema - partially completed
  • It should validate incoming playbooks using the JSON schema
  • It should have an optional webservice where playbooks are stored and later ran under
  • It should be compatible with MCollective AAA, a webservice should be able to run commands as a certain user
  • It should support pluggable Node sources so users can extend it (#90)
  • It should support pluggable Task types so users can extend it (#89)
  • It should support arbitrarily named tasks lists and ability to run those from within a task list to facilitate reusing of logic (#91)

Inputs

  • Defined inputs should be sourced from external systems when not supplied

Node Sets

  • It should be able to do MCollective discovery
  • It should be able to make arbitrary PQL queries
  • It should be able to run shell scripts and get certnames from there
  • It should be able to load node set groups from YAML
  • It should be able to use terraform outputs
  • It should support data sources
  • It should be able to get node groups from PE classifications
  • It should be able to get node groups from foreman classifications
  • It should be able to query EC2 and search by tag for nodes

Tasks

  • It should be able to make MCollective requests
  • It should be able to make make assertions about MCollective request state
  • It should be able to run local shell scripts
  • It should be able to make GET and POST requests to arbitrary webhooks
  • It should be able to send messages to Slack
  • It should support data stores
  • It should be able to run terraform
  • It should be able to initiate and wait for servers to be built by razor

Data Sources

  • Should support dynamic inputs
  • Should be able to write and delete from data stores in tasks
  • Should have a in-memory data store
  • Should have a consul based data store
  • Should have a etcd based data store
  • Should have a vault based data store

Ticked features are implemented and usable today.

A number of issues have been opened on GitHub to track work on this feature.