Add GH Pages infrastructure
Start to migrate from README.md to the Pages infrastructure for nicer looking and more organized docs.
This commit is contained in:
Colin Walters
parent
2077e64595
commit
d913e9ba82
9 changed files with 264 additions and 113 deletions
14
docs/Gemfile
Normal file
14
docs/Gemfile
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
# Bundler setup for jekyll to be deployed on github pages.
|
||||
|
||||
source "https://rubygems.org"
|
||||
|
||||
# Note that we're using the github-pages gem to mimic the GitHub pages
|
||||
# automated setup. That installs jekyll, a default set of jekyll
|
||||
# plugins, and a modified jekyll configuration.
|
||||
group :jekyll_plugins do
|
||||
gem "github-pages"
|
||||
gem "jekyll-remote-theme"
|
||||
end
|
||||
|
||||
# Prefer the GitHub flavored markdown version of kramdown.
|
||||
gem "kramdown-parser-gfm"
|
||||
58
docs/_config.yml
Normal file
58
docs/_config.yml
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
title: containers/bootc
|
||||
description: bootc documentation
|
||||
baseurl: "/centos-boot"
|
||||
url: "https://centos.github.io"
|
||||
# Comment above and use below for local development
|
||||
# url: "http://localhost:4000"
|
||||
permalink: /:title/
|
||||
markdown: kramdown
|
||||
kramdown:
|
||||
typographic_symbols:
|
||||
ndash: "--"
|
||||
mdash: "---"
|
||||
|
||||
# Exclude the README and the bundler files that would normally be
|
||||
# ignored by default.
|
||||
exclude:
|
||||
- README.md
|
||||
- Gemfile
|
||||
- Gemfile.lock
|
||||
- prep-docs.sh
|
||||
- vendor/
|
||||
|
||||
# These are copies of the apidoc/html and man/html directories. Run
|
||||
# prep-docs.sh before jekyll to put it in place.
|
||||
include: [reference, man]
|
||||
|
||||
remote_theme: just-the-docs/just-the-docs@v0.4.1
|
||||
plugins:
|
||||
- jekyll-remote-theme
|
||||
|
||||
color_scheme: coreos
|
||||
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
"bootc on GitHub":
|
||||
- "https://github.com/containers/bootc"
|
||||
|
||||
footer_content: "Copyright © <a href=\"https://www.redhat.com\">Red Hat, Inc.</a> and <a href=\"https://github.com/containers\">others</a>."
|
||||
|
||||
# Footer last edited timestamp
|
||||
last_edit_timestamp: true
|
||||
last_edit_time_format: "%b %e %Y at %I:%M %p"
|
||||
|
||||
# Footer "Edit this page on GitHub" link text
|
||||
gh_edit_link: true
|
||||
gh_edit_link_text: "Edit this page on GitHub"
|
||||
gh_edit_repository: "https://github.com/containers/bootc"
|
||||
gh_edit_branch: "main"
|
||||
gh_edit_source: docs
|
||||
gh_edit_view_mode: "tree"
|
||||
|
||||
compress_html:
|
||||
clippings: all
|
||||
comments: all
|
||||
endings: all
|
||||
startings: []
|
||||
blanklines: false
|
||||
profile: false
|
||||
1
docs/_sass/color_schemes/coreos.scss
Normal file
1
docs/_sass/color_schemes/coreos.scss
Normal file
|
|
@ -0,0 +1 @@
|
|||
$link-color: #53a3da;
|
||||
64
docs/cloud-agents.md
Normal file
64
docs/cloud-agents.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# Project CentOS boot tier-1 and cloud agents
|
||||
|
||||
---
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
The tier-0 and tier-1 images today do not contain any special
|
||||
hypervisor-specific agents. The following specifically are not included
|
||||
for example:
|
||||
|
||||
- cloud-init
|
||||
- vmware-guest-agent
|
||||
- google-guest-agent
|
||||
- qemu-guest-agent
|
||||
- ignition
|
||||
- afterburn
|
||||
|
||||
etc.
|
||||
|
||||
## Unnecessary on bare metal
|
||||
|
||||
For deployment to bare metal using e.g. Anaconda or `bootc install`, none of
|
||||
these are necessary.
|
||||
|
||||
## Unnecessary for "immutable infrastructure" on hypervisors
|
||||
|
||||
A model we aim to emphasize is having the container image define the
|
||||
"source of truth" for system state. This conflicts with using e.g. `cloud-init`
|
||||
and having it fetch instance metadata and raises questions around changes to the
|
||||
instance metadata and when they apply.
|
||||
|
||||
Related to this, `vmware-guest-agent` includes a full "backdoor" mechanism to
|
||||
log into the OS.
|
||||
|
||||
## Should be containerized anyways
|
||||
|
||||
In general particularly for e.g. `vmware-guest-agent`, it makes more sense to
|
||||
containerize it.
|
||||
|
||||
## Easy to install afterward
|
||||
|
||||
Many of these (particularly the first ones mentioned) are easy to install in a
|
||||
custom image.
|
||||
|
||||
You can build your own derived image that includes e.g. vmware-guest-agent if
|
||||
required alongside all other desired customizations.
|
||||
|
||||
## Fully supported if installed
|
||||
|
||||
It is supported to include these agents in your image if desired (whether as
|
||||
part of the base image or containerized).
|
||||
|
||||
## What about Ignition
|
||||
|
||||
Ignition as shipped by CoreOS Container Linux derivatives has a lot of
|
||||
advantages in providing a model that works smoothly across both bare metal and
|
||||
virtualized scenarios.
|
||||
|
||||
It also has some compelling advantages over cloud-init at a technical level.
|
||||
|
||||
However, there is also significant overlap between a container-focused model of
|
||||
the world and an Ignition-focused model.
|
||||
|
||||
More on this topic in [coreos.md](coreos.md).
|
||||
13
docs/coreos.md
Normal file
13
docs/coreos.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
# Relationship with CoreOS
|
||||
|
||||
---
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
The CoreOS Container Linux project was very successful, spawning multiple projects
|
||||
and derivatives that continue to see widespread use today.
|
||||
|
||||
An aim of this project is to share code and logic with Fedora CoreOS and its derivatives,
|
||||
such as Red Hat Enterprise Linux CoreOS. At the current time, these systems continue
|
||||
to exist and success for this project will include sharing as much code as possible
|
||||
with them.
|
||||
118
docs/index.md
Normal file
118
docs/index.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# Goals
|
||||
|
||||
This project's toplevel goal is to create base *bootable* container images
|
||||
from Fedora ELN and CentOS Stream packages.
|
||||
|
||||
## Status
|
||||
|
||||
This is an in-development project not intended for production use yet.
|
||||
|
||||
## Trying it out
|
||||
|
||||
See [install.md](./install.md).
|
||||
|
||||
## Differences from Fedora CoreOS
|
||||
|
||||
Fedora CoreOS today is not small; there are multiple reasons for this, but
|
||||
primarily because it was created in a pre-bootable-container time. Not everyone
|
||||
wants e.g. moby-engine.
|
||||
|
||||
But going beyond size, the images produced by this project will focus
|
||||
on a container-native flow. We will ship a (container) image that does not
|
||||
include Ignition for example.
|
||||
|
||||
## Differences from RHEL CoreOS
|
||||
|
||||
We sometimes say that RHEL CoreOS [has FCOS as an upstream][1] but this is only
|
||||
kind of true; RHEL CoreOS includes a subset of FCOS content, and is lifecycled
|
||||
with OCP.
|
||||
|
||||
An explicit goal of this project is to produce bootable container images
|
||||
that can be used as *base images* for RHEL CoreOS; for more on this, see e.g.
|
||||
<https://github.com/openshift/os/issues/799>
|
||||
|
||||
## Differences from RHEL for Edge
|
||||
|
||||
It is an explicit goal that CentOS boot also becomes a "base input" to RHEL for Edge.
|
||||
|
||||
## What does CentOS boot means
|
||||
|
||||
From [Wikipedia](https://en.wikipedia.org/wiki/Bamboo_Forest_(Kyoto,_Japan)):
|
||||
|
||||
> Bamboo Forest, Arashiyama Bamboo Grove or CentOS boot Bamboo Forest, is a natural
|
||||
> forest of bamboo in Arashiyama, Kyoto, Japan
|
||||
|
||||
[1]: https://github.com/openshift/os/blob/master/docs/faq.md#q-what-is-coreos
|
||||
|
||||
## Demonstration base images for Project CentOS boot
|
||||
|
||||
These images are technology demonstrators, not for production use. The
|
||||
intention is that these images are generated by the OS vendor or
|
||||
distribution.
|
||||
Or, you can fork this repository and generate your own via
|
||||
`rpm-ostree compose image`.
|
||||
|
||||
## Operating system sources
|
||||
|
||||
At the moment these demonstration builds use Fedora ELN and CentOS Stream 9.
|
||||
|
||||
## Tiers
|
||||
|
||||
### Tier 0
|
||||
|
||||
This is the basic tier; it has effectively just:
|
||||
|
||||
- kernel systemd selinux-policy-targeted bootc
|
||||
|
||||
You are generally going to need to generate derived images from this; installing
|
||||
it on its own will boot to a system with no automatic networking support, no SSH,
|
||||
and no default passwords etc.
|
||||
|
||||
### Tier 1
|
||||
|
||||
This is larger system.
|
||||
|
||||
- NetworkManager, chrony
|
||||
- rpm-ostree (to install packages and in case it's useful "day 2")
|
||||
- openssh-server
|
||||
|
||||
At the current time, it does not include Ignition or cloud-init; so you will
|
||||
still need to derive from it in order to inject a mechanism to log in in many
|
||||
cases. However, it will work to install it using e.g. Anaconda and set up
|
||||
users and passwords that way.
|
||||
|
||||
## Image matrix (Fedora)
|
||||
|
||||
- `quay.io/centos-boot/fedora-tier-1:eln`
|
||||
|
||||
### More about image sources
|
||||
|
||||
The current manifest definitions [tier-0](tier-0) and [tier-1](tier-1) were
|
||||
forked from Fedora CoreOS, but significantly cut down.
|
||||
|
||||
The existing content set is obviously subject to change and debate.
|
||||
|
||||
## Building
|
||||
|
||||
Here's an example command:
|
||||
|
||||
```shell
|
||||
sudo rpm-ostree compose image --authfile ~/.config/containers/myquay.json --cachedir=cache -i --format=ociarchive centos-tier-0-stream9.yaml centos-tier-0-stream9.ociarchive
|
||||
```
|
||||
|
||||
In some situations, copying to a local `.ociarchive` file is convenient. You
|
||||
can also push to a registry with `--format=registry`.
|
||||
|
||||
More information at <https://coreos.github.io/rpm-ostree/container/>
|
||||
|
||||
## Badges
|
||||
|
||||
| Badge | Description | Service |
|
||||
| ----------------------- | -------------------- | ------------ |
|
||||
| [![Renovate][1]][2] | Dependencies | Renovate |
|
||||
| [![Pre-commit][3]][4] | Static quality gates | pre-commit |
|
||||
|
||||
[1]: https://img.shields.io/badge/renovate-enabled-brightgreen?logo=renovate
|
||||
[2]: https://renovatebot.com
|
||||
[3]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
|
||||
[4]: https://pre-commit.com/
|
||||
71
docs/install.md
Normal file
71
docs/install.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
# Trying out development builds
|
||||
|
||||
---
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
<!--
|
||||
## Booting directly from KVM guest image
|
||||
|
||||
There's a provisional KVM guest image uploaded here:
|
||||
|
||||
<https://fedorapeople.org/~walters/cloud-init-base-eln-20231029.qcow2.zst>
|
||||
|
||||
You can run it using e.g. [virt-install](https://github.com/virt-manager/virt-manager/blob/main/man/virt-install.rst#--cloud-init)
|
||||
and in general all the same techniques that work the Fedora Cloud Base or the
|
||||
RHEL KVM guest image.
|
||||
|
||||
Once you've booted this, use e.g. `bootc update` to fetch updates.
|
||||
-->
|
||||
|
||||
## Rebasing from Fedora CoreOS
|
||||
|
||||
[Fedora CoreOS](https://docs.fedoraproject.org/en-US/fedora-coreos/) supports
|
||||
many different platforms, and can be used as a starting point to "rebase" to a
|
||||
custom derived image from CentOS boot.
|
||||
|
||||
```shell
|
||||
systemctl mask --now zincati && rm -vf /run/ostree/staged-deployment-locked
|
||||
echo "# dummy change" >> "/etc/sudoers.d/coreos-sudo-group"
|
||||
rpm-ostree rebase ostree-unverified-registry:quay.io/centos-boot/fedora-tier-1:eln
|
||||
systemctl reboot
|
||||
```
|
||||
|
||||
See also [this pull request][1] for more information.
|
||||
|
||||
## TODO: Use osbuild
|
||||
|
||||
Document the ongoing work to materialize a disk image from a container.
|
||||
|
||||
## Using `bootc install-to-filesystem --replace=alongside` with a cloud image
|
||||
|
||||
A toplevel goal of this project is that the "source of truth" for Linux
|
||||
operating system management is a container image registry - as opposed to e.g. a
|
||||
set of qcow2 OpenStack images or AMIs, etc.
|
||||
|
||||
The latest development builds of `bootc` have support for
|
||||
`bootc install-to-filesystem --replace=alongside`. More about this core
|
||||
mechanic in the [bootc install docs](https://github.com/containers/bootc/blob/main/docs/install.md).
|
||||
|
||||
Here's an example set of steps to execute; this could be done via e.g.
|
||||
[cloud-init](https://cloudinit.readthedocs.io/en/latest/reference/index.html)
|
||||
configuration.
|
||||
|
||||
```shell
|
||||
dnf -y install podman skopeo
|
||||
podman run --rm --privileged --pid=host -v /:/target --security-opt label=type:unconfined_t quay.io/centos-boot/fedora-tier-1:eln bootc install-to-filesystem --target-no-signature-verification --karg=console=ttyS0,115200n8 --replace=alongside /target
|
||||
reboot
|
||||
```
|
||||
|
||||
## Generating a derived container image
|
||||
|
||||
These examples just use a "stock" container image, and in the first case rely on
|
||||
user state being preserved by the `rpm-ostree rebase`.
|
||||
|
||||
What's much more interesting is to generate a custom derived container image,
|
||||
and target that instead. For more information, see
|
||||
|
||||
- <https://github.com/coreos/layering-examples>
|
||||
- <https://github.com/openshift/rhcos-image-layering-examples>
|
||||
|
||||
[1]: https://github.com/coreos/fedora-coreos-docs/pull/540
|
||||
Loading…
Add table
Add a link
Reference in a new issue