Writing a plugin
The plugin package format, from a minimal example to every field of features and actions.
A plugin is a package in npm's format: a folder with a package.json that has a rookery section next to the usual fields. npm pack and npm publish understand it, so plugins can be shared through npmjs.com or a private registry such as Nexus or Verdaccio. The Unity plugin in plugins/unity/ is a good one to copy.
A minimal plugin
{
"name": "rookery-plugin-hello",
"version": "1.0.0",
"displayName": "Hello",
"rookery": {
"features": [
{
"id": "cowsay",
"group": "Development Tools",
"label": "cowsay",
"description": "Installs cowsay and adds a greeting to the overview.",
"summary": "`cowsay` is installed.",
"packages": ["cowsay"],
"commands": ["cowsay"],
"actions": [
{"name": "greet", "label": "Say hello", "run": "cowsay hello from $(hostname)"}
]
}
]
}
}Switch it on under Development Tools, apply the configuration, and Say hello appears on the host's overview.
The package
{
"name": "rookery-plugin-unity",
"version": "0.1.0",
"displayName": "Unity",
"description": "Unity CLI and editor for rookery machines.",
"keywords": ["rookery-plugin"],
"files": ["tasks", "guide.md"],
"rookery": {
"features": [
{
"id": "cli",
"group": "Development Tools",
"label": "Unity CLI",
"description": "Shown as help in rookery.",
"summary": "Unity CLI (`unity`) with its agent skills.",
"packages": ["libgtk-3-0t64"],
"commands": ["unity"],
"tasks": "tasks/cli.yml",
"guide": "guide.md",
"actions": [
{"name": "status", "label": "Sign-in and license", "run": "unity auth status"}
]
}
]
}
}The plugin's id is the package name without its scope and without a leading rookery-plugin-, so @acme/rookery-plugin-unity is unity. rookery.id overrides that. Ids and feature ids are lower-case letters, digits, - and _, starting with a letter. displayName is the name Rookery shows.
Features
Prop
Type
Actions
An action becomes an action of the host's controller named PLUGIN:ACTION. Applying the configuration writes the actions of the chosen features to the host, and they appear on the overview in their group. From the command line: rookery run HOST PLUGIN:ACTION.
Prop
Type
Arguments
The command finds each argument as ROOKERY_ARG_NAME in its environment, upper-cased, with _ for anything that is not a letter or digit. Values are never pasted into the command line. choices is a command whose output lines are the values to offer. values and kind mean what they mean for a provisioner's arguments, below. A yes or no is a switch here too.
Steps of other actions
An action with extends has no row of its own. It runs after the action it extends, every time, and its output follows that action's. Start that output with the plugin's name. An action and its steps run one after another in one session, each as its own user. All steps run even when one fails. rookery run HOST status includes what plugins add to it.
Terminal actions
An action with terminal: true gets a terminal of its own in a panel, with the same keys as other panels. From the command line it runs in your terminal over ssh -t. Actions without it have no terminal, so make them non-interactive.
Sign-ins should not open a browser on the host. Start them with env -u DISPLAY BROWSER=echo so the tool prints its link.
Leave agent off for anything the agent should not start, and think twice before setting it on an action that runs as root.
Tasks
tasks is a plain Ansible task list, included while the role runs: after the base tools and coding agents are installed, before the desktop is configured. Features are applied in the order the plugin lists them, so a later one can rely on an earlier one. Everything the role knows is available, most usefully:
| Variable | Value |
|---|---|
rookery_user, rookery_home | The agent's account and home |
rookery_plugin_dir | The package's directory, for files it brings |
rookery_plugin_features | Every feature chosen for the host |
rookery_software_rendering, rookery_profile | And the other rookery_ settings |
A setting of your own, such as a version, can be given per host in the profile's ansible_vars as long as its name starts with rookery_. Read it with a default:
version: "{{ rookery_unity_cli_version | default('1.0.0-beta.17') }}"Tasks must be safe to run again, because applying a configuration runs them every time.
On a node there is no agent: rookery_user and rookery_home are the SSH user and its home, and rookery_level is node. A feature for a node can also set these:
| Fact | What it adds |
|---|---|
rookery_firewall_rules | Rules of the node's firewall, as the arguments of ufw, such as allow in on incusbr0. The role deletes a rule of a feature that the node no longer has |
rookery_node_units | Units whose state rookeryd reports, such as incus |
rookery_offer | The provisioners it offers, once the tasks are sure of them |
Offering provisioners
A feature that lists offers sets rookery_offer with set_fact at the end of its tasks. The role keeps it in the host's /etc/rookery/applied.json, and Rookery registers a provisioner of each type after the apply, with the node it is on. The record is readable on the node, so it holds public values only. Rookery takes the provisioners the feature lists in offers, with their own arguments and secrets. It ignores any other provisioner, setting or secret in the record.
A provisioner registered by hand becomes the node's when Rookery finds the server it names on the node's address and port. The node's word alone, its aliases or the certificate it reports, never changes another provisioner. The apply then names it, and rookery provisioner run NAME adopt node=NODE makes it the node's.
| Field | Meaning |
|---|---|
provisioners | The ids it offers now, out of offers. All of them when it is left out |
settings | Values of the provisioners' own arguments. {address}, {user} and {port} become where Rookery reaches the node and as whom. A URL has to name the node's address |
secrets | Values of the provisioners' secrets, such as a server's certificate, kept as each provisioner's own |
aliases | Other values of a setting that reach the same server. A provisioner registered by hand with one is named in the apply's output, and its owner can make it the node's |
fingerprint | What identifies the server, for the apply's output |
- name: Offer the provisioner of this engine
ansible.builtin.set_fact:
rookery_offer:
provisioners: [container]
settings:
host: "ssh://{user}@{address}:{port}"With trusts, the certificate is in rookery_client_certificates, under the feature's PLUGIN/ID, with its fingerprint and a name for the trust store.
Guide
The guide is installed as /etc/rookery/guides/PLUGIN-FEATURE.md and linked from the host's AGENT.md (On the host). It is a Jinja template, so it can adapt to the host:
{% if rookery_software_rendering %}
This machine renders on the CPU; pass `--software`.
{% endif %}Write it for an agent that has never seen the tool. Cover what the command is and what has to happen before first use. Then say what needs a person, and what the agent must not ask about again.
Channels
A feature that publishes on the host's channel lists its topics with how long the host keeps them:
"channels": [{"topic": "progress", "keep": "none", "max": 1000, "days": 30}]The topic becomes PLUGIN/TOPIC. keep is the default for messages published there. With none only current listeners see a message, last stores the newest one, and log stores them for reading later. max and days limit a log. Publish with box publish PLUGIN/TOPIC '{"percent": 40}' and read with box listen PLUGIN/.
Writing a provisioner
A provisioner is a program of a plugin that makes things on a platform: machines for saved hosts, and other kinds of things its plugin names. It also has actions of its own, such as listing images or freeing space. Its plugin lists it under rookery.provisioners, next to features, and holds the executable. People register it under a name of their own with rookery provisioner add NAME PLUGIN/ID, and then use it with rookery host create HOST --provisioner NAME, rookery provisioner show NAME and rookery resource list (Provisioners, Resources). The plugins docker and incus in the Rookery source are examples.
{
"name": "rookery-plugin-lab",
"version": "1.0.0",
"displayName": "Lab",
"files": ["bin"],
"rookery": {
"provisioners": [
{
"id": "vm",
"label": "Lab virtual machine",
"description": "A guest on the lab server, set up from rookery's cloud seed.",
"command": "bin/provision",
"protocol": 2,
"verbs": ["list"],
"secrets": ["lab_token", {"name": "lab_ca", "required": false}],
"arguments": [
{"name": "server", "label": "Lab server", "required": true}
],
"kinds": [
{
"id": "machine",
"setup": "seed",
"archive": true,
"verbs": ["start", "stop", "change", "logs"],
"arguments": [
{"name": "cpus", "label": "CPUs", "default": "4", "kind": "resource"},
{"name": "image", "label": "Image", "default": "ubuntu-26.04",
"help": "The image the machine starts from."}
]
}
],
"actions": [
{"name": "pools", "label": "Storage pools", "group": "Storage", "changes": false},
{"name": "prune", "label": "Remove unused images", "group": "Storage",
"confirm": "Remove every image no machine uses?"}
]
}
]
}
}Its type is PLUGIN/ID, here lab/vm. Rookery runs it as each provisioner registered of that type, with that provisioner's settings and secrets. The program gets its secrets under the names it declares, whichever provisioner it runs as.
Manifest fields
Prop
Type
A kind:
Prop
Type
A kind other than machine belongs to no host. The Docker plugin's deployment is one, made from a Compose file:
{
"id": "deployment",
"label": "Compose project",
"verbs": ["start", "stop", "change", "logs"],
"spec": {"format": "compose", "label": "Compose file"},
"arguments": [{"name": "keep_volumes", "default": "no", "values": ["no", "yes"]}],
"actions": [
{"name": "services", "label": "Services", "group": "Compose", "changes": false},
{"name": "restart", "label": "Restart", "group": "Compose", "confirm": "Restart every container of this deployment?"}
]
}Rookery keeps the specification and never reads it. People give it with rookery resource create or rookery resource set ID --spec FILE (Deployments).
An action takes most fields of a host's action:
| Field | Means |
|---|---|
name, label, help | As for a host's action |
group | The group of the provisioner's page it is listed in |
arguments | What it asks for |
confirm | The question to answer yes to first |
It also takes these:
| Field | Default | Means |
|---|---|---|
changes | true | false for one that only reads. It answers at once. One that changes something runs as a job of its own. It holds the provisioner's lock, or the resource's for an action of a kind |
role | admin. An action of the provisioner with "changes": false is view | The least role that may run it through a Rookery server. An action of a kind is admin unless it says otherwise, even one that only reads |
An action runs where Rookery runs, as the provisioner does, so it has no terminal and no user. An argument with "secret": true is not shown as it is typed and is masked in the job's output.
Collections
A collection is a list of things the provisioner holds, such as the storage pools of a server, its volumes or its images. The provisioner's page shows each as one row with the number of its items. Enter opens a table of them, and each item has a page with the actions that act on it. Its actions are the provisioner's own, declared in actions as usual. A collection lists the ones that belong to it in new, item and list, and the page offers them there and not as rows of their own. rookery provisioner run runs them as any other action, and rookery provisioner show prints each collection as a table.
The Incus plugin declares its pools and the volumes in them:
"collections": [
{
"id": "pools", "label": "Storage pool", "plural": "Storage pools", "group": "Storage",
"key": ["pool"],
"columns": [{"name": "driver", "label": "Driver"}, {"name": "size", "label": "Size"}],
"new": [{"action": "create-pool"}],
"item": [
{"action": "resize-pool", "label": "Grow"},
{"action": "remove-pool", "label": "Remove", "arguments": {"pool": "name"}}
],
"remove": "remove-pool",
"show": "pools"
},
{
"id": "volumes", "label": "Volume", "plural": "Volumes", "group": "Storage",
"key": ["pool", "volume"], "within": "pools",
"new": [{"action": "create-volume"}],
"item": [{"action": "remove-volume", "label": "Remove", "arguments": {"volume": "name"}}],
"remove": "remove-volume"
}
]Prop
Type
Each entry of new, item and list names an action:
| Field | Means |
|---|---|
action | The name of the provisioner's action |
label | What it is called where the item is known, such as Grow. The action's own label when empty |
arguments | The argument each part of the key fills where its name is not the part's own, such as {"volume": "name"} |
On an item's page, the key fills the arguments of its actions, and they are not asked for again. A new item or an action on the list of a collection that is within another has the key of that item filled when it starts from that item's page. From the provisioner's page, it asks for that key too. The page of a pool lists the volumes in it, and the provisioner's page lists all of them.
A collection with kinds has the resources of those kinds that Rookery made with the provisioner as its items, in place of items that status gives. It has a key of one name, which takes the provisioner's id of the resource, and only item actions. Those are offered on the page of each such resource. The Incus plugin offers its action that grows a root disk on each machine and instance this way.
Rookery checks the collections when it loads the plugin. If a collection refers to an action, an argument, a kind or a collection that is not there, the provisioner cannot be used, and Rookery says what to fix. Each action belongs to one collection at most.
Arguments
Each entry of arguments, of the provisioner, of a kind or of an action, is one value it takes.
Prop
Type
A yes or no
Declare a yes or no with "kind": "boolean", and give its two values too:
{"name": "keep_volumes", "label": "Keep volumes", "default": "no", "kind": "boolean", "values": ["no", "yes"]}The screens show it as a switch, which Space, Enter or a click turns on or off. An argument whose values are just yes and no, or true and false, is a switch as well. Your program gets the value for on or off from values, or yes and no without them. On the command line it is given as one of these, in any case, and Rookery sends the declared value:
| On | Off |
|---|---|
yes, true, on, 1 | no, false, off, 0 |
An action's confirm question names each switch that is on. Give the argument a confirm of its own, such as "confirm": "Remove the deployment and its volumes?", and Rookery asks that question instead of the action's while the switch is on.
A provisioner's status, described below, lists the values an argument takes. Rookery does not run a choices command for a provisioner.
A host's set-up tabs show the arguments of a machine: the provisioner's own first, then the machine kind's.
| Argument | Where Rookery shows it |
|---|---|
required | On the Install tab, under the Provisioner row |
"kind": "resource", not required | Under Machine on the Settings tab |
| Any other | Under Provisioner Options on the Settings tab |
Rookery checks the value of a resource before it creates the machine. It goes by the name of the argument:
| Name contains | The value has to be |
|---|---|
cpu | A positive number, such as 4 |
memory, mem, ram, disk, size, storage or swap | A size with its unit, such as 8GiB, 512MiB or 4g |
| anything else | Not checked |
An argument that is not required may be left empty. Rookery lists a bad value as a problem of the tab that shows the argument, but the command line does not check resources. The provisioner checks what it is given in any case.
How it is run
Rookery runs COMMAND VERB directly, with the package directory as its working directory and in a process group of its own. Give the file a shebang and the executable bit.
| Channel | Use |
|---|---|
| Standard input | One JSON object, the request, which holds the secrets |
| Standard output | One JSON object, the answer. Empty output is read as {}. logs writes the log here instead |
| Standard error | Progress. Each line is shown as it comes |
| Exit code | 0 is success. Anything else is a failure, and the last five lines of standard error are the reason |
When the command ends, Rookery ends everything it started in the process group. Do not leave anything running in the background.
| Verb | Time allowed |
|---|---|
status, list, an act that only reads | 30 seconds |
start, stop, destroy, change | 5 minutes |
create, exec, an act that changes something | 15 minutes |
logs | Until it ends, or the one who asked stops reading |
A command that takes longer is killed with its group.
The request
Every verb gets this:
| Field | Value |
|---|---|
version | 2. A provisioner refuses another version |
verb | The verb |
provisioner | The id within the plugin, so one command can serve several provisioners |
arguments | The values of the arguments that apply, with defaults filled in. The provisioner's own come from what was given or from its settings. A verb about a machine also gets those of the machine kind |
secrets | The secrets it names that have a value |
A verb about one resource also gets these. status without an id, list and an action of the provisioner itself are about the provisioner and have none of them. An action of a kind is about one resource and has them.
| Field | Value |
|---|---|
kind | machine, or the kind's id |
name | The resource's name. A machine's is the host's |
host | The host's name, for a machine |
id | The id create answered with, once it has |
labels | For a machine, rookery-host with the host's name and rookery-instance with the token. For another kind, rookery-resource with Rookery's id of the resource and rookery-token with the token |
node | The node the provisioner is on, when a node's apply registered it. The node's controller dials its endpoints |
The verbs about a resource get the arguments that create was given, with defaults for any argument added since. A resource of any other kind gets the provisioner's own arguments and its kind's.
Each verb adds to it and answers like this:
| Verb | Request adds | Answer |
|---|---|---|
create | token. For a machine, seed or access. For another kind, environment, and spec when the kind has one | id, and optionally address, port and endpoints |
status | id | state, which is running, stopped or gone, and optionally address and endpoints. Rookery shows gone as missing |
status | nothing | The provisioner itself: state (ready unless it says otherwise), message, details, values, collections |
destroy | id | {} |
start, stop | id | {}, and optionally state and endpoints |
change | id, the new values in arguments, changed with the names of the arguments whose value is new, and environment. For a kind with a specification, spec: the new one, or the one Rookery has | state, and optionally endpoints |
exec | id, command as a list of words, and stdin when there is input | exit_code, the command's exit status. Its output goes to standard error |
logs | id, tail and follow | The log on standard output, a line at a time, until it ends |
list | nothing | resources, a list of id, kind, name, host and state, of every kind |
act | action: its name and its arguments. For an action of a kind, also environment, and spec when the kind has one | message, and optionally details |
create must answer with an id. Rookery keeps it, and every later verb uses that id. For a machine, the address and port go into the profile's access.address and access.port when those are empty. Entries of list without an id are dropped. An entry without a kind is a machine, and one without a name takes its host as its name.
spec is the specification as the person gave it, as text. environment maps variables to the values of the Rookery secrets the resource is given, such as {"DB_PASSWORD": "…"}. It is empty for a resource without secrets. Pass these values on only through the environment of the program that needs them, and Rookery masks them in your output as it does secrets.
For logs, tail is how many of the last lines to give, and follow whether to go on with what comes after them. Give a machine's console, or its boot output when the console has none. An empty log is no failure.
While Rookery waits for a new machine, it asks logs of the machine kind with each status, until SSH answers, with tail at 100 and follow false. It shows the lines it has not shown before. Rookery removes escape sequences and control characters, shortens long lines and shows at most six lines at a time. It hides the provisioner's secrets and those of the seed. A kind without logs is waited for without them.
Endpoints
An answer about one resource may report where it is reached, as endpoints. Rookery keeps the list with the resource's record, and an answer with endpoints replaces it whole. An answer without them leaves the list as it was, and a resource that is gone has none. Report them from create, status and change, so they follow what is there, and from start and an act that makes it anew when those know.
{"state": "running",
"endpoints": [{"name": "8080", "address": "127.0.0.1", "port": 8080, "hint": "http", "local": true},
{"name": "bridge-80", "address": "172.17.0.2", "port": 80, "hint": "http", "local": true}]}| Field | Value |
|---|---|
name | Unique within the resource. Lowercase letters, digits, -, _ and ., up to 63, starting with a letter or a digit |
address | An IP address or a DNS name, as seen from the machine your engine runs on |
port | 1 to 65535 |
protocol | tcp, the default, or udp |
hint | What speaks there, such as http or postgres. Rookery shows it to people and doesn't read it |
local | true when your engine runs on the machine that dials: the one Rookery runs on, or the node in the request |
Rookery leaves out an endpoint that does not fit, and the first of two with the same name stands. resources.connect dials only what you report. It dials from the server, or from the node when the request has node. Report local only for an engine on the server's own machine or on that node, as a loopback address is then the dialling machine's. With node, report addresses as the node sees them: 127.0.0.1 for a port published on every address, and the addresses of the node's bridges. For an engine elsewhere, report addresses that other machines can connect to, such as a port published on the engine's own name. Leave out the addresses only its machine routes to.
Commands
A kind with exec among its verbs gets Rookery's action exec (Run a command in it). Rookery sends the command as a list of words in command, never as one line for a shell. Run it as it is, with stdin on its standard input when the request has it. Write its output to standard error as it comes. Answer with its exit_code. Exit with 0 even when the command fails; exit with another code only when you could not run it, such as when the resource is not running. Rookery records the command line in the job, and not the input.
details is a list of rows, each {"label": …, "value": …}, which Rookery shows as they are, such as a pool and how full it is. values names, by argument, the values an argument takes here, such as {"pool": ["default", "fast"]}. Rookery offers those in place of what the manifest says.
collections gives the items of each collection, by its id. An item has a name and a key with a value for each part. Its columns hold its values by name. unavailable gives the item actions that cannot run on it, each with why not. The key of a collection whose key has one part may be left out: it is the name. Rookery leaves out an item without its whole key, and a collection left out of the answer is shown as not listed.
"collections": {
"pools": [
{"name": "default", "columns": {"driver": "zfs", "size": "100.0 GiB"}},
{"name": "fast", "columns": {"driver": "dir", "size": "200.0 GiB"},
"unavailable": {"resize-pool": "A dir pool has no size of its own"}}
],
"volumes": [
{"name": "data", "key": {"pool": "default", "volume": "data"}, "columns": {"size": "10GiB"}}
]
}A status without an id that fails is shown as unreachable, with the reason. Answer it quickly, because Rookery asks it each time the provisioner's page opens.
A seed provisioner also receives the cloud seed with create:
| Field | Value |
|---|---|
seed.user_data | The cloud-init user data |
seed.meta_data | instance-id and local-hostname, as text |
seed.archive | With archive: true: path of the release archive on the machine Rookery runs on, and its sha256 |
An archive has to end up as /opt/rookery-bootstrap/release.tar.gz in the machine. First boot waits up to 15 minutes for the file to have that digest.
An apply provisioner receives access: the user to create and the public_keys that may log in as it. It must make SSH answer for that account.
A create request and its answer, with the secrets left out:
{
"version": 2,
"verb": "create",
"kind": "machine",
"name": "studio-2",
"host": "studio-2",
"provisioner": "vm",
"arguments": {"server": "https://192.0.2.10:8443", "cpus": "8", "image": "ubuntu-26.04"},
"secrets": {"lab_token": "…"},
"labels": {"rookery-host": "studio-2", "rookery-instance": "0b6d4f1c9a7e4e58b3d2a61f8c05e9a7"},
"token": "0b6d4f1c9a7e4e58b3d2a61f8c05e9a7",
"seed": {
"user_data": "#cloud-config\n…",
"meta_data": "instance-id: 0b6d4f1c9a7e4e58b3d2a61f8c05e9a7\nlocal-hostname: studio-2\n",
"archive": {"path": "/home/ops/.local/share/rookery/build/delivered/studio-2/rookery-release.tar.gz", "sha256": "…"}
}
}{"id": "lab-studio-2", "address": "192.0.2.31", "port": 22}An action and its answer:
{
"version": 2,
"verb": "act",
"provisioner": "vm",
"arguments": {"server": "https://192.0.2.10:8443"},
"secrets": {"lab_token": "…"},
"action": {"name": "pools", "arguments": {}}
}{"message": "2 storage pools on https://192.0.2.10:8443",
"details": [{"label": "default", "value": "zfs · 40 GiB of 200 GiB used"},
{"label": "fast", "value": "dir · 3 GiB of 50 GiB used"}]}Rules
A provisioner is run again after a crash or a timeout, and it works on machines that belong to people. Keep these rules:
- Create once per token. Called again with the same
token,createanswers with the machine it made before and does not make a second one. - Label what you make. Put
labelson the machine in whatever way the platform allows. - Destroy a machine that is gone.
destroysucceeds when there is nothing left to delete, and deletes only the machine with theidit is given. - Leave alone what lacks Rookery's labels.
listshows, anddestroy,changeand the actions touch, only what has them. An action that frees space removes only what Rookery made. - Write progress to standard error. Standard output is for the answer.
- Take secrets from standard input only. That includes the values in
environment. Never print them, and do not put them on a command line or in a file that stays after the command ends. Rookery hides secrets in the lines you write, but it cannot hide what you write elsewhere.
Try it
Install the plugin from its folder and see that Rookery finds the provisioner and what it says of itself:
rookery plugin add ~/src/rookery-plugin-lab
rookery provisioner types
rookery provisioner add lab lab/vm server=https://192.0.2.10:8443
rookery provisioner show labRun a verb by hand from the package directory with a request on standard input. Use a scratch machine and made-up values:
echo '{"version":2,"verb":"status","provisioner":"vm","arguments":{"server":"https://192.0.2.10:8443"},"secrets":{}}' \
| bin/provision statusThen create a machine for a saved host and delete it again:
rookery host create studio-2 --provisioner lab/vm
rookery resource list # the machine's id, such as r-k3q7wz2m
rookery resource remove r-k3q7wz2mRun rookery host create --provisioner a second time while the first has failed to check that it finds the same machine.
Last updated on