Skip to Content

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

~/.config/rookery/plugins/hello/package.json
{
  "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

package.json
guide.md
cli.yml
editor.yml
package.json
{
  "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:

VariableValue
rookery_user, rookery_homeThe agent's account and home
rookery_plugin_dirThe package's directory, for files it brings
rookery_plugin_featuresEvery feature chosen for the host
rookery_software_rendering, rookery_profileAnd 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:

FactWhat it adds
rookery_firewall_rulesRules 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_unitsUnits whose state rookeryd reports, such as incus
rookery_offerThe 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.

FieldMeaning
provisionersThe ids it offers now, out of offers. All of them when it is left out
settingsValues 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
secretsValues of the provisioners' secrets, such as a server's certificate, kept as each provisioner's own
aliasesOther 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
fingerprintWhat 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:

guide.md
{% 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.

package.json
{
  "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:

FieldMeans
name, label, helpAs for a host's action
groupThe group of the provisioner's page it is listed in
argumentsWhat it asks for
confirmThe question to answer yes to first

It also takes these:

FieldDefaultMeans
changestruefalse 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
roleadmin. An action of the provisioner with "changes": false is viewThe 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:

FieldMeans
actionThe name of the provisioner's action
labelWhat it is called where the item is known, such as Grow. The action's own label when empty
argumentsThe 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:

OnOff
yes, true, on, 1no, 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.

ArgumentWhere Rookery shows it
requiredOn the Install tab, under the Provisioner row
"kind": "resource", not requiredUnder Machine on the Settings tab
Any otherUnder 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 containsThe value has to be
cpuA positive number, such as 4
memory, mem, ram, disk, size, storage or swapA size with its unit, such as 8GiB, 512MiB or 4g
anything elseNot 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.

ChannelUse
Standard inputOne JSON object, the request, which holds the secrets
Standard outputOne JSON object, the answer. Empty output is read as {}. logs writes the log here instead
Standard errorProgress. Each line is shown as it comes
Exit code0 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.

VerbTime allowed
status, list, an act that only reads30 seconds
start, stop, destroy, change5 minutes
create, exec, an act that changes something15 minutes
logsUntil 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:

FieldValue
version2. A provisioner refuses another version
verbThe verb
provisionerThe id within the plugin, so one command can serve several provisioners
argumentsThe 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
secretsThe 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.

FieldValue
kindmachine, or the kind's id
nameThe resource's name. A machine's is the host's
hostThe host's name, for a machine
idThe id create answered with, once it has
labelsFor 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
nodeThe 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:

VerbRequest addsAnswer
createtoken. For a machine, seed or access. For another kind, environment, and spec when the kind has oneid, and optionally address, port and endpoints
statusidstate, which is running, stopped or gone, and optionally address and endpoints. Rookery shows gone as missing
statusnothingThe provisioner itself: state (ready unless it says otherwise), message, details, values, collections
destroyid{}
start, stopid{}, and optionally state and endpoints
changeid, 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 hasstate, and optionally endpoints
execid, command as a list of words, and stdin when there is inputexit_code, the command's exit status. Its output goes to standard error
logsid, tail and followThe log on standard output, a line at a time, until it ends
listnothingresources, a list of id, kind, name, host and state, of every kind
actaction: its name and its arguments. For an action of a kind, also environment, and spec when the kind has onemessage, 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.

Answer of status
{"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}]}
FieldValue
nameUnique within the resource. Lowercase letters, digits, -, _ and ., up to 63, starting with a letter or a digit
addressAn IP address or a DNS name, as seen from the machine your engine runs on
port1 to 65535
protocoltcp, the default, or udp
hintWhat speaks there, such as http or postgres. Rookery shows it to people and doesn't read it
localtrue 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:

FieldValue
seed.user_dataThe cloud-init user data
seed.meta_datainstance-id and local-hostname, as text
seed.archiveWith 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:

Request on standard input
{
  "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": "…"}
  }
}
Answer on standard output
{"id": "lab-studio-2", "address": "192.0.2.31", "port": 22}

An action and its answer:

Request on standard input
{
  "version": 2,
  "verb": "act",
  "provisioner": "vm",
  "arguments": {"server": "https://192.0.2.10:8443"},
  "secrets": {"lab_token": "…"},
  "action": {"name": "pools", "arguments": {}}
}
Answer on standard output
{"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, create answers with the machine it made before and does not make a second one.
  • Label what you make. Put labels on the machine in whatever way the platform allows.
  • Destroy a machine that is gone. destroy succeeds when there is nothing left to delete, and deletes only the machine with the id it is given.
  • Leave alone what lacks Rookery's labels. list shows, and destroy, change and 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 lab

Run 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 status

Then 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-k3q7wz2m

Run rookery host create --provisioner a second time while the first has failed to check that it finds the same machine.

Edit on GitHub

Last updated on

On this page