Provisioners
Have a plugin create the machine for a saved host on Docker, Incus or another platform, and look after the platform from its provisioner's page.
A provisioner creates the machine a host's profile describes, such as a container or a virtual machine. Rookery runs it and keeps a record of the machine in its store, as a resource. From then on the machine is an ordinary host. Some provisioners make other kinds of resources too, such as the deployments of the Docker plugin.
Plugins bring the types of provisioner, such as incus/vm or docker/container. Each provisioner you register is of one type and has a name of your own, such as ovh-incus. It works like a registry. Each keeps settings and secrets of its own. Register as many of one type as you have servers or engines.
A provisioner is also a place of its own, with a page that says whether the platform answers and lists what Rookery made there. The actions on that page come from the plugin, such as listing images or removing what Rookery left behind.
Each host has at most one machine made this way.
Register a provisioner
A node registers the provisioners of its engines by itself when it is applied, such as big-incus-vm. Register one by hand for an engine that is not a node's.
See the types the plugins bring:
rookery provisioner typesdocker/container Docker container · makes machine, deployment
incus/container Incus container · makes machine
incus/vm Incus virtual machine · makes machineRegister one under a name, with the values of its own arguments:
rookery provisioner add ovh-incus incus/vm server=https://192.0.2.10:8443
rookery provisioner add docker docker/containerNames take lowercase letters, digits, - and _, and start with a letter. The type stays as it was registered. To use another, register one under another name. See which provisioners you have, and whether each can be used here:
rookery provisioner listdocker Docker container (docker/container)
ovh-incus Incus virtual machine (incus/vm) · not usable: ovh-incus needs the secrets incus_client_cert, incus_client_key: rookery provisioner run ovh-incus secrets incus_client_cert=VALUE incus_client_key=VALUEOne that cannot be used says what to change, such as a secret to set or a plugin to update. rookery provisioner list lists the same with what each asks for:
ovh-incus Incus virtual machine
A KVM guest on an Incus server, set up from rookery's cloud seed. The server needs KVM.
· makes machines that set themselves up from the cloud seed
· actions server, pools, images, networks
· also start, stop, list
· asks server
· asks cpus (default 4)
· secret incus_client_cert, not setThe listing is shortened here. A secret marked not set is required and has no value yet.
In the terminal UI, a on the Provisioners tab adds one. It asks for the name and then the type.
rookery provisioner rename NAME NEW gives a provisioner another name. It keeps its id. Its settings, its secrets, the resources and machines it made or plans, and its jobs stay with it, and what it made is not touched. The action rename on its page does the same.
rookery provisioner remove NAME forgets a provisioner, with its settings and its own secrets. Rookery refuses while it holds anything, so remove what it made first. The action remove on its page does the same. The action adopt makes one you registered the provisioner of a node that reaches the same server.
A provisioner's page
rookery provisioner show dockerdocker Docker container
State ready · Docker 27.5.1 answers at ssh://ops@192.0.2.10
Endpoint ssh://ops@192.0.2.10
Engine 27.5.1
Runtimes io.containerd.runc.v2, runc, sysbox-runc
Machines rookery made 1
Settings host=ssh://ops@192.0.2.10
Machines rookery made with it
studio-2 rookery-studio-2 running · r-k3q7wz2m
Compose project rookery made with it
notes notes running · r-p5x2hd7a
Actions (rookery provisioner run docker ACTION)
Create
new-deployment New compose project
new-instance New container from an image
Set-Up
settings Change settings
adopt Make it a node's
rename Rename
remove Remove provisioner
Engine
engine Check the engine
images Images
pull-image Pull image
remove-image Remove image
build Build the image
Storage
volumes Volumes
create-volume New volume
remove-volume Remove volume
prune Remove what rookery left behindRookery asks the provisioner how it is each time. The lines under the state are what it says, shown as they are.
| State | Means |
|---|---|
ready | It answered. Its message says how it is |
unreachable | It did not answer, as when the engine or server is down. The message says why |
unusable | Rookery does not ask it, because a secret or a setting is missing, or the plugin is of an older version |
What Rookery made is listed by kind, each with Rookery's id of the resource and the state the provisioner lists for it. One the provisioner lists with Rookery's labels, but that Rookery has no record of, is marked Rookery has no record of it. Rookery does not delete it. Resources says how to look after each one.
Settings
A provisioner's own arguments say where it is, such as the Incus server or the Docker host. Rookery keeps their values as the provisioner's settings, in its store:
rookery provisioner set ovh-incus server=https://192.0.2.10:8443 project=labEvery call to the provisioner uses them, and so does each machine made with it unless rookery host create --provisioner is given another value. The record of a machine keeps the values it was made with, and an empty setting is forgotten. While a setting it needs has no value, Rookery prompts for it before each action.
rookery provisioner show NAME SETTING=VALUE… asks another place this once, such as rookery provisioner show ovh-incus server=https://192.0.2.11:8443.
Secrets
The plugin declares the secrets its provisioners need, such as incus_client_cert. Each provisioner has its own, which belong to it: they keep with it through a rename and go when it is removed. Rookery gives a provisioner its own secrets alone, never a secret of the same name that is not its own. Each is set as the secret provisioner/NAME/SECRET, where NAME is the provisioner's name or id, and rookery secret set reads it from standard input:
rookery secret set provisioner/ovh-incus/incus_server_cert < server.crtThe action secrets on the provisioner's page takes each in a hidden field. An empty value keeps what it has, and - forgets it. The Secrets tab of the terminal UI leaves them out. A provisioner a node offers gets the client certificate the node trusts as its own, at each apply of the node.
Actions
rookery provisioner actions docker
rookery provisioner run docker images
rookery provisioner run docker prune volumes=yesIn a terminal, run prompts for a required argument you leave out. It puts the action's question first, unless --yes is given. An action that only reads, such as images, answers at once. One that changes something runs as a job and shows its output as it comes. Only one such job runs at a time for a provisioner.
In the terminal UI, the Provisioners tab of the home screen (2) lists the provisioners, and a registers one. Enter opens a page, which lists the actions in their groups and what Rookery made there, by kind. Enter on an action shows its question and then a dialog for its arguments. A job's output fills a panel. An argument of several lines, such as a Compose file, keeps the line breaks of what you paste. Each shows as ⏎. Enter on something Rookery made opens its resource's page, and Esc comes back.
Seed and apply
A provisioner sets up the new machine in one of two ways. The plugin chooses.
| Kind | The new machine | Rookery waits for | What the profile needs |
|---|---|---|---|
seed | Boots with Rookery's cloud seed made from the profile and sets itself up | rookeryd to answer, up to 30 minutes. It then prints the machine's provision state | What rookery host seed needs. A provisioner that puts the release archive into the machine itself does without a release_url |
apply | Starts with SSH and an account for Rookery | SSH to answer, up to 5 minutes. Rookery then applies the profile as rookery apply does | An SSH user, access.user |
For an apply provisioner the account is the profile's SSH user. It takes Rookery's own key and the keys of the profile's operator. If that user's sudo asks for a password, Rookery asks for it at the terminal. A script gives it with --sudo-password-stdin, or keeps it as the secret sudo/HOST.
A provisioner may report the machine's address and SSH port. Rookery writes them to access.address and access.port of the profile, but only where those are empty. A machine just made has a new SSH host key, so Rookery forgets the host key it recorded for the host and records the new one at the first login.
A seeded machine whose address Rookery does not know is not waited for. Rookery says so and ends. The machine sets itself up on its own, and you set access.address to reach it.
While Rookery waits
The first boot of a seeded machine installs everything and can take most of the 30 minutes. Rookery says what it can find out as it goes, and each thing only once. Lines that come from the machine start with │.
| What | When |
|---|---|
| The machine's state and address | When the provisioner reports a new one |
| The latest lines of the machine's console | Until SSH answers, from provisioners whose machines have logs |
SSH answers | Once Rookery can log in |
| The first boot's state, its steps and the Ansible task it is at | After SSH answers, for a seeded machine |
rookeryd answers | When the host is ready |
still waiting and the time so far | After a minute without any other line |
▸ studio-2: waiting for rookeryd to answer (up to 30 minutes)
▸ studio-2: its machine is running at 192.0.2.31
│ [ OK ] Started ssh.service - OpenBSD Secure Shell server.
✓ studio-2: SSH answers
│ first boot: provisioning
│ Installing Ansible
│ Applying the role
│ Ansible task 87: Install the desktop
… studio-2: still waiting, 12 minutes so far
│ Ansible task 214: Configure the browser
│ first boot: configured
✓ studio-2: rookeryd answersReading the first boot's log needs sudo on the machine. The seed gives the operator sudo without a password, so Rookery doesn't need one for it. An SSH user without such sudo sees the first boot's state only.
When the first boot fails, Rookery stops waiting at once and shows the last lines of its log. The machine tries again by itself every 10 minutes. Rookery hides the secrets in the seed, such as password hashes and the enrollment key, in every line it shows.
Create the machine
Save the host
Make the profile as for any host. The provisioner works from the saved profile.
Store the secrets
A provisioner that needs provider credentials lists them as secrets. Store them as the provisioner's own:
rookery secret set provisioner/ovh-incus/incus_client_cert < rookery.crt
rookery secret set provisioner/ovh-incus/incus_client_key < rookery.keyRookery refuses to start while a required secret has no value.
Create it
rookery host create studio-2 --provisioner ovh-incus cpus=8Rookery asks Create a machine for studio-2 with Incus virtual machine (ovh-incus)? [y/N]. --yes answers it. Arguments are NAME=VALUE. An argument that is required and has no default is asked for in a terminal when you leave it out. The others take their defaults.
The output of the provisioner and of the set-up follows as it runs. Rookery ends when the host answers, or says what failed.
In the terminal UI, choose Create a machine under How To Install on the host's Install tab. The arguments of the provisioner are spread over the tabs:
| Tab | Shows |
|---|---|
| Install | Provisioner, a choice like any other. Space or Enter switches to the next one, and → chooses from the suggestions. Under it the required arguments, marked * |
| Settings | Under Machine, the resources it has, such as CPUs, memory and disk. Under Provisioner Options, its other arguments |
| Run | Create with PROVISIONER, and every problem |
The first provisioner is chosen when the list arrives. There is no Target row. A created machine always has the target cloud. Rookery writes that into the profile before it creates the machine, on the command line as well. Enter on an argument changes it. A missing secret is a problem of the Install tab, and a bad resource value one of the Settings tab. Create with PROVISIONER on the Run tab asks once before it saves the profile and starts, and does not start while a problem is listed. The output is shown as it runs. The screens are the same with a Rookery server elsewhere.
Only one thing runs at a time for a host. A second command for the same host is refused until the first ends.
Look after the machine
The machine is a resource of the kind machine. rookery resource show shows it by the host's name, as it does by its id:
rookery resource show studio-2r-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]The state comes from the provisioner each time you ask. A machine the platform no longer has is missing, and its record stays until you delete it through Rookery (States).
rookery host start HOST and stop go through the provisioner when it offers them. The actions above say which, and so does the host's power (Starting and stopping). The Run tab shows the machine's state and a Start and Stop row in the same cases, whatever install method is chosen.
When it fails
What happens depends on how far it got.
| It failed | What is left | To go on |
|---|---|---|
| Before the provisioner gave an id | A record with a token, and perhaps a machine | rookery host create HOST --provisioner PROVISIONER again with the same provisioner. The provisioner finds the machine by the token and does not make a second one |
| After it gave one, such as a boot that did not finish or a failed apply | The machine and its record. The message says so | Fix the cause and wait, or rookery apply HOST for a failed apply. rookery resource remove ID deletes the machine to start again |
A record without a machine is shown with a problem that says creating it did not end. Asking for a different provisioner while it exists is refused. rookery resource remove ID then forgets the record only. A machine the provisioner made anyway is not deleted.
Delete the machine
rookery host remove studio-2 --destroyRookery asks before it deletes anything, names the machine, and -y answers yes. It deletes the machine and then forgets the host. To delete the machine alone and keep the profile, use rookery resource remove ID. Either runs the provisioner's destroy with the id it kept, never another, and then removes the record. A machine that is gone already counts as deleted. If deleting fails, the host and the record stay so you can try again.
The host's node on the tailnet is not removed. Remove it in the tailnet's admin console.
Deleting needs the provisioner's plugin and its required secrets. rookery host remove HOST without --destroy forgets the host and leaves the machine. Rookery keeps its record as a resource of the provisioner with no host, which rookery resource remove ID deletes later (Removing a host).
With a Rookery server
With a Rookery server set, the server creates the machines. Its commands and the set-up tabs go to the server, and the provisioner runs on the server's machine with the server's plugins, secrets and provisioner settings. Creating and deleting a machine are jobs there of the subject resource:ID, named create and remove, and their output follows as for an apply. An action of a provisioner that changes something is a job there too, of the subject provisioner:NAME.
| What | Role |
|---|---|
| The list, the types, a provisioner's page and its actions | view |
| Registering and removing a provisioner | admin |
| An action of a provisioner | Its own: admin for one that changes something, view for one that only reads, unless the plugin says otherwise |
| Looking at what it made | view |
| Creating, changing, starting, stopping and deleting what it made | admin |
Resources lists the operations with their roles.
A server with serve_setup off does not take set-up over the network, only on its own socket (Closing set-up).
Credentials stay where Rookery runs
Provider credentials are Rookery secrets, shared by a type or a provisioner's own. They are kept in a file that only its user can read, on the machine that runs Rookery. With a server, that is the server. Rookery gives a provisioner only the secrets its plugin names, under those names, on its standard input. Rookery does not write the request anywhere. Lines of the provisioner's output that contain one show [secret].
A provisioner is a program that runs as you
It runs with the rights of the user Rookery runs as, and it gets the credentials it names. Install only provisioner plugins you trust.
The plugins that come with Rookery
The documentation site does not show the guides of these plugins. Each is a guide.md beside the plugin's package.json, under plugins/ in the Rookery source, and lists every argument and the limits.
Docker
A provisioner of the type docker/container makes an Ubuntu 26.04 container with systemd and an SSH server on the local Docker or on the engine named by host, such as ssh://ops@192.0.2.10. Rookery applies the profile to it over SSH. The container is named rookery-HOST and has the labels rookery-host and rookery-instance. It offers start, stop, change, logs and list, and takes no secrets.
The same provisioner runs Compose projects on that engine as deployments.
For an engine at ssh://user@address, the provisioner only sets DOCKER_HOST, and Docker starts the system's ssh with your own SSH configuration and known hosts. It does not use Rookery's recorded host key of that server or Rookery's key. The address has to be in your own known hosts, so log in once with plain ssh first. The account's key has to be one your ssh offers, from your configuration or agent. ssh cannot ask for a password.
| Action | Does |
|---|---|
engine | Says the engine's version, its runtimes and how many machines Rookery made there |
images | Lists the engine's images with their sizes |
volumes | Lists the volumes Rookery made, and whether a container uses each |
build | Builds the image the plugin brings ahead of the first machine |
prune | Removes the plugin's images of older versions that no container uses. With volumes=yes it also removes the volumes Rookery made that no container uses, with the agent's work in them |
The container runs privileged by default. With runtime=sysbox it runs under Sysbox instead, which the Docker host needs to have. Read the limits in plugins/docker/guide.md before you use an engine that others share. In the container Chromium uses its setuid sandbox helper, as the self-test describes.
rookery host create studio-2 --provisioner docker runtime=sysboxIncus
A provisioner of the type incus/vm makes a virtual machine, and one of incus/container a system container, on an Incus server. Both are set up from the cloud seed, and the plugin puts the release archive into the machine. The profile does without a release_url. They offer start, stop, change, logs and list. In a container Chromium uses its setuid sandbox helper, and in a virtual machine a user namespace, as the self-test describes.
Rookery talks to the Incus API over HTTPS. server is required, as a setting or for each machine. Incus must trust a certificate of Rookery, which you store as the provisioner's own secrets incus_client_cert and incus_client_key. The secret incus_server_cert is optional and pins the server's own certificate. plugins/incus/guide.md shows how to make and trust the certificate.
The page offers the server's pools, networks and instances for the arguments pool, network and instance.
| Action | Does |
|---|---|
server | Says the server's version and whether it trusts Rookery |
pools | Lists the storage pools in a table with the driver, source, size, used and free space of each, and whether it can grow |
images, networks, volumes | List the images the server keeps, its networks and the custom volumes of every pool |
create-pool, remove-pool | Create and remove a storage pool |
resize-pool | Grows a loop-backed btrfs, zfs or lvm pool to size. It refuses a dir pool, a pool on a disk or dataset given when it was made, and any smaller size, as Incus never shrinks a pool |
set-pool | Sets a setting key of a pool that Incus changes once the pool is made, such as description or volume.size, to value |
create-volume, remove-volume | Create and remove a custom volume |
resize-volume | Gives a custom volume a new size. A block volume only grows |
resize-disk | Grows the root disk of instance to size. A container has it at once. A running virtual machine needs a restart, which happens only with restart=yes |
remove-image | Removes a cached image |
A size is a whole number and a unit, such as 50GiB or 200GB. The plugin checks it before it asks Incus. plugins/incus/guide.md has what each driver allows.
rookery provisioner add ovh-incus incus/vm server=https://192.0.2.10:8443
rookery host create studio-2 --provisioner ovh-incusLast updated on