Skip to Content

Provisioners

What the plugins can create machines and deployments with, their pages and their actions.

OperationKindHTTP
provisioners.listcallGET /v1/provisioners
provisioners.typescallGET /v1/provisioner-types
provisioners.getcallGET /v1/provisioners/{name}
provisioners.savecallPUT /v1/provisioners/{name}
provisioners.removecallDELETE /v1/provisioners/{name}
provisioners.actionscallGET /v1/provisioners/{name}/actions
provisioners.actcallPOST /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

ProvisionerInfo[]

Request
{
  "id": 1,
  "op": "provisioners.list"
}
Reply
{
  "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

ProvisionerInfo[]

Request
{
  "id": 1,
  "op": "provisioners.types"
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe provisioner, by its name or its id (bare or as prov_ID)
argumentsquerynoValues of the provisioner's own arguments as NAME=VALUE for this once, such as another server to ask; the others are its settings

Result

FieldTypeDescription
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)stringWhat it said of itself, or why it could not be asked.
provisionerProvisionerInfoSomething 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.
statestringready, 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

StatusWhen
404No such provisioner
Request
{
  "id": 1,
  "op": "provisioners.get",
  "args": {
    "name": "status"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesIts 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

FieldTypeDescription
settings (optional)map of string | nullValues of its own arguments, such as the server it uses. Empty ones are not kept. Left out, the settings it has stay.
type (optional)stringThe plugin's provisioner it is, as PLUGIN/ID. A registered one keeps its type: this is the same or empty.

Result

FieldTypeDescription
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
idstringIts 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.
labelstring
missing_secrets (optional)string[]The required ones that have no value. Not looked at in a plugin's listing.
name (optional)stringThe name it is registered under, such as ovh-incus. In the list of types, the type itself.
node (optional)stringThe node it lives on, when a feature of that host offered it, by name.
node_id (optional)stringThe 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)stringWhy 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 stringThe values of its own arguments that are kept, by name.
setupstringseed: 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)stringThe 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

StatusWhen
400The name, the type or a setting does not fit; the message says which
Request
{
  "id": 1,
  "op": "provisioners.save",
  "args": {
    "name": "status"
  },
  "data": {
    "settings": {},
    "type": "text"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesIts name or its id (bare or as prov_ID)

Errors

StatusWhen
404No such provisioner
409It still holds resources; the message names them
Request
{
  "id": 1,
  "op": "provisioners.remove",
  "args": {
    "name": "status"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe provisioner, by its name or its id (bare or as prov_ID)

Result

Action[]

Errors

StatusWhen
404No such provisioner
Request
{
  "id": 1,
  "op": "provisioners.actions",
  "args": {
    "name": "status"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe provisioner, by its name or its id (bare or as prov_ID)
actionpathyesThe 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

FieldTypeDescription
job (optional)JobInfo | null
result (optional)anyWhat an action that answers at once and changes nothing said.
session (optional)Session | null

Errors

StatusWhen
400An argument is missing or unknown, or the body is not one
403The caller's role is below the action's
404No such provisioner or action
409Something else is being done to the provisioner
501It cannot run here now; the message says why
502The provisioner failed, as when its engine does not answer
Request
{
  "id": 1,
  "op": "provisioners.act",
  "args": {
    "name": "status",
    "action": "VALUE"
  },
  "data": {
    "arguments": {},
    "cols": 120,
    "input_b64": "aGVsbG8K",
    "rows": 40,
    "sudo_password": "text",
    "token": "text"
  }
}
Reply
{
  "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.

FieldTypeDescription
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
idstringIts 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.
labelstring
missing_secrets (optional)string[]The required ones that have no value. Not looked at in a plugin's listing.
name (optional)stringThe name it is registered under, such as ovh-incus. In the list of types, the type itself.
node (optional)stringThe node it lives on, when a feature of that host offered it, by name.
node_id (optional)stringThe 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)stringWhy 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 stringThe values of its own arguments that are kept, by name.
setupstringseed: 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)stringThe 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.

FieldTypeDescription
columns (optional)map of stringThe value of each column, by its name.
key (optional)map of stringThe value of each part of the collection's key.
namestring
unavailable (optional)map of stringThe item actions that cannot run on it, each with why not.

Detail

A row of what a provisioner says, shown as it is given.

FieldTypeDescription
labelstring
value (optional)string

ListedResource

What a provisioner lists of what it holds, beside rookery's records.

FieldTypeDescription
host (optional)stringThe host a machine was made for, when it says.
id (optional)stringThe provisioner's id of it; empty for a record whose create did not end.
kindstringmachine, or a kind the plugin names, such as deployment.
namestring
resource (optional)stringrookery'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)stringWhat 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.

FieldTypeDescription
arguments (optional)Argument[]
available (optional)booleanFalse, with why, when the subject's state rules it out now.
changes (optional)booleanFalse when it only reads, and may be called at any time.
collection (optional)stringThe 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 | nullThe question to answer yes to before it runs.
group (optional)stringThe group of the page it is listed in; Host when empty.
help (optional)string
label (optional)string
namestring
role (optional)RoleThe least role that may run it.
runs (optional)RunsWhere an action runs.
steps (optional)ActionStep[]What plugins add to it, in the order they run.
terminal (optional)booleanIt needs a terminal session attached; only a host runs these.
why (optional)string

Argument

FieldTypeDescription
choices (optional)stringA command whose lines are the values to offer.
confirm (optional)stringFor 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)stringWhy 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)stringWhat it is for, in a sentence or two, beside its short label.
kind (optional)stringresource 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
namestring
required (optional)boolean
secret (optional)booleanWhat 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.

FieldTypeDescription
columns (optional)CollectionColumn[]The values each item shows besides its name, in order.
group (optional)stringThe group of the provisioner's page it is listed in.
help (optional)string
idstring
item (optional)CollectionAction[]The actions on one item.
keystring[]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)stringWhat 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)stringWhat several are called, such as Storage pools.
remove (optional)stringThe item action that removes one.
show (optional)stringThe action that prints the list for the command line, which the screens show as the table instead.
within (optional)stringThe 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.

FieldTypeDescription
actions (optional)Action[]What its plugin can do to one, each run with the verb act and the resource's id.
arguments (optional)Argument[]
idstringmachine, or a kind the plugin names, such as deployment.
label (optional)string
setup (optional)stringFor a machine: seed or apply, as for the provisioner.
spec (optional)anyThe 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.

FieldTypeDescription
arguments (optional)map of string
cols (optional)integer | null
input_b64 (optional)string | nullBytes 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 | nullThe size of the terminal, for an action that runs in one.
sudo_password (optional)string | nullThe 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 | nullAny 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.

FieldTypeDescription
action (optional)stringThe 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)stringThe hosts it is about, for a reader: a name, or several with commas.
host_id (optional)stringThe ids of those hosts, as host lists them; a host in a file by its path.
idstring
report (optional)RolloutReport | null
startedstring
stopped_by (optional)string | nullWho stopped it before it ended by itself.
subject (optional)stringWhat it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one.
subject_name (optional)stringWhat 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

FieldTypeDescription
action (optional)string | nullThe action it was started for, if any.
cols (optional)integer | null
commandstring[]
ended (optional)string | null
exit_code (optional)integer | null
idstring
kindSessionKind
last_output (optional)string | null
lost (optional)booleanIt ended with rookeryd or the host, not by itself.
output_size (optional)integer
rows (optional)integer | null
startedstring
started_byFromWho did something, as rookeryd saw it.
steps (optional)Step[]
titlestring
userstring
viewers (optional)integer

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Runs

Where an action runs.

Runs

Where an action runs.

ActionStep

What a plugin adds to an action: a step run after it in the same run.

FieldTypeDescription
help (optional)string
labelstring

CollectionColumn

A value an item of a collection shows.

FieldTypeDescription
label (optional)string
namestring

CollectionAction

An action of a provisioner as one of a collection's.

FieldTypeDescription
actionstringThe provisioner's action, by its name.
arguments (optional)map of stringThe argument of the action each part of the key fills, where its name is not the part's own: {"volume": "name"}.
label (optional)stringWhat 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.

FieldTypeDescription
hostsRolloutHost[]
okbooleanEvery host is done or current.

SessionKind

SessionKind

From

Who did something, as rookeryd saw it.

FieldTypeDescription
levelLevel
session (optional)string | null
uidinteger

Step

FieldTypeDescription
exit_code (optional)integer | null
namestring
userstring

RolloutHost

FieldTypeDescription
changes (optional)Change[]What had changed, as it was before applying.
error (optional)stringWhat went wrong, for a failed host.
namestring
rebooted (optional)booleanIt was rebooted.
stateRolloutStateHow 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

Level

Change

Something that changed since a host was applied: rookery itself or a plugin.

FieldTypeDescription
fromstringThe version the host was applied with.
idstringrookery, or a plugin's id.
tostringThe 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.

RolloutState

How one host of a roll-out went.

On this page