desired.json

The document a host watches at the path paths.desired_state_file names, and converges on with every change to it: which apps run here, on which volumes, reachable how. Deploy an app is the guide to it; this is the file field by field. A document the host cannot read is refused whole, and reported.json says so.

An editor completes and checks a document that names the schema:

{
  "$schema": "https://raw.githubusercontent.com/ilbertt/nibrunner/main/crates/protocol/schema/desired-state.schema.json",
  "hostId": "host-1"
}

Schema: desired-state.schema.json

HostDesiredState

What one host should be running. The daemon watches this document at the path its paths.desired_state_file names and converges on every change to it.

HostId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

DesiredVolume

DesiredInstance

DesiredCheckpoint

DesiredExport

VolumeId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

AppId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

DesiredPresence

One of "present", "absent".

InitialContents

What a volume holds before its app has written a byte: an archive in the store — a tar, gzipped or not, or a zip — unpacked under destinationPath in the app's root as the volume is formatted. That happens once, so this is read once: a volume already formatted is its app's, and a change here does nothing to it.

DeploymentId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

DesiredInstanceState

The whole of an instance's activation policy.

DesiredLayer

One read-only layer of the root filesystem an instance boots into. Layers stack in the order the document lists them, first at the bottom, and the app's volume is stacked writable over all of them. The kind says what the object is, and so what the host does with it.

One of the following, told apart by kind:

filesystem

A squashfs or ext4 image, attached as it was uploaded.

executable

One program, packed into an image at destinationPath and run the way this host has always run one: by the guest's own init, with the app's arguments and environment.

AppConfig

AppHostname

ActivationPolicy

IdleTimeoutMs

integer, 60000 to 86400000

CheckpointId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

ExportId

an identifier

string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$

ObjectKey

between 1 and 1024 characters

string, 1 to 1024 characters

TenantEnvironment

map of TenantValue, keys matching ^[A-Za-z_][A-Za-z0-9_]*$

Sha256Digest

a lowercase hex sha-256

string, matching ^[0-9a-f]{64}$

GuestPath

a guest path

string, at most 4096 characters, matching ^/$|^(/(?!\.\.?(/|$))[^/\\"'\x00-\x1f]+)+$

ExecutablePath

an absolute path to a file other than /sbin/init

string, at most 4096 characters, matching ^/$|^(/(?!\.\.?(/|$))[^/\\"'\x00-\x1f]+)+$

HttpPort

integer, 1 to 65535

Command

What the guest runs once its root is stacked, as uid 65534: program with args, in workingDirectory, with environment. The working directory is made if it is not there, given to that uid, and is where the program's persistent state lives, because everything under the root persists on the volume and nowhere else is the program's to write.

InstanceResources

HealthCheck

What tells this host an instance is well — and so what a wake waits for before it hands the caller on, and what the instance's liveness is read from after that. Named in every document: a default would be a kind nobody chose, and the one that looks obvious lies. A TCP connect is answered by the guest kernel's accept queue whether or not the process behind it will ever read the request, so a program that has stopped answering passes it for as long as it lives.

One of the following, told apart by kind:

http

path, requested on httpPort, answers 2xx.

tcp

A connection to httpPort is accepted. Only that — for a port that does not speak HTTP.

boot-completed

The microVM is up and httpPort has accepted a connection once: the tenant is listening. That is all it is asked, and only until it answers — a guest this host did not build answers no path it was not told about — so its liveness after that is the microVM being up.

RestartPolicy

InstancePort

A port a guest answers on beside its HTTP one, carried to it unread.

It carries whatever arrives, tcp or udp: a port is a port, the relay in front of a host forwards both for every one in its range, and a guest that listens on only one of them answers the other with a port-unreachable the way any host would.

Hostname

a hostname

string, at most 253 characters, matching ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$

AppHostnameKind

One of "platform", "custom".

SleepPolicy

What puts a running microVM back to sleep. Only an on-request instance may carry one that fires: nothing else on this host would wake it again, and the next reconcile pass would bring it straight back up.

One of the following, told apart by kind:

never

traffic-idle

max-lifetime

TenantValue

Handed to the app as is, except that ${NAME} and $NAME are filled in for NAME in NIBRUN_HOSTNAME, NIBRUN_HTTP_PORT; any other $NIBRUN_ reference is refused.

string, at most 32768 characters

TenantArguments

The arguments the binary is started with.

array of string, at most 4096 characters, at most 64 items

PortName

lowercase letters, digits and dashes, starting with a letter

string, matching ^[a-z][a-z0-9-]{0,15}$

GuestPort

integer, 1 to 65535

MaxLifetimeMs

integer, 60000 to 604800000