Skip to Content

Resources

What provisioners made for Rookery, such as a host's machine or a deployment, and how to look after each one from the command line, the terminal UI and the API.

A resource is something a provisioner made for Rookery. A host's machine is one. A plugin can declare other kinds, such as the deployments of the Docker plugin. Rookery keeps a record of each resource in its store and looks after all of them the same way.

rookery resource list
r-k3q7wz2m   machine     studio-2 (host studio-2)   ovh-incus            running
r-p5x2hd7a   deployment  notes                      docker               running

The list comes from Rookery's records, with each resource as it was last seen. Rookery doesn't ask the provisioners for it. --provisioner NAME, --kind KIND and --host HOST narrow it.

Kinds

KindBelongs toMade with
machineA saved host, at most one machine for eachrookery host create HOST --provisioner PROVISIONER (Create the machine)
A kind its plugin declares, such as deployment or instanceNo hostrookery resource create for a deployment, the provisioner's new-KIND action, or resources.create for any kind

A provisioner's page says which kinds it makes. Each kind lists which of start, stop, change, logs and exec its provisioner takes for it, and can bring actions of its own.

What Rookery keeps of one

FieldHolds
idRookery's id, such as r-k3q7wz2m. It stays the same for the life of the record
provisioner, kind, nameWho made it and what it is. A machine's name is its host's
external_idThe provisioner's own id of it, shown as Made as. Empty until the provisioner has said it
hostThe saved host, for a machine
state, checkedHow it was when Rookery last asked, and when that was (Asked)
addressWhere it is reached, when the provisioner says
endpointsThe addresses and ports it serves on, as the provisioner last said (Endpoints)
argumentsThe values it was made or last changed with
secretsThe names of the Rookery secrets it is given, and the variable each becomes. Never their values
spec_sha256The SHA-256 of its specification, for a kind made from one
createdWhen Rookery made it

States

StateMeans
creatingA job is making it now
running, stoppedWhat the provisioner said
missingThe provisioner no longer finds it
unknownThe provisioner did not answer, or making it did not end. A Problem line says which

A missing resource keeps its record. Rookery does not forget a resource that was removed outside Rookery. Remove it through Rookery, which then forgets it. Removing something that is gone already counts as done.

Look at one

rookery resource show ID asks the provisioner how the resource is now, and keeps what it says. A name works in place of the id while only one resource has that name.

rookery resource show r-k3q7wz2m
r-k3q7wz2m  machine studio-2 of ovh-incus
State      running
Made as    rookery-studio-2
Host       studio-2
Address    192.0.2.31
Created    2026-11-12T20:14:03Z
Asked      2026-11-13T08:02:11Z
Arguments  cpus=8 disk=60GiB image=ubuntu/26.04/cloud memory=8GiB pool=default project=default server=https://192.0.2.10:8443

Actions (rookery resource run r-k3q7wz2m ACTION)
  start              Start
  stop               Stop
  change             Change
  remove             Delete the machine

Its log: rookery resource logs r-k3q7wz2m [--follow]

An action that cannot run now says why beside its name, such as a secret of the provisioner that has no value.

Its actions

ActionListed whenDoes
start, stopThe kind lists that verbStart or stop it. Stop asks first
changeThe kind lists changeGive it other values of the kind's arguments. A kind made from a specification also takes a new one, and other secrets
execThe kind lists execRun a command in it and wait for it to end (Run a command in it)
The kind's ownIts plugin declares themWhat the plugin does, such as services of a deployment
removeAlwaysRemove it with its provisioner and forget the record. For a machine, the host's profile stays
rookery resource actions r-k3q7wz2m
rookery resource run r-k3q7wz2m stop
rookery resource set r-k3q7wz2m cpus=4 memory=16GiB
rookery resource logs r-k3q7wz2m --tail 50 --follow
rookery resource remove r-k3q7wz2m

run and remove put the action's question first, unless --yes is given. In a terminal, run prompts for a required argument you leave out. An action that only reads answers at once. One that changes something runs as a job and shows its output as it comes. Rookery then ends with the job's exit code.

change takes what is given and keeps the rest. For a kind made from a specification, --spec FILE gives a new one and - reads it from standard input. --secret NAME[:VARIABLE] gives the secrets it gets. Given once, it replaces the whole list.

logs prints the last 100 lines, or --tail N. --follow goes on with what comes after them until the log ends or you stop it. A Rookery server ends a followed log after an hour. Lines that contain a secret show [secret] in its place.

Endpoints

A resource's endpoints say where it listens, as a list of addresses and ports. Its provisioner reports them each time it makes, changes or checks the resource. After a container restarts with a new address, its next check reports the new one. When the resource is gone, Rookery clears the list.

FieldHolds
nameUnique within the resource, such as 8080 or web-80
addressAn IP address or a DNS name
portThe port
protocoltcp or udp
hintWhat speaks there, for people, such as http or postgres. It may be empty
localtrue when the provisioner's engine runs on the machine that dials it: the server's own, or the node the provisioner is on

An address is as seen from the machine the provisioner's engine runs on, such as the Docker engine or the Incus server. With local, that machine is the one that dials. For a provisioner on the server's machine, the server then dials the address as it is, 127.0.0.1 among them. Without local, 127.0.0.1 names the engine's machine, and the server refuses to dial it. For an engine elsewhere, a provisioner reports addresses that other machines can connect to, such as the engine's own name.

A change in the endpoints is a change of the resource for events.follow, so a follower of resources hears of it.

Reach an endpoint

resources.connect opens a TCP connection to one endpoint, through the server (The stream of an endpoint). The caller names the endpoint by its name or its port, and needs the role operate.

The server dials only what the provisioner reported. When it dials, it reads the resource's endpoints again and resolves the address then. It refuses:

WhatWhy
An endpoint the provisioner did not reportThe tunnel is not a way to an address of the caller's choosing
A UDP endpointA tunnel is a TCP connection
A cloud's metadata address, 169.254.169.254 or fd00:ec2::254It hands credentials of the server's machine to whoever asks
A loopback or link-local address, unless the endpoint is local and reports that very addressSuch an address is the server's own. A name that resolves to one now, or one an engine elsewhere reported, is not what the provisioner meant

Who dials depends on where the provisioner is:

ProvisionerWho dialsHow
On a node, registered by its applyThe node's controllerThe server opens the connection through the link it has to the node. 127.0.0.1 is the node's loopback, and any other address has to be on a network of the node's own
Any otherThe serverFrom its own machine, with the checks above

The server is right for an engine on its own machine or on a network it routes to. A node's controller is right for a container on a bridge such as incusbr0 or docker0, which only the node routes to.

For a provisioner on a node, the server still refuses an endpoint that was not reported, a UDP endpoint and a metadata address. The node's controller then refuses:

WhatWhy
A loopback address other than 127.0.0.1The controller reaches the node's loopback at 127.0.0.1 alone
A link-local or metadata addressIt hands credentials of the node to whoever asks
An address on none of the node's networksSuch an address is reached through a router, which is not the node's to offer

When the node cannot be reached, the stream fails with 502 unreachable. A node whose controller is older than this gives 501 not_available: update its controller or apply the node.

Run a command in it

The action exec runs a command in a resource whose kind has it, such as a Docker or an Incus instance. Its provisioner runs it, and the server waits for it to end.

ArgumentHolds
commandThe words of the command, split at spaces, or a JSON list such as ["sh", "-c", "echo hi"] for a word with spaces in it
stdinWhat the command reads on its standard input. Empty gives it none

It runs as a job of the resource, and needs the role operate. It does not hold the resource's lock, so several commands can run at once. The job's output is the command's, and the job ends with the command's exit status. The job records the command line, but not the standard input. Give a secret on standard input, never on the command line.

curl -X POST "$ROOKERY/v1/resources/r-m4t8qv2c/actions/exec" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"arguments": {"command": "psql -U app", "stdin": "select count(*) from notes;"}}'

A host's machine

A host's machine is a resource of the kind machine. These short forms go by the host's name:

CommandIs the same as
rookery host create HOST --provisioner PROVISIONER [NAME=VALUE…]Making the machine and setting it up as the host
rookery resource show HOSTrookery resource show ID
rookery host start HOST, rookery host stop HOSTrookery resource run ID start, rookery resource run ID stop
rookery host remove HOST --destroyrookery resource remove ID, and then forgetting the host

rookery host remove HOST without --destroy forgets the host and keeps its machine's record as a resource with no host. A duplicate's machine is planned until it's made: its record keeps the provisioner and the arguments to make it with (Duplicating a host).

Records, tokens and locks

Rookery writes a resource's record before it asks the provisioner to make anything. The record has a token, which goes to the provisioner with create. When making it fails or Rookery stops halfway, asking again with the same provisioner and name sends the same token. The provisioner then finds what it made before and does not make a second one. A record whose making did not end shows the state unknown with a problem that says so. remove then forgets the record only.

A host's machine is kept beside the host's profile, and every other resource in the installation's own part of the store. A specification is kept in a row of its own, so listing resources reads none. Like every value of the store, both are sealed when the store is encrypted.

Each change is a job whose subject is resource:ID, and it holds the resource's lock while it runs. A second change to the same resource is refused until the first has ended. A host's machine shares the host's lock, so applying the host and changing its machine exclude each other.

A caller of the API can give a token of its own, as token in a request. The same token again answers with the job the first call started, and nothing runs a second time.

In the terminal UI

The Provisioners tab of the home screen (2) lists the provisioners. Enter opens a provisioner's page, which lists what it holds, grouped by kind:

Machines rookery made with it
  studio-2           rookery-studio-2  running
Compose project rookery made with it
  notes              notes  running
  attic              attic  running · no record of it

An entry the provisioner lists with Rookery's labels, but that Rookery has no record of, is marked no record of it. Rookery does not remove it.

Enter on an entry opens the resource's page. It shows the resource's state and fields, and its actions in their groups. Show its log is there when its kind gives logs, and follows the log in a panel until you close it. Esc goes back to the provisioner's page. Rookery on macOS and Windows has the same tab (On other systems).

A host's machine is also on the host's Run tab, with its state and rows to start, stop and delete it.

With a Rookery server

With a Rookery server set, rookery resource list, rookery resource create and the short forms use the server's resources. What changes one runs as a job there, with the server's plugins, secrets and provisioner settings.

OperationRouteRole
resources.listGET /v1/resources, with provisioner, kind or host to narrow itview
resources.getGET /v1/resources/{id}view
resources.createPOST /v1/resources. Answers 202 with the resource and its jobadmin
resources.changePUT /v1/resources/{id}, as a jobadmin
resources.removeDELETE /v1/resources/{id}, as a job. A token goes in ?token=admin
resources.actionsGET /v1/resources/{id}/actionsview
resources.actPOST /v1/resources/{id}/actions/{action}The action's own
resources.logsGET /v1/resources/{id}/logs?tail=N, as plain textoperate
resources.followA WebSocket at the same path. The lines come as binary frames, then {"exited": …}operate
resources.connectA WebSocket at /v1/resources/{id}/endpoints/{endpoint}: a TCP connection to the endpointoperate

An action of a resource needs admin unless its plugin says otherwise, including one that only reads. exec needs operate. Requests and answers are in the API reference.

With serve_setup off, a server takes changes to resources only on its own socket, not over the network (Closing set-up).

Edit on GitHub

Last updated on

On this page