Provisioners
What the plugins can create machines and deployments with, their pages and their actions.
| Operation | Kind | HTTP |
|---|---|---|
provisioners.list | call | GET /v1/provisioners |
provisioners.types | call | GET /v1/provisioner-types |
provisioners.get | call | GET /v1/provisioners/{name} |
provisioners.save | call | PUT /v1/provisioners/{name} |
provisioners.remove | call | DELETE /v1/provisioners/{name} |
provisioners.actions | call | GET /v1/provisioners/{name}/actions |
provisioners.act | call | POST /v1/provisioners/{name}/actions/{action} |
provisioners.list
What the plugins can create machines and other resources with, what each asks for and can do, and whether it can be used here.
Needs the role view.
Result
{
"id": 1,
"op": "provisioners.list"
}{
"id": 1,
"result": [
{
"id": "k3v9qz2m8w1x",
"label": "text",
"setup": "text"
}
]
}provisioners.types
The types of provisioner the plugins bring, which a provisioner is registered as.
Needs the role view.
Result
{
"id": 1,
"op": "provisioners.types"
}{
"id": 1,
"result": [
{
"id": "k3v9qz2m8w1x",
"label": "text",
"setup": "text"
}
]
}provisioners.get
A provisioner's page: what it says of itself now, such as whether its engine answers, and what it holds: rookery's resources, with what its own list says.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The provisioner, by its name or its id (bare or as prov_ID) |
arguments | query | no | Values of the provisioner's own arguments as NAME=VALUE for this once, such as another server to ask; the others are its settings |
Result
| Field | Type | Description |
|---|---|---|
collections (optional) | map of CollectionItem[] | The items of each of its collections, by the collection's id, as its status gave them. |
details (optional) | Detail[] | |
message (optional) | string | What it said of itself, or why it could not be asked. |
provisioner | ProvisionerInfo | Something a plugin creates machines with, for a saved host's profile. |
resources (optional) | ListedResource[] | rookery's records of what it made, with what its own list says. |
state | string | ready, unreachable or unusable, or what the provisioner said. |
values (optional) | map of string[] | The values an argument takes here, by its name, where the provisioner narrows what it declares, such as the pools there are. |
Errors
| Status | When |
|---|---|
| 404 | No such provisioner |
{
"id": 1,
"op": "provisioners.get",
"args": {
"name": "status"
}
}{
"id": 1,
"result": {
"collections": {},
"details": [
{
"label": "text",
"value": "text"
}
],
"message": "text",
"provisioner": {
"id": "k3v9qz2m8w1x",
"label": "text",
"setup": "text"
},
"resources": [
{
"host": "studio",
"id": "k3v9qz2m8w1x",
"kind": "process",
"name": "status",
"resource": "text",
"state": "text"
}
],
"state": "text",
"values": {}
}
}provisioners.save
Register a provisioner under a name of its own, of a type a plugin brings, or change the settings of one that is registered. A registered one keeps its type.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | Its name: lowercase letters, digits, - and _, starting with a letter, and not in the shape of an id; or the id of a registered one |
Input
| Field | Type | Description |
|---|---|---|
settings (optional) | map of string | null | Values of its own arguments, such as the server it uses. Empty ones are not kept. Left out, the settings it has stay. |
type (optional) | string | The plugin's provisioner it is, as PLUGIN/ID. A registered one keeps its type: this is the same or empty. |
Result
| Field | Type | Description |
|---|---|---|
actions (optional) | Action[] | Its plugin's own actions, such as listing images or pruning. |
arguments (optional) | Argument[] | What creating a machine takes: the provisioner's own arguments first, then those of its machines. |
collections (optional) | Collection[] | What it holds that can be listed, such as storage pools, each with the actions of its items. |
description (optional) | string | |
id | string | Its id, which stays when it is renamed. In the list of types, the type itself. |
kinds (optional) | ProvisionerKind[] | What it can make: machine, and kinds its plugin names. |
label | string | |
missing_secrets (optional) | string[] | The required ones that have no value. Not looked at in a plugin's listing. |
name (optional) | string | The name it is registered under, such as ovh-incus. In the list of types, the type itself. |
node (optional) | string | The node it lives on, when a feature of that host offered it, by name. |
node_id (optional) | string | The id of that node. |
own (optional) | string[] | The names of the provisioner's own arguments, which say where it is, such as an Incus server. Their values are kept as its settings. |
problem (optional) | string | Why it cannot be used here, as a sentence that says what to change. Empty when it can. |
secrets (optional) | string[] | The rookery secrets it is given. |
settings (optional) | map of string | The values of its own arguments that are kept, by name. |
setup | string | seed: the machine boots with rookery's cloud seed and sets itself up. apply: rookery applies the profile over SSH once the machine answers. |
type (optional) | string | The plugin's provisioner it is, as PLUGIN/ID, such as incus/vm. |
verbs (optional) | string[] | What it can do besides create, status and destroy: start, stop, list, log. |
Errors
| Status | When |
|---|---|
| 400 | The name, the type or a setting does not fit; the message says which |
{
"id": 1,
"op": "provisioners.save",
"args": {
"name": "status"
},
"data": {
"settings": {},
"type": "text"
}
}{
"id": 1,
"result": {
"id": "k3v9qz2m8w1x",
"label": "text",
"setup": "text"
}
}provisioners.remove
Forget a registered provisioner, with its settings and the secrets it keeps of its own. It is kept while it holds resources.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | Its name or its id (bare or as prov_ID) |
Errors
| Status | When |
|---|---|
| 404 | No such provisioner |
| 409 | It still holds resources; the message names them |
{
"id": 1,
"op": "provisioners.remove",
"args": {
"name": "status"
}
}{
"id": 1,
"result": null
}provisioners.actions
What can be done to a provisioner: its plugin's actions, and rookery's own settings of it.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The provisioner, by its name or its id (bare or as prov_ID) |
Result
Action[]
Errors
| Status | When |
|---|---|
| 404 | No such provisioner |
{
"id": 1,
"op": "provisioners.actions",
"args": {
"name": "status"
}
}{
"id": 1,
"result": [
{
"name": "status"
}
]
}provisioners.act
Run one of a provisioner's actions. One that changes something is a job, which holds the provisioner's lock; one that only reads answers at once.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The provisioner, by its name or its id (bare or as prov_ID) |
action | path | yes | The action, as provisioners.actions names it |
Input
Its arguments, which may also give the provisioner's own for this once, and a token that makes asking again safe
Act | null
Result
| Field | Type | Description |
|---|---|---|
job (optional) | JobInfo | null | |
result (optional) | any | What an action that answers at once and changes nothing said. |
session (optional) | Session | null |
Errors
| Status | When |
|---|---|
| 400 | An argument is missing or unknown, or the body is not one |
| 403 | The caller's role is below the action's |
| 404 | No such provisioner or action |
| 409 | Something else is being done to the provisioner |
| 501 | It cannot run here now; the message says why |
| 502 | The provisioner failed, as when its engine does not answer |
{
"id": 1,
"op": "provisioners.act",
"args": {
"name": "status",
"action": "VALUE"
},
"data": {
"arguments": {},
"cols": 120,
"input_b64": "aGVsbG8K",
"rows": 40,
"sudo_password": "text",
"token": "text"
}
}{
"id": 1,
"result": {
"job": {
"id": "k3v9qz2m8w1x",
"started": "2026-11-12T09:30:00Z"
},
"result": null,
"session": {
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent"
}
}
}Types
The named types used on this page.
ProvisionerInfo
Something a plugin creates machines with, for a saved host's profile.
| Field | Type | Description |
|---|---|---|
actions (optional) | Action[] | Its plugin's own actions, such as listing images or pruning. |
arguments (optional) | Argument[] | What creating a machine takes: the provisioner's own arguments first, then those of its machines. |
collections (optional) | Collection[] | What it holds that can be listed, such as storage pools, each with the actions of its items. |
description (optional) | string | |
id | string | Its id, which stays when it is renamed. In the list of types, the type itself. |
kinds (optional) | ProvisionerKind[] | What it can make: machine, and kinds its plugin names. |
label | string | |
missing_secrets (optional) | string[] | The required ones that have no value. Not looked at in a plugin's listing. |
name (optional) | string | The name it is registered under, such as ovh-incus. In the list of types, the type itself. |
node (optional) | string | The node it lives on, when a feature of that host offered it, by name. |
node_id (optional) | string | The id of that node. |
own (optional) | string[] | The names of the provisioner's own arguments, which say where it is, such as an Incus server. Their values are kept as its settings. |
problem (optional) | string | Why it cannot be used here, as a sentence that says what to change. Empty when it can. |
secrets (optional) | string[] | The rookery secrets it is given. |
settings (optional) | map of string | The values of its own arguments that are kept, by name. |
setup | string | seed: the machine boots with rookery's cloud seed and sets itself up. apply: rookery applies the profile over SSH once the machine answers. |
type (optional) | string | The plugin's provisioner it is, as PLUGIN/ID, such as incus/vm. |
verbs (optional) | string[] | What it can do besides create, status and destroy: start, stop, list, log. |
CollectionItem
One item of a collection, as the provisioner's status gives it.
| Field | Type | Description |
|---|---|---|
columns (optional) | map of string | The value of each column, by its name. |
key (optional) | map of string | The value of each part of the collection's key. |
name | string | |
unavailable (optional) | map of string | The item actions that cannot run on it, each with why not. |
Detail
A row of what a provisioner says, shown as it is given.
| Field | Type | Description |
|---|---|---|
label | string | |
value (optional) | string |
ListedResource
What a provisioner lists of what it holds, beside rookery's records.
| Field | Type | Description |
|---|---|---|
host (optional) | string | The host a machine was made for, when it says. |
id (optional) | string | The provisioner's id of it; empty for a record whose create did not end. |
kind | string | machine, or a kind the plugin names, such as deployment. |
name | string | |
resource (optional) | string | rookery's id of it, when rookery has a record of it. One the provisioner lists without one is not rookery's, or rookery lost track of it. |
state (optional) | string | What the provisioner's list says, or empty when it was not asked. |
Action
Something that can be done to a subject: a host, the installation, and later a provisioner or a resource. It says enough to build a form from.
| Field | Type | Description |
|---|---|---|
arguments (optional) | Argument[] | |
available (optional) | boolean | False, with why, when the subject's state rules it out now. |
changes (optional) | boolean | False when it only reads, and may be called at any time. |
collection (optional) | string | The id of the provisioner's collection it belongs to, whose items it makes, acts on or lists. The screens offer it there and not on the provisioner's page. |
confirm (optional) | string | null | The question to answer yes to before it runs. |
group (optional) | string | The group of the page it is listed in; Host when empty. |
help (optional) | string | |
label (optional) | string | |
name | string | |
role (optional) | Role | The least role that may run it. |
runs (optional) | Runs | Where an action runs. |
steps (optional) | ActionStep[] | What plugins add to it, in the order they run. |
terminal (optional) | boolean | It needs a terminal session attached; only a host runs these. |
why (optional) | string |
Argument
| Field | Type | Description |
|---|---|---|
choices (optional) | string | A command whose lines are the values to offer. |
confirm (optional) | string | For a yes or no: the question to answer yes to before the action runs with it on, instead of the action's own. |
default (optional) | string | |
fixed (optional) | string | Why it keeps its default here and cannot be given another value, such as destroying a machine no provisioner made. The screens show it greyed and say this instead of changing it. Empty when it can be changed. |
help (optional) | string | What it is for, in a sentence or two, beside its short label. |
kind (optional) | string | resource for an argument of a provisioner that sizes the machine: its CPUs, memory or disk. text for one whose value has several lines. boolean for a yes or no, which the screens show as a switch. Empty for any other argument. |
label (optional) | string | |
name | string | |
required (optional) | boolean | |
secret (optional) | boolean | What is given is a secret, such as a password: it is not shown as it is typed, nor kept, nor written to a job's output. |
values (optional) | string[] | The values a provisioner's argument takes, when it is a choice of a few. Empty for one that takes any text. |
Collection
A list of things a provisioner holds, such as the storage pools of a server. Its items come with the provisioner's status, and its actions are the provisioner's own: some make an item, some act on one item, whose key fills their arguments, and some act on the whole list.
| Field | Type | Description |
|---|---|---|
columns (optional) | CollectionColumn[] | The values each item shows besides its name, in order. |
group (optional) | string | The group of the provisioner's page it is listed in. |
help (optional) | string | |
id | string | |
item (optional) | CollectionAction[] | The actions on one item. |
key | string[] | The names that identify an item, such as pool and volume. A collection within another starts with that one's key. |
kinds (optional) | string[] | The kinds of resource that are its items, such as machine, in place of items the status gives: its item actions are offered on the page of each resource of those kinds the provisioner made. |
label (optional) | string | What one item is called, such as Storage pool. |
list (optional) | CollectionAction[] | The actions on the whole list, such as pruning. |
new (optional) | CollectionAction[] | The actions that make a new item. |
plural (optional) | string | What several are called, such as Storage pools. |
remove (optional) | string | The item action that removes one. |
show (optional) | string | The action that prints the list for the command line, which the screens show as the table instead. |
within (optional) | string | The collection whose items hold these, such as the pools that hold volumes. Each item of that one lists those that belong to it. |
ProvisionerKind
A kind of thing a provisioner makes.
| Field | Type | Description |
|---|---|---|
actions (optional) | Action[] | What its plugin can do to one, each run with the verb act and the resource's id. |
arguments (optional) | Argument[] | |
id | string | machine, or a kind the plugin names, such as deployment. |
label (optional) | string | |
setup (optional) | string | For a machine: seed or apply, as for the provisioner. |
spec (optional) | any | The specification one is made from, for a kind that has one: its format and label, as the plugin declares them. |
verbs (optional) | string[] | What can be done to one besides create, status and destroy: start, stop, change, logs. |
Act
What running an action is given.
| Field | Type | Description |
|---|---|---|
arguments (optional) | map of string | |
cols (optional) | integer | null | |
input_b64 (optional) | string | null | Bytes for the standard input of an action that takes them, in base64: the build context of a rookery for upgrade-server source=here. They go over HTTP when they are more than the portal carries. |
rows (optional) | integer | null | The size of the terminal, for an action that runs in one. |
sudo_password (optional) | string | null | The SSH user's sudo password, for an action that logs in to a host whose sudo asks for one. It is neither shown nor kept. |
token (optional) | string | null | Any text of the caller's. The same token again for the same subject and action answers with the job the first call started. |
JobInfo
A job of rookery: one run of an action, with its output kept where it ran.
| Field | Type | Description |
|---|---|---|
action (optional) | string | The action it runs, such as apply, rollout or provision. |
arguments (optional) | string[] | What it was started with, as people may see it: the command of a resource's exec, or an action's arguments as NAME=VALUE. Never a secret argument, a password or standard input. |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
host (optional) | string | The hosts it is about, for a reader: a name, or several with commas. |
host_id (optional) | string | The ids of those hosts, as host lists them; a host in a file by its path. |
id | string | |
report (optional) | RolloutReport | null | |
started | string | |
stopped_by (optional) | string | null | Who stopped it before it ended by itself. |
subject (optional) | string | What it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one. |
subject_name (optional) | string | What it was done to, by name as it is called now: host:NAME, provisioner:NAME, resource:ID or installation; by id for one that is gone. |
Session
| Field | Type | Description |
|---|---|---|
action (optional) | string | null | The action it was started for, if any. |
cols (optional) | integer | null | |
command | string[] | |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
id | string | |
kind | SessionKind | |
last_output (optional) | string | null | |
lost (optional) | boolean | It ended with rookeryd or the host, not by itself. |
output_size (optional) | integer | |
rows (optional) | integer | null | |
started | string | |
started_by | From | Who did something, as rookeryd saw it. |
steps (optional) | Step[] | |
title | string | |
user | string | |
viewers (optional) | integer |
Role
What a caller has to be allowed for an operation. Each role includes the ones before it.
What a caller has to be allowed for an operation. Each role includes the ones before it.
Runs
Where an action runs.
Where an action runs.
ActionStep
What a plugin adds to an action: a step run after it in the same run.
| Field | Type | Description |
|---|---|---|
help (optional) | string | |
label | string |
CollectionColumn
A value an item of a collection shows.
| Field | Type | Description |
|---|---|---|
label (optional) | string | |
name | string |
CollectionAction
An action of a provisioner as one of a collection's.
| Field | Type | Description |
|---|---|---|
action | string | The provisioner's action, by its name. |
arguments (optional) | map of string | The argument of the action each part of the key fills, where its name is not the part's own: {"volume": "name"}. |
label (optional) | string | What it is called where its item is known already, such as Grow. The action's own label when empty. |
RolloutReport
The result of a roll-out, host by host in the order they were taken.
| Field | Type | Description |
|---|---|---|
hosts | RolloutHost[] | |
ok | boolean | Every host is done or current. |
SessionKind
From
Who did something, as rookeryd saw it.
| Field | Type | Description |
|---|---|---|
level | Level | |
session (optional) | string | null | |
uid | integer |
Step
| Field | Type | Description |
|---|---|---|
exit_code (optional) | integer | null | |
name | string | |
user | string |
RolloutHost
| Field | Type | Description |
|---|---|---|
changes (optional) | Change[] | What had changed, as it was before applying. |
error (optional) | string | What went wrong, for a failed host. |
name | string | |
rebooted (optional) | boolean | It was rebooted. |
state | RolloutState | How one host of a roll-out went. |
warnings (optional) | string[] | What did not go well without being a failure, such as an update step that ended badly. One stops the roll-out after this host. |
Level
Change
Something that changed since a host was applied: rookery itself or a plugin.
| Field | Type | Description |
|---|---|---|
from | string | The version the host was applied with. |
id | string | rookery, or a plugin's id. |
to | string | The version there is now; empty for a plugin that is gone, the same as from for one whose files changed. |
RolloutState
How one host of a roll-out went.
How one host of a roll-out went.