host-v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Host",
  "description": "The core host definition",
  "type": "object",
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "kind": {
      "type": "string"
    },
    "metadata": {
      "$ref": "#/$defs/ObjectMeta",
      "default": {}
    },
    "spec": {
      "description": "The spec",
      "$ref": "#/$defs/HostSpec",
      "default": {
        "bootOrder": "default",
        "image": null
      }
    },
    "status": {
      "description": "The status",
      "$ref": "#/$defs/HostStatus",
      "default": {
        "booted": null,
        "rollback": null,
        "rollbackQueued": false,
        "staged": null,
        "type": null,
        "usrOverlay": null
      }
    }
  },
  "required": [
    "apiVersion",
    "kind"
  ],
  "$defs": {
    "BootEntry": {
      "description": "A bootable entry",
      "type": "object",
      "properties": {
        "cachedUpdate": {
          "description": "The last fetched cached update metadata",
          "anyOf": [
            {
              "$ref": "#/$defs/ImageStatus"
            },
            {
              "type": "null"
            }
          ]
        },
        "composefs": {
          "description": "If this boot entry is composefs based, the corresponding state",
          "anyOf": [
            {
              "$ref": "#/$defs/BootEntryComposefs"
            },
            {
              "type": "null"
            }
          ]
        },
        "downloadOnly": {
          "description": "Whether this deployment is in download-only mode (prevented from automatic finalization on shutdown).\nThis is set via --download-only on the CLI.",
          "type": "boolean",
          "default": false
        },
        "image": {
          "description": "The image reference",
          "anyOf": [
            {
              "$ref": "#/$defs/ImageStatus"
            },
            {
              "type": "null"
            }
          ]
        },
        "incompatible": {
          "description": "Whether this boot entry is not compatible (has origin changes bootc does not understand)",
          "type": "boolean"
        },
        "ostree": {
          "description": "If this boot entry is ostree based, the corresponding state",
          "anyOf": [
            {
              "$ref": "#/$defs/BootEntryOstree"
            },
            {
              "type": "null"
            }
          ]
        },
        "pinned": {
          "description": "Whether this entry will be subject to garbage collection",
          "type": "boolean"
        },
        "softRebootCapable": {
          "description": "This is true if (relative to the booted system) this is a possible target for a soft reboot",
          "type": "boolean",
          "default": false
        },
        "store": {
          "description": "The container storage backend",
          "anyOf": [
            {
              "$ref": "#/$defs/Store"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "incompatible",
        "pinned"
      ]
    },
    "BootEntryComposefs": {
      "description": "A bootable entry",
      "type": "object",
      "properties": {
        "bootDigest": {
          "description": "The sha256sum of vmlinuz + initrd\nOnly `Some` for Type1 boot entries",
          "type": [
            "string",
            "null"
          ]
        },
        "bootType": {
          "description": "Whether this deployment is to be booted via Type1 (vmlinuz + initrd) or Type2 (UKI) entry",
          "$ref": "#/$defs/BootType"
        },
        "bootloader": {
          "description": "Whether we boot using systemd or grub",
          "$ref": "#/$defs/Bootloader"
        },
        "verity": {
          "description": "The erofs verity",
          "type": "string"
        }
      },
      "required": [
        "verity",
        "bootType",
        "bootloader"
      ]
    },
    "BootEntryOstree": {
      "description": "A bootable entry",
      "type": "object",
      "properties": {
        "checksum": {
          "description": "The ostree commit checksum",
          "type": "string"
        },
        "deploySerial": {
          "description": "The deployment serial",
          "type": "integer",
          "format": "uint32",
          "minimum": 0
        },
        "stateroot": {
          "description": "The name of the storage for /etc and /var content",
          "type": "string"
        }
      },
      "required": [
        "stateroot",
        "checksum",
        "deploySerial"
      ]
    },
    "BootOrder": {
      "description": "Configuration for system boot ordering.",
      "oneOf": [
        {
          "description": "The staged or booted deployment will be booted next",
          "type": "string",
          "const": "default"
        },
        {
          "description": "The rollback deployment will be booted next",
          "type": "string",
          "const": "rollback"
        }
      ]
    },
    "BootType": {
      "type": "string",
      "enum": [
        "Bls",
        "Uki"
      ]
    },
    "Bootloader": {
      "description": "Bootloader type to determine whether system was booted via Grub or Systemd",
      "oneOf": [
        {
          "description": "Use Grub as the bootloader",
          "type": "string",
          "const": "grub"
        },
        {
          "description": "Use SystemdBoot as the bootloader",
          "type": "string",
          "const": "systemd"
        },
        {
          "description": "Don't use a bootloader managed by bootc",
          "type": "string",
          "const": "none"
        }
      ]
    },
    "FilesystemOverlay": {
      "description": "Details of an overlay filesystem: read-only or read/write, persistent or transient.",
      "type": "object",
      "properties": {
        "accessMode": {
          "description": "Whether the overlay is read-only or read/write",
          "$ref": "#/$defs/FilesystemOverlayAccessMode"
        },
        "persistence": {
          "description": "Whether the overlay will persist across reboots",
          "$ref": "#/$defs/FilesystemOverlayPersistence"
        }
      },
      "required": [
        "accessMode",
        "persistence"
      ]
    },
    "FilesystemOverlayAccessMode": {
      "description": "The permissions mode of a /usr overlay",
      "oneOf": [
        {
          "description": "The overlay is mounted read-only",
          "type": "string",
          "const": "readOnly"
        },
        {
          "description": "The overlay is mounted read/write",
          "type": "string",
          "const": "readWrite"
        }
      ]
    },
    "FilesystemOverlayPersistence": {
      "description": "The persistence mode of a /usr overlay",
      "oneOf": [
        {
          "description": "Changes are temporary and will be lost on reboot",
          "type": "string",
          "const": "transient"
        },
        {
          "description": "Changes persist across reboots",
          "type": "string",
          "const": "persistent"
        }
      ]
    },
    "HostSpec": {
      "description": "The host specification",
      "type": "object",
      "properties": {
        "bootOrder": {
          "description": "If set, and there is a rollback deployment, it will be set for the next boot.",
          "$ref": "#/$defs/BootOrder",
          "default": "default"
        },
        "image": {
          "description": "The host image",
          "anyOf": [
            {
              "$ref": "#/$defs/ImageReference"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "HostStatus": {
      "description": "The status of the host system",
      "type": "object",
      "properties": {
        "booted": {
          "description": "The booted image; this will be unset if the host is not bootc compatible.",
          "anyOf": [
            {
              "$ref": "#/$defs/BootEntry"
            },
            {
              "type": "null"
            }
          ]
        },
        "otherDeployments": {
          "description": "Other deployments (i.e. pinned)",
          "type": "array",
          "items": {
            "$ref": "#/$defs/BootEntry"
          }
        },
        "rollback": {
          "description": "The previously booted image",
          "anyOf": [
            {
              "$ref": "#/$defs/BootEntry"
            },
            {
              "type": "null"
            }
          ]
        },
        "rollbackQueued": {
          "description": "Set to true if the rollback entry is queued for the next boot.",
          "type": "boolean",
          "default": false
        },
        "staged": {
          "description": "The staged image for the next boot",
          "anyOf": [
            {
              "$ref": "#/$defs/BootEntry"
            },
            {
              "type": "null"
            }
          ]
        },
        "type": {
          "description": "The detected type of system",
          "anyOf": [
            {
              "$ref": "#/$defs/HostType"
            },
            {
              "type": "null"
            }
          ]
        },
        "usrOverlay": {
          "description": "The state of the overlay mounted on /usr",
          "anyOf": [
            {
              "$ref": "#/$defs/FilesystemOverlay"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "HostType": {
      "description": "The detected type of running system.  Note that this is not exhaustive\nand new variants may be added in the future.",
      "oneOf": [
        {
          "description": "The current system is deployed in a bootc compatible way.",
          "type": "string",
          "const": "bootcHost"
        }
      ]
    },
    "ImageReference": {
      "description": "A container image reference with attached transport and signature verification",
      "type": "object",
      "properties": {
        "image": {
          "description": "The container image reference",
          "type": "string"
        },
        "signature": {
          "description": "Signature verification type",
          "anyOf": [
            {
              "$ref": "#/$defs/ImageSignature"
            },
            {
              "type": "null"
            }
          ]
        },
        "transport": {
          "description": "The container image transport",
          "type": "string"
        }
      },
      "required": [
        "image",
        "transport"
      ]
    },
    "ImageSignature": {
      "description": "An image signature",
      "oneOf": [
        {
          "description": "Fetches will use the named ostree remote for signature verification of the ostree commit.",
          "type": "object",
          "properties": {
            "ostreeRemote": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "ostreeRemote"
          ]
        },
        {
          "description": "Fetches will defer to the `containers-policy.json`, but we make a best effort to reject `default: insecureAcceptAnything` policy.",
          "type": "string",
          "const": "containerPolicy"
        },
        {
          "description": "No signature verification will be performed",
          "type": "string",
          "const": "insecure"
        }
      ]
    },
    "ImageStatus": {
      "description": "The status of the booted image",
      "type": "object",
      "properties": {
        "architecture": {
          "description": "The hardware architecture of this image",
          "type": "string"
        },
        "image": {
          "description": "The currently booted image",
          "$ref": "#/$defs/ImageReference"
        },
        "imageDigest": {
          "description": "The digest of the fetched image (e.g. sha256:a0...);",
          "type": "string"
        },
        "timestamp": {
          "description": "The build timestamp, if any",
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "version": {
          "description": "The version string, if any",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "image",
        "imageDigest",
        "architecture"
      ]
    },
    "ObjectMeta": {
      "type": "object",
      "properties": {
        "annotations": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "type": "string"
          }
        },
        "labels": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "type": "string"
          }
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "namespace": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "Store": {
      "description": "The container storage backend",
      "oneOf": [
        {
          "description": "Use the ostree-container storage backend.",
          "type": "string",
          "const": "ostreeContainer"
        }
      ]
    }
  }
}