reported.json
Every field of the file a host writes back, from its JSON Schema.
The file the host writes to reported.json in paths.state_dir after every reconcile pass. The
metrics page is built from the same data. A control plane that reads only this file learns the
result of its last write to desired.json, and the reason for any failure.
Schema: reported.schema.json
HostReportedState
What one host is running, as the daemon last wrote it to reported.json in its paths.state_dir.
| Name | Type | Description |
|---|---|---|
hostId | HostId | |
reportedAt | Timestamp | |
state | HostState | |
capacity | HostCapacity | What the machine has. |
allocatable | HostCapacity | What is left once every booted app is taken off. |
versions | HostVersions | |
cron | array of CronListing | null | |
volumes | array of ReportedVolume | |
instances | array of ReportedInstance | |
checkpoints | array of ReportedCheckpoint | |
exports | array of ReportedExport | |
acceptedDigest optional | Sha256Digest | null | The document this host is converging on, as sha256sum reads the file it came from. Absent until one has been taken up. A control plane checks it against the write it made to learn that this host is on that document rather than on the one before it — which is what instances alone cannot say about a document that changed nothing about an app. |
acceptedRevision optional | Revision | null | The revision that document named, if it named one — the control plane's own word for what this host is converging on, beside the digest that is this host's. |
message optional | StateMessage | null | Set when the last document this host was handed was refused — malformed, or not the document this host reads — and cleared when a readable one is taken up. A control plane that only reads this file learns from it that its last write did not land, and why. |
HostId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
Timestamp
an ISO 8601 instant with an offset
string, matching ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$
HostState
One of "registering", "ready", "draining", "unreachable".
HostCapacity
| Name | Type | Description |
|---|---|---|
vcpuCount | integer, at least 0 | |
memoryMib | integer, at least 0 | |
cacheBytes | integer, at least 0 |
HostVersions
| Name | Type | Description |
|---|---|---|
agent | string | |
guestImage | string | |
zerofs | string | |
firecracker | string |
CronListing
| Name | Type | Description |
|---|---|---|
appId | AppId | |
deploymentId | DeploymentId | |
enabled | boolean | |
timeZone | string | |
jobs | array of RegisteredCronJob |
ReportedVolume
| Name | Type | Description |
|---|---|---|
volumeId | VolumeId | |
appId | AppId | |
state | VolumeState | |
sizeBytes | integer, at least 0 | |
usage | FilesystemUsage | null | |
devicePath optional | string | null | |
message optional | StateMessage | null | |
storagePrefix optional | ObjectKey | null |
ReportedInstance
| Name | Type | Description |
|---|---|---|
appId | AppId | |
deploymentId | DeploymentId | |
state | InstanceState | |
compute | ComputeUsage | null | |
restartCount | integer, at least 0 | Times the supervisor inside the guest has restarted the tenant since this host last booted the app afresh. A restore from a snapshot keeps the count; a cold boot starts it over. |
convergedAt optional | Timestamp | null | When the instance first became what the document asks of it, for the deploymentId and desiredState it now carries. Absent while it is still on its way there, and for a deployment this host was not there to see arrive. |
guestIpv4 optional | Ipv4Address | null | |
hostPort optional | HostPort | null | |
lastExitCode optional | integer | null | |
lastRestart optional | ReportedRestart | null | The last of those restarts. Absent until there has been one. |
layerDigests optional | array of Sha256Digest | The layers the running microVM was booted from, bottom first. Empty until one has been. |
message optional | StateMessage | null | |
startedAt optional | Timestamp | null |
ReportedCheckpoint
| Name | Type | Description |
|---|---|---|
checkpointId | CheckpointId | |
volumeId | VolumeId | |
state | CheckpointState | |
message optional | StateMessage | null | |
readyAt optional | Timestamp | null | |
reference optional | StateMessage | null |
ReportedExport
| Name | Type | Description |
|---|---|---|
exportId | ExportId | |
state | ExportState | |
checkpointId optional | CheckpointId | null | |
message optional | StateMessage | null | |
readyAt optional | Timestamp | null | |
sizeBytes optional | integer, at least 0 | null |
Sha256Digest
a lowercase hex sha-256
string, matching ^[0-9a-f]{64}$
Revision
between 1 and 128 printable characters, without spaces
string, matching ^[\x21-\x7e]{1,128}$
StateMessage
string, at most 512 characters
AppId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
DeploymentId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
RegisteredCronJob
| Name | Type | Description |
|---|---|---|
jobId | string | |
schedule | CronSchedule | |
command | CronCommand | |
nextRunAt | Timestamp | null | |
environment optional | TenantEnvironment | null |
VolumeId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
VolumeState
One of "pending", "ready", "detached", "deleted", "failed".
FilesystemUsage
| Name | Type | Description |
|---|---|---|
totalBytes | integer, at least 0 | |
usedBytes | integer, at least 0 | |
measuredAt | Timestamp |
ObjectKey
between 1 and 1024 characters
string, 1 to 1024 characters
InstanceState
One of "pending", "starting", "running", "unhealthy", "stopping", "stopped", "idle", "failed".
ComputeUsage
| Name | Type | Description |
|---|---|---|
memoryTotalBytes | integer, at least 0 | |
memoryUsedBytes | integer, at least 0 | |
measuredAt | Timestamp | |
| optional | number | null |
Ipv4Address
an IPv4 address
string, matching ^((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9][0-9]|[0-9])$
HostPort
integer, 1 to 65535
ReportedRestart
A tenant restart as the host heard of it: what the guest said, and when it said it.
| Name | Type | Description |
|---|---|---|
at | Timestamp | |
attempt | integer, at least 0 | 1 for the first restart since the tenant last stayed up long enough to earn its budget back, up to budget. |
budget | integer, at least 0 | |
exit | TenantExit | |
reason | StateMessage | |
backoffMs | integer, at least 0 |
CheckpointId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
CheckpointState
One of "pending", "ready", "deleted", "failed".
ExportId
an identifier
string, matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$
ExportState
One of "pending", "preparing", "ready", "failed", "expired".
CronSchedule
string
CronCommand
string, at most 32768 characters
TenantEnvironment
map of TenantValue, keys matching ^[A-Za-z_][A-Za-z0-9_]*$
TenantExit
How a tenant process ended: the code it exited with, or the signal that killed it.
One of the following:
code
| Name | Type | Description |
|---|---|---|
code | integer |
signal
| Name | Type | Description |
|---|---|---|
signal | integer |
TenantValue
Only complete ${NAME} references are filled in for NAME in NIBRUN_HOSTNAME, NIBRUN_HTTP_PORT. Bare names, incomplete references and other dollar signs remain literal; complete references to unknown NIBRUN_ names are refused.
string, at most 32768 characters