Plugins
The plugins the server has, and updating them.
| Operation | Kind | HTTP |
|---|---|---|
plugins.list | call | GET /v1/plugins |
plugins.add | call | POST /v1/plugins |
plugins.upload | call | POST /v1/plugins/package |
plugins.remove | call | DELETE /v1/plugins/{id} |
plugins.check | call | GET /v1/plugins/updates |
plugins.update | call | POST /v1/plugins/update |
plugins.list
The plugins: those that come with rookery and the server's own.
Needs the role admin.
Result
| Field | Type | Description |
|---|---|---|
dir | string | The directory of its own plugins; a folder copied there is one too. |
plugins | PluginInfo[] |
{
"id": 1,
"op": "plugins.list"
}{
"id": 1,
"result": {
"dir": "text",
"plugins": [
{
"dir": "text",
"id": "k3v9qz2m8w1x",
"label": "text",
"origin": "shipped",
"package": "text",
"version": "0.6.0"
}
]
}
}plugins.add
Install a plugin with npm from a registry or an address.
Needs the role admin.
Input
What to install
| Field | Type | Description |
|---|---|---|
spec | string | A package of the server's npm registry, [@SCOPE/]NAME[@VERSION], or the https address of a .tgz. |
Result
| Field | Type | Description |
|---|---|---|
behind (optional) | HostBehind[] | After an update: the hosts whose configuration is now behind. |
lines | string[] |
Errors
| Status | When |
|---|---|
| 400 | Not a package or address, or npm failed; the message has its output |
{
"id": 1,
"op": "plugins.add",
"data": {
"spec": "text"
}
}{
"id": 1,
"result": {
"behind": [
{
"changes": [
{}
],
"name": "status"
}
],
"lines": [
"text"
]
}
}plugins.upload
Install a plugin from a .tgz, as npm pack makes one, which the server keeps.
Needs the role admin.
Input
Bytes: {"base64": …} on the portal, the request body over HTTP.
Result
| Field | Type | Description |
|---|---|---|
behind (optional) | HostBehind[] | After an update: the hosts whose configuration is now behind. |
lines | string[] |
Errors
| Status | When |
|---|---|
| 400 | Not a .tgz, or npm failed; the message has its output |
{
"id": 1,
"op": "plugins.upload",
"data": {
"base64": "aGVsbG8K"
}
}{
"id": 1,
"result": {
"behind": [
{
"changes": [
{}
],
"name": "status"
}
],
"lines": [
"text"
]
}
}plugins.remove
Remove one of the server's own plugins.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | The plugin's id |
Result
| Field | Type | Description |
|---|---|---|
behind (optional) | HostBehind[] | After an update: the hosts whose configuration is now behind. |
lines | string[] |
Errors
| Status | When |
|---|---|
| 404 | No such plugin |
| 409 | It comes with rookery and stays |
{
"id": 1,
"op": "plugins.remove",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"behind": [
{
"changes": [
{}
],
"name": "status"
}
],
"lines": [
"text"
]
}
}plugins.check
Ask the registries the server's own plugins came from whether they have newer versions.
Needs the role admin.
Result
| Field | Type | Description |
|---|---|---|
plugins | PluginUpdate[] |
Errors
| Status | When |
|---|---|
| 400 | npm could not be run |
{
"id": 1,
"op": "plugins.check"
}{
"id": 1,
"result": {
"plugins": [
{
"id": "k3v9qz2m8w1x",
"latest": "text",
"note": "text",
"package": "text",
"version": "0.6.0"
}
]
}
}plugins.update
Update one of the server's own plugins, or all, to the latest version of their registry, and say which hosts are behind then.
Needs the role admin.
Input
The plugin, by id or npm name; all without one
PluginUpdateSpec | null
Result
| Field | Type | Description |
|---|---|---|
behind (optional) | HostBehind[] | After an update: the hosts whose configuration is now behind. |
lines | string[] |
Errors
| Status | When |
|---|---|
| 400 | It has no registry to ask, comes with rookery, or npm failed; the message says which |
| 404 | No such plugin |
{
"id": 1,
"op": "plugins.update",
"data": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"behind": [
{
"changes": [
{}
],
"name": "status"
}
],
"lines": [
"text"
]
}
}Types
The named types used on this page.
PluginInfo
A plugin that was found, with what it can install.
| Field | Type | Description |
|---|---|---|
description (optional) | string | |
dir | string | Where it is on the machine that has it. |
features (optional) | PluginFeature[] | |
id | string | |
label | string | |
origin | PluginOrigin | Where a plugin comes from, which says whether it can be removed. |
package | string | Its npm name. |
provisioners (optional) | ProvisionerInfo[] | What it can create machines with. |
version | string |
HostBehind
A host whose configuration is behind, and how.
A host whose configuration is behind, and how.
PluginUpdate
Whether a newer version of a plugin is there, as its registry says.
| Field | Type | Description |
|---|---|---|
id | string | |
latest (optional) | string | null | The registry's latest version, when it is another one. |
note (optional) | string | Why there is nothing to ask, or what asking said: a plugin from a .tgz or a folder has no registry to ask. |
package | string | |
version | string | The version installed. |
PluginUpdateSpec
What to update: one plugin by its id or npm name, or all of them.
| Field | Type | Description |
|---|---|---|
id (optional) | string | null |
PluginFeature
Something a plugin installs, switched on per host.
| Field | Type | Description |
|---|---|---|
actions (optional) | PluginAction[] | |
channels (optional) | string[] | Channel topics, without the plugin's id. |
group | string | The group of the Features page it is listed in. |
help (optional) | string | |
id | string | A profile names it PLUGIN/ID. |
label | string | |
services (optional) | PluginService[] |
PluginOrigin
Where a plugin comes from, which says whether it can be removed.
Where a plugin comes from, which says whether it can be removed.
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. |
PluginAction
An action a feature adds to a host.
| Field | Type | Description |
|---|---|---|
agent (optional) | boolean | The agent may run it with box run. |
arguments (optional) | string[] | The names of the arguments it asks for. |
extends (optional) | string[] | Actions of rookery it runs after, with no row of its own. |
label | string | |
name | string | The action is PLUGIN:NAME on the host. |
user | string | agent, operator or root. |
PluginService
A program a feature keeps running on the host to answer calls.
| Field | Type | Description |
|---|---|---|
methods (optional) | string[] | |
name | string | The service is PLUGIN/NAME on the host. |
user | string |
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. |
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. |