Writing broker types

Brokers are responsible for handing a node off to a configuration management system, and consist of two parts: a broker type and some information that is specific for each broker type. For the Puppet broker type, this information consists of the node's certname, the address of the server, and the Puppet environment that a node should use. You create brokers with the create-broker command

The broker type is closely tied to the configuration management system that the node should be handed off to. Generally, it consists of a (templated) shell script that does that, and a description of what additional information must be specified to create a broker from that broker type.

To create a broker called sample, do the following

1. Create a directory sample.broker somewhere on the broker_path set in your config.yaml; by default, the brokers directory in Razor.root is on that path.
2. Write a template for your broker install script and put it into install.erb in the sample.broker directory
3. If your broker type requires configuration data, add a configuration.yaml to your sample.broker directory.

To see examples of brokers, have a look at the stock brokers (pun intended) that ship with Razor.

Writing the broker install script

The broker install script is generated from the install.erb template of your broker, and should generally return a valid shell script, since tasks generally perform the handoff to the broker by running a command like curl -s <%= broker_install_url %> | /bin/bash; the server makes sure that the GET request to broker_install_url returns the broker's install script, after interpolating the template.

In the install.erb template, you have access to two objects: node and broker. The node object gives you access to things like the node's facts as node.facts["foo"], the node's tags via node.tags, etc. [FIXME: clarify this]

The broker object gives you access to the configuration settings: if your configuration.yaml specifies that a setting version must be provided when creating a broker from this broker type, you can access the value of version for the current broker as broker.version.

The broker configuration file

The configuration.yaml file declares what parameters the user must specify when creating a broker. For the Puppet broker type, it looks something like

---
certname:
  description: "The locally unique name for this node."
  required: true
server:
  description: "The puppet master server to request configurations from."
  required: true
environment:
  description: "On agent nodes, the environment to request configuration in."

For each parameter, you can provide a human-readable description and indicate whether this parameter is required. Parameters that are not explicitly required are optional.