docs: more detail about using bootc images #189
Conversation
This adds more verbose details around composing base images, customizing images, installing images, and updating systems. It's intended to help users learning about the `bootc` paradigm by filling in some gaps on how to use things right now. It's noted that this information may be out of date quickly and will likely need multiple revisions to stay current.
|
Hi @miabbott. Thanks for your PR. I'm waiting for a containers member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
| possible to use [osbuild to generate disk images](https://github.com/osbuild/osbuild/pull/1418) | ||
| from a `bootc` compatible container image. | ||
|
|
||
| ## Updating your system with `bootc` |
There was a problem hiding this comment.
This section overlaps with other parts of the docs.
| You'll use `bootc upgrade` to instruct the system to pull the latest version of | ||
| your compatible container image and apply it to your system. | ||
|
|
||
| ## Switching the `bootc` compatible container image |
| use `bootc install-to-filesystem` to install the contents of the compatible | ||
| container image to an existing filesystem on a host. | ||
|
|
||
| These methods can be [driven interactively](https://github.com/containers/bootc/blob/main/docs/install.md#using-bootc-install-to-filesystem---replacealongside) |
There was a problem hiding this comment.
Let's make this a relative reference to just install.md.
| that a user could write a cloud-config snippet to drive the `bootc` install methods on | ||
| a cloud VM that supports `cloud-init`. | ||
|
|
||
| **NOTE:** The current implementation of the `install` and `install-to-filesystem` methods |
There was a problem hiding this comment.
I think we can clarify this in the install.md docs instead?
| The requirement for both methods is that your treefile/manifest **MUST** include | ||
| the `bootc` package in list of packages included in your compose. | ||
|
|
||
| ## Building a custom `bootc` compatible image |
There was a problem hiding this comment.
I'm OK with this but isn't it somewhat covered already by linking to e.g. https://github.com/coreos/layering-examples ?
(I think it'd be best to centralize that and clean it up alongside centos-boot )
| The easiest and most straight-forward way is to use `rpm-ostree compose image` | ||
| in order to produce a `bootc` compatible OCI image from a [treefile](https://coreos.github.io/rpm-ostree/treefile/) |
There was a problem hiding this comment.
This is already linked earlier in this doc, right?
| @@ -55,4 +55,79 @@ as part of your `RUN` invocations. This will perform early detection | |||
| of some incompatibilities but is not a strict requirement today and will not be | |||
| in the future. | |||
|
|
|||
| # Building and using `bootc` compatible images in the real world | |||
There was a problem hiding this comment.
I understand the sentiment but...overall ISTM we should try to improve the existing bits of the docs to match the "real world"
| The requirement for both methods is that your treefile/manifest **MUST** include | ||
| the `bootc` package in list of packages included in your compose. |
There was a problem hiding this comment.
Agree this bit should be clearer.
|
Maybe the biggest problem is that this base images doc happens to be ordered first, but should probably be last? Certainly a core tension running through this too is actually I think it'd be most useful to improve the centos-boot docs; started on that in CentOS/centos-bootc#33 |
I think that as many docs as possible should be moved here to bootc. At the moment, it's the core and the other bits are moving a lot (see the recent renaming).
Agreed that distro-specific things should be mentioned in the distro docs. For the rest, I'd prefer if the distros just point to the docs here to avoid redundancy and divergence. bootc docs could point to the individual distros and images. |
|
@cgwalters @vrothberg My intent was to provide a detailed description of the various phases of a building/using a compatible image using real world examples, based on the feedback from internal chat. I knew submitting this was going to duplicate some of existing docs, but I wanted gather more feedback on how best to structure this and where it should live. I'll clean up the PR based on the comments so far...if you have additional thoughts/guidance on how to approach telling this narrative or where it should live, please continue to share! |
|
As I started to address the feedback, the original intent of this PR drifted. I'll open a replacement PR shortly. |
This adds more verbose details around composing base images, customizing images, installing images, and updating systems. It's intended to help users learning about the
bootcparadigm by filling in some gaps on how to use things right now.It's noted that this information may be out of date quickly and will likely need multiple revisions to stay current.