PLUGINS.md

Plugin DSL

component

Components are logical groupings of elements that make up an application.

component "webserver" do
  description "My webserver that serves webs"
end

description

Provides text to be displayed in the help output generated for the component

component "webserver" do
  description "serves the myface PHP web application"
end

versioned

Declares that the component is versioned.

component "webserver" do
  versioned
end

This will default to the 'webserver.version' attribute, seen in recipes as node[:webserver][:version]. Declaring this will allow you to use the mb plugin upgrade command:

mb myface upgrade --components webserver:1.2.3

You can also specify a custom version attribute:

component "webserver" do
  versioned_with "web"
end

THis would use the attribute 'web', seen in recipes as node[:web].

command

Defines a command to be added to the mb cli generated for the plugin.

  command "start" do
    description "Start the web server"
    execute do
      on("default") do
        service("apache").run(:start)
      end
    end
  end

description

Provides text to be displayed in the help output generated for the plugin

command "start" do
  description "Start the web server"
  # ...
end

execute

Execute provides a place to define which actions are to be run during a command's run

command "start" do
  execute do
    on("default") do
      service("server").run(:start)
    end
  end
end

on

on specifies a group to perform the actions contained in the block on. These actions will be performed in parallel. If actions need to be performed in sequence, use multiple on blocks.

Invocation of actions in on blocks follows this syntax: service("service_name").run(:action_name)

command "start" do
  execute do
    on("default") do
      service("server").run(:start)
    end
  end
end

service

service is used to invoke actions in a command on block. See on for more details

on("default") do
  service("server").run(:start)
end

any

To run a command only on portion of the nodes:

on("default", any: 2) do
  ...
end

The nodes will be chosen at random.

max_concurrent

To run a command on all nodes, but limit how many are running at once:

on("default", max_concurrent: 2) do
  ...
end

group

Groups allow motherbrain to identify nodes on which actions are taken.

component "webserver" do
  description "My webserver that serves webs"

  group "default" do
    recipe "myface::webserver"
  end
end

Also supported

  group "default" do
    role "webserver"
  end

  group "default" do
    attribute "activemq.master", true
  end

recipe

Used in a group to identify a server by a recipe entry on its runlist

  group "default" do
    recipe "myface::webserver"
  end

role

Used in a group to identify a server by a role entry on its runlist

  group "default" do
    role "webserver"
  end

attribute

Used in a group to identify a server by a node attribute

  group "default" do
    attribute "activemq.master", true
  end

service

Services are defined to represent the running processes on a given node that make up a component.

component "webserver" do
  # ...
  service "apache" do
    # ...
  end
end

action

Actions provide a way of interacting with the chef server to change the state of a service. Following the block, chef-client will be run on the nodes matched by the group.

service "apache" do
  action :start do
    node_attribute 'myface.apache.enable', true
    node_attribute 'myface.apache.start', true
  end

  action :stop do
    node_attribute 'myface.apache.enable', false
    node_attribute 'myface.apache.start', false
  end
end

node_attribute

Used in an action to specify the value a node attribute should be set to

action :start do
  node_attribute 'myface.apache.enable', true
  node_attribute 'myface.apache.start', true
end

toggle

To toggle an attribute for just this Chef run:

action :start do
  node_attribute 'myface.apache.restart', true, toggle: true
end

The attribute will be set to true, and then set back to its original value after the Chef run.

stack_order

A stack order specifies the order in which a bootstrap or Chef run occurs.

stack_order do
  bootstrap("webserver::default")
end

bootstrap

Used in a stack_order block to specify what component and group should be bootstrapped during a provision

stack_order do
  bootstrap("webserver::default")
end