-
Notifications
You must be signed in to change notification settings - Fork 70
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Talk about sysroot, growing #502
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
# Filesystem: Physical /sysroot | ||
|
||
The bootc project uses [ostree](https://github.com/ostreedev/ostree/) as a backend, | ||
and maps fetched container images to a [deployment](https://ostreedev.github.io/ostree/deployment/). | ||
|
||
## stateroot | ||
|
||
The underlying `ostree` CLI and API tooling expose a concept of `stateroot`, which | ||
is not yet exposed via `bootc`. The `stateroot` used by `bootc install` | ||
is just named `default`. | ||
|
||
The stateroot concept allows having fully separate parallel operating | ||
system installations with fully separate `/etc` and `/var`, while | ||
still sharing an underlying root filesystem. | ||
|
||
In the future, this functionality will be exposed and used by `bootc`. | ||
|
||
## /sysroot mount | ||
|
||
When booted, the physical root will be available at `/sysroot` as a | ||
read-only mount point. This is a key aspect of how `bootc upgrade` operates: | ||
it fetches the updated container image and writes new files to `/sysroot/ostree`. | ||
|
||
Beyond that and debugging/introspection, there are few use cases for tooling to | ||
operate on the physical root. | ||
|
||
## Expanding the root filesystem | ||
|
||
One notable use case that *does* need to operate on `/sysroot` | ||
is expanding the root filesystem. | ||
|
||
Some higher level tools such as e.g. `cloud-init` may (reasonably) | ||
expect the `/` mount point to be the physical root. Tools like | ||
this will need to be adjusted to instead detect this and operate | ||
on `/sysroot`. | ||
|
||
### Growing the block device | ||
|
||
Fundamentally bootc is agnostic to the underlying block device setup. | ||
How to grow the root block device depends on the underlying | ||
storage stack, from basic partitions to LVM. However, a | ||
common tool is the [growpart](https://manpages.debian.org/testing/cloud-guest-utils/growpart.1.en.html) | ||
utility from `cloud-init`. | ||
|
||
### Growing the filesytem | ||
|
||
The systemd project ships a [systemd-growfs](https://www.freedesktop.org/software/systemd/man/latest/systemd-growfs.html#) | ||
tool and corresponding `systemd-growfs@` services. This is | ||
a relatively thin abstraction over detecting the target | ||
root filesystem type and running the underlying tool such as | ||
`xfs_growfs`. | ||
|
||
At the current time, most Linux filesystems require | ||
the target to be mounted writable in order to grow. Hence, | ||
an invocation of `system-growfs /sysroot` or `xfs_growfs /sysroot` | ||
will need to be further wrapped in a temporary mount namespace. | ||
|
||
Using a `MountFlags=slave` drop-in stanza for `systemd-growfs@sysroot.service` | ||
is recommended, along with an `ExecStartPre=mount -o remount,rw /sysroot`. | ||
|
||
### Detecting bootc/ostree systems | ||
|
||
For tools like `cloud-init` that want to operate generically, | ||
conditionally detecting this situation can be done via e.g.: | ||
|
||
- Checking for `/` being an `overlay` mount point | ||
- Checking for `/sysroot/ostree` | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor/optional: at this point, we might as well provide a sample dropin to paint a clearer picture. We can do that as a follow-up of course.