Skip to Content

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 types
docker/container     Docker container  · makes machine, deployment
incus/container      Incus container  · makes machine
incus/vm             Incus virtual machine  · makes machine

Register 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/container

Names 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 list
docker  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=VALUE

One 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 set

The 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 docker
docker  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 behind

Rookery asks the provisioner how it is each time. The lines under the state are what it says, shown as they are.

StateMeans
readyIt answered. Its message says how it is
unreachableIt did not answer, as when the engine or server is down. The message says why
unusableRookery 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=lab

Every 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.crt

The 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=yes

In 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.

KindThe new machineRookery waits forWhat the profile needs
seedBoots with Rookery's cloud seed made from the profile and sets itself uprookeryd to answer, up to 30 minutes. It then prints the machine's provision stateWhat rookery host seed needs. A provisioner that puts the release archive into the machine itself does without a release_url
applyStarts with SSH and an account for RookerySSH to answer, up to 5 minutes. Rookery then applies the profile as rookery apply doesAn 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 │.

WhatWhen
The machine's state and addressWhen the provisioner reports a new one
The latest lines of the machine's consoleUntil SSH answers, from provisioners whose machines have logs
SSH answersOnce Rookery can log in
The first boot's state, its steps and the Ansible task it is atAfter SSH answers, for a seeded machine
rookeryd answersWhen the host is ready
still waiting and the time so farAfter 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 answers

Reading 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.key

Rookery refuses to start while a required secret has no value.

Create it

rookery host create studio-2 --provisioner ovh-incus cpus=8

Rookery 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:

TabShows
InstallProvisioner, a choice like any other. Space or Enter switches to the next one, and → chooses from the suggestions. Under it the required arguments, marked *
SettingsUnder Machine, the resources it has, such as CPUs, memory and disk. Under Provisioner Options, its other arguments
RunCreate 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-2
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]

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 failedWhat is leftTo go on
Before the provisioner gave an idA record with a token, and perhaps a machinerookery 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 applyThe machine and its record. The message says soFix 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 --destroy

Rookery 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.

WhatRole
The list, the types, a provisioner's page and its actionsview
Registering and removing a provisioneradmin
An action of a provisionerIts own: admin for one that changes something, view for one that only reads, unless the plugin says otherwise
Looking at what it madeview
Creating, changing, starting, stopping and deleting what it madeadmin

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.

ActionDoes
engineSays the engine's version, its runtimes and how many machines Rookery made there
imagesLists the engine's images with their sizes
volumesLists the volumes Rookery made, and whether a container uses each
buildBuilds the image the plugin brings ahead of the first machine
pruneRemoves 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=sysbox

Incus

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.

ActionDoes
serverSays the server's version and whether it trusts Rookery
poolsLists the storage pools in a table with the driver, source, size, used and free space of each, and whether it can grow
images, networks, volumesList the images the server keeps, its networks and the custom volumes of every pool
create-pool, remove-poolCreate and remove a storage pool
resize-poolGrows 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-poolSets 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-volumeCreate and remove a custom volume
resize-volumeGives a custom volume a new size. A block volume only grows
resize-diskGrows 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-imageRemoves 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-incus
Edit on GitHub

Last updated on

On this page