From 0d4436b34ee0b5332544548cb789e34ccb769444 Mon Sep 17 00:00:00 2001 From: Antheas Kapenekakis Date: Wed, 11 Dec 2024 21:16:54 +0100 Subject: [PATCH] docs: Describe `--json-fd` Signed-off-by: Antheas Kapenekakis Signed-off-by: Colin Walters --- docs/src/bootc-via-api.md | 74 ++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 17 deletions(-) diff --git a/docs/src/bootc-via-api.md b/docs/src/bootc-via-api.md index fdfdf7939..94438b135 100644 --- a/docs/src/bootc-via-api.md +++ b/docs/src/bootc-via-api.md @@ -4,27 +4,67 @@ At the current time, bootc is primarily intended to be driven via a fork/exec model. The core CLI verbs are stable and will not change. -## Using `bootc edit` and `bootc status --json` +The core API is meant to be used as a "state machine": run a command, +such as `bootc upgrade --check` or `bootc switch`, and then query the +updated state with `bootc status --json`. The status command contains all +relevant state about the current deployment, including cached results +from `bootc upgrade --check`. + +## `bootc status` JSON Schema + +`bootc status --json --format-version=1` outputs a machine-readable JSON +that contains all relevant information about the current +deployment. This API is considered stable. You can find a +[JSON schema](https://json-schema.org/) describing the +version `org.containers.bootc/v1` here: +[host-v1.schema.json](host-v1.schema.json). This schema was generated +directly from the Rust bootc code. +You can either reference or feed it to a code generator such as +[go-jsonschema](https://github.com/omissis/go-jsonschema) to generate +client bindings. + +In order to be forwards compatible with a future introduction of +a v2 or newer format, please include an explicit version in your +status request with `--format-version=1` as referenced above. +(Available since bootc 0.1.15, `--format-version=0` in bootc 0.1.14). + +## Interactive progress with `--json-fd` + +While the `bootc status` tooling allows a client to discover the state +of the system, during interactive changes such as `bootc upgrade` +or `bootc switch` it is possible to monitor the status of downloads +or other operations at a fine-grained level with `--json-fd`. + +The format of data output over `--json-fd` is [JSON Lines](https://jsonlines.org) +which is a series of JSON objects separated by newlines (the intermediate +JSON content is guaranteed not to contain a literal newline). + +The current API version is `org.containers.bootc/progress/v1`. You can find +the JSON schema describing this version here: +[progress-v1.schema.json](progress-v1.schema.json). + +Deploying a new image with either switch or upgrade consists +of three stages: `pulling`, `importing`, and `staging`. The `pulling` step +downloads the image from the registry, offering per-layer and progress in +each message. The `importing` step imports the image into storage and consists +of a single step. Finally, `staging` runs a variety of staging +tasks. Currently, they are staging the image to disk, pulling bound images, +and removing old images. + +Note that new stages or fields may be added at any time. + +Importing and staging are affected by disk speed and the total image size. Pulling +is affected by network speed and how many layers invalidate between pulls. +Therefore, a large image with a good caching strategy will have longer +importing and staging times, and a small bespoke container image will have +negligible importing and staging times. + +## Using `bootc edit` While bootc does not depend on Kubernetes, it does currently -also offere a Kubernetes *style* API, especially oriented +also offer a Kubernetes *style* API, especially oriented towards the [spec and status and other conventions](https://kubernetes.io/docs/reference/using-api/api-concepts/). In general, most use cases of driving bootc via API are probably most easily done by forking off `bootc upgrade` when desired, and viewing `bootc status --json --format-version=1`. - -## JSON Schema - -The current API `org.containers.bootc/v1` is stable. -In order to support the future introduction of a v2 -or newer format, please change your code now to explicitly -request `--format-version=1` as referenced above. (Available -since bootc 0.1.15, `--format-version=0` in bootc 0.1.14). - -There is a [JSON schema](https://json-schema.org/) generated from -the Rust source code available here: [host-v1.schema.json](host-v1.schema.json). - -A common way to use this is to run a code generator such as -[go-jsonschema](https://github.com/omissis/go-jsonschema) on the -input schema.