Merge pull request #819 from cgwalters/status-non-bootc

status: Output targeted message in non-bootc case, update docs

Author: cgwalters

docs/src/man/bootc-container-lint.md

@@ -23,4 +23,4 @@ part of a build process; it will error if any problems are detected.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-container.md

@@ -30,4 +30,4 @@ bootc-container-help(8)
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-edit.md

@@ -36,4 +36,4 @@ Only changes to the \`spec\` section are honored.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-install-print-configuration.md

@@ -27,4 +27,4 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-install-to-disk.md

@@ -10,7 +10,8 @@ bootc-install-to-disk - Install to the target block device
 \[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\]
 \[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\]
 \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\]
-\[**\--via-loopback**\] \[**-h**\|**\--help**\] \<*DEVICE*\>
+\[**\--stateroot**\] \[**\--via-loopback**\] \[**-h**\|**\--help**\]
+\<*DEVICE*\>
 
 # DESCRIPTION
 
@@ -129,6 +130,10 @@ boot.
 \- All bootloader types will be installed - Changes to the system
 firmware will be skipped
 
+**\--stateroot**=*STATEROOT*
+
+:   The stateroot name to use. Defaults to \`default\`
+
 **\--via-loopback**
 
 :   Instead of targeting a block device, write to a file via loopback
@@ -144,4 +149,4 @@ firmware will be skipped
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-install-to-existing-root.md

@@ -10,8 +10,8 @@ bootc-install-to-existing-root - Install to the host root filesystem
 \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\]
 \[**\--disable-selinux**\] \[**\--karg**\]
 \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\]
-\[**\--acknowledge-destructive**\] \[**-h**\|**\--help**\]
-\[*ROOT_PATH*\]
+\[**\--stateroot**\] \[**\--acknowledge-destructive**\]
+\[**-h**\|**\--help**\] \[*ROOT_PATH*\]
 
 # DESCRIPTION
 
@@ -115,6 +115,10 @@ boot.
 \- All bootloader types will be installed - Changes to the system
 firmware will be skipped
 
+**\--stateroot**=*STATEROOT*
+
+:   The stateroot name to use. Defaults to \`default\`
+
 **\--acknowledge-destructive**
 
 :   Accept that this is a destructive action and skip a warning timer
@@ -130,4 +134,4 @@ firmware will be skipped
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-install-to-filesystem.md

@@ -13,7 +13,7 @@ filesystem structure
 \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\]
 \[**\--disable-selinux**\] \[**\--karg**\]
 \[**\--root-ssh-authorized-keys**\] \[**\--generic-image**\]
-\[**-h**\|**\--help**\] \<*ROOT_PATH*\>
+\[**\--stateroot**\] \[**-h**\|**\--help**\] \<*ROOT_PATH*\>
 
 # DESCRIPTION
 
@@ -144,6 +144,10 @@ boot.
 \- All bootloader types will be installed - Changes to the system
 firmware will be skipped
 
+**\--stateroot**=*STATEROOT*
+
+:   The stateroot name to use. Defaults to \`default\`
+
 **-h**, **\--help**
 
 :   Print help (see a summary with -h)
@@ -157,4 +161,4 @@ mounting. To override this, use \`\--root-mount-spec\`.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-install.md

@@ -10,7 +10,7 @@ bootc-install - Install the running container to a target
 
 Install the running container to a target.
 
-\## Understanding installations
+## Understanding installations
 
 OCI containers are effectively layers of tarballs with JSON for
 metadata; they cannot be booted directly. The \`bootc install\` flow is
@@ -61,4 +61,4 @@ bootc-install-help(8)
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-rollback.md

@@ -34,4 +34,4 @@ rollback invocation.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-status.md

@@ -11,11 +11,21 @@ bootc-status - Display status
 
 Display status
 
-This will output a YAML-formatted object using a schema intended to
-match a Kubernetes resource that describes the state of the booted
-system.
+If standard output is a terminal, this will output a description of the
+bootc system state. If standard output is not a terminal, output a
+YAML-formatted object using a schema intended to match a Kubernetes
+resource that describes the state of the booted system.
 
-The exact API format is not currently declared stable.
+## Parsing output via programs
+
+Either the default YAML format or \`\--format=json\` can be used. Do not
+attempt to explicitly parse the output of \`\--format=humanreadable\` as
+it will very likely change over time.
+
+## Programmatically detecting whether the system is deployed via bootc
+
+Invoke e.g. \`bootc status \--json\`, and check if \`status.booted\` is
+not \`null\`.
 
 # OPTIONS
 
@@ -26,16 +36,18 @@ The exact API format is not currently declared stable.
 \
 *Possible values:*
 
+> -   humanreadable: Output in Human Readable format
+>
 > -   yaml: Output in YAML format
 >
 > -   json: Output in JSON format
 
 **\--format-version**=*FORMAT_VERSION*
 
 :   The desired format version. There is currently one supported
-    version, which is version \`0\`. Pass this option to explicitly
-    request it; it is possible that multiple versions will be supported
-    in the future
+    version, which is exposed as both \`0\` and \`1\`. Pass this option
+    to explicitly request it; it is possible that another future version
+    2 or newer will be supported in the future
 
 **\--booted**
 
@@ -47,4 +59,4 @@ The exact API format is not currently declared stable.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-switch.md

@@ -4,7 +4,7 @@ bootc-switch - Target a new container image reference to boot
 
 # SYNOPSIS
 
-**bootc switch** \[**\--quiet**\] \[**\--transport**\]
+**bootc switch** \[**\--quiet**\] \[**\--apply**\] \[**\--transport**\]
 \[**\--enforce-container-sigpolicy**\] \[**\--ostree-remote**\]
 \[**\--retain**\] \[**-h**\|**\--help**\] \<*TARGET*\>
 
@@ -15,7 +15,7 @@ Target a new container image reference to boot.
 This is almost exactly the same operation as \`upgrade\`, but
 additionally changes the container image reference instead.
 
-\## Usage
+## Usage
 
 A common pattern is to have a management agent control operating system
 updates via container image tags; for example,
@@ -30,6 +30,14 @@ updates via container image tags; for example,
 
 :   Dont display progress
 
+**\--apply**
+
+:   Restart or reboot into the new target image.
+
+Currently, this option always reboots. In the future this command will
+detect the case where no kernel changes are queued, and perform a
+userspace-only restart.
+
 **\--transport**=*TRANSPORT* \[default: registry\]
 
 :   The transport; e.g. oci, oci-archive, containers-storage. Defaults
@@ -61,4 +69,4 @@ includes a default policy which requires signatures.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-upgrade.md

@@ -52,4 +52,4 @@ userspace-only restart.
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc-usr-overlay.md

@@ -12,20 +12,20 @@ will be discarded on reboot
 Adds a transient writable overlayfs on \`/usr\` that will be discarded
 on reboot.
 
-\## Use cases
+## Use cases
 
 A common pattern is wanting to use tracing/debugging tools, such as
 \`strace\` that may not be in the base image. A system package manager
 such as \`apt\` or \`dnf\` can apply changes into this transient overlay
 that will be discarded on reboot.
 
-\## /etc and /var
+## /etc and /var
 
 However, this command has no effect on \`/etc\` and \`/var\` - changes
 written there will persist. It is common for package installations to
 modify these directories.
 
-\## Unmounting
+## Unmounting
 
 Almost always, a system process will hold a reference to the open mount
 point. You can however invoke \`umount -l /usr\` to perform a \"lazy
@@ -39,4 +39,4 @@ unmount\".
 
 # VERSION
 
-v0.1.13
+v0.1.16

docs/src/man/bootc.md

@@ -72,4 +72,4 @@ bootc-help(8)
 
 # VERSION
 
-v0.1.13
+v0.1.16

lib/src/cli.rs

@@ -369,10 +369,19 @@ pub(crate) enum Opt {
     Edit(EditOpts),
     /// Display status
     ///
-    /// This will output a YAML-formatted object using a schema intended to match a Kubernetes resource
-    /// that describes the state of the booted system.
+    /// If standard output is a terminal, this will output a description of the bootc system state.
+    /// If standard output is not a terminal, output a YAML-formatted object using a schema
+    /// intended to match a Kubernetes resource that describes the state of the booted system.
     ///
-    /// The exact API format is not currently declared stable.
+    /// ## Parsing output via programs
+    ///
+    /// Either the default YAML format or `--format=json` can be used. Do not attempt to
+    /// explicitly parse the output of `--format=humanreadable` as it will very likely
+    /// change over time.
+    ///
+    /// ## Programmatically detecting whether the system is deployed via bootc
+    ///
+    /// Invoke e.g. `bootc status --json`, and check if `status.booted` is not `null`.
     Status(StatusOpts),
     /// Adds a transient writable overlayfs on `/usr` that will be discarded on reboot.
     ///

lib/src/status.rs

@@ -364,8 +364,7 @@ fn human_render_ostree(mut out: impl Write, slot_name: &str, _ostree_commit: &st
     Ok(())
 }
 
-/// Implementation of rendering our host structure in a "human readable" way.
-fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
+fn human_readable_output_booted(mut out: impl Write, host: &Host) -> Result<()> {
     for (slot_name, status) in [
         ("staged", &host.status.staged),
         ("booted", &host.status.booted),
@@ -386,6 +385,16 @@ fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
     Ok(())
 }
 
+/// Implementation of rendering our host structure in a "human readable" way.
+fn human_readable_output(mut out: impl Write, host: &Host) -> Result<()> {
+    if host.status.booted.is_some() {
+        human_readable_output_booted(out, host)?;
+    } else {
+        writeln!(out, "System is not deployed via bootc.")?;
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -465,15 +474,7 @@ mod tests {
         // staged/rollback image, no booted
         let w = human_status_from_spec_fixture(include_str!("fixtures/spec-staged-rollback.yaml"))
             .expect("No spec found");
-        let expected = indoc::indoc! { r"
-    Current staged image: quay.io/example/someimage:latest
-        Image version: nightly (2023-10-14 19:22:15 UTC)
-        Image digest: sha256:16dc2b6256b4ff0d2ec18d2dbfb06d117904010c8cf9732cdb022818cf7a7566
-    No booted image present
-    Current rollback image: quay.io/example/someimage:latest
-        Image version: nightly (2023-09-30 19:22:16 UTC)
-        Image digest: sha256:736b359467c9437c1ac915acaae952aad854e07eb4a16a94999a48af08c83c34
-    "};
+        let expected = "System is not deployed via bootc.\n";
         similar_asserts::assert_eq!(w, expected);
     }