README

README.md

@@ -1,4 +1,64 @@
-# Demonstration base images for Project Sagano
+# Sagano
+
+For many years, we've had Linux and containers operating in connected but
+separate worlds.  Today, we are excited to announce that we are bringing these
+worlds together.  We're making the ecosystem of content available to you in
+containers, now to your core Linux systems.  Containers now become the language
+for building the OS.  Boot them to your core Linux systems.  Modify them in a
+Containerfile/Dockerfile.  Whether standalone images to modify as you see fit in
+your datacenter, immutable images at the edge or worker nodes in
+Kubernetes/OpenShift - one, consistent approach.  We're always striving to make
+developing applications across the hybrid cloud easier and to make your IT
+landscape easier to manage even as you face increasing complexity.  And we hope
+you are as excited about this as we are.
+
+## Goals
+
+This project's toplevel goal is to create "base" *bootable* container images
+from Fedora ELN and CentOS Stream packages.
+
+## Trying it out
+
+See [install.md](./install.md).
+
+## Status
+
+This is an in-development project not intended for production use yet.
+
+## 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 Sagano also becomes a "base input" to RHEL for Edge.
+
+## What does Sagano means
+
+From [Wikipedia](https://en.wikipedia.org/wiki/Bamboo_Forest_(Kyoto,_Japan)):
+
+> Bamboo Forest, Arashiyama Bamboo Grove or Sagano 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 Sagano
 
 This is part of [Project Sagano](https://gitlab.com/CentOS/cloud/issue-tracker/-/blob/main/README.md).
 

cloud-agents.md

@@ -0,0 +1,60 @@
+# Project Sagano tier-1 and cloud agents
+
+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).

coreos.md

@@ -0,0 +1,9 @@
+# Relationship with CoreOS
+
+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.

install.md

@@ -0,0 +1,70 @@
+# Trying out Project Sagano development builds
+
+## 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 Sagano.
+
+```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:registry.gitlab.com/centos/cloud/sagano/fedora-boot-tier-1-dev:38
+systemctl reboot
+```
+
+See also [this pull request][1] for more information.
+
+## Installing via Anaconda
+
+For this path, see [this page in the sagano-examples](https://gitlab.com/CentOS/cloud/sagano-examples/-/tree/main/tier1-kickstart-unmodified).
+
+## 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 registry.gitlab.com/centos/cloud/sagano-examples/autonomous-podman-hello:latest 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://gitlab.com/CentOS/cloud/sagano-examples>
+- <https://github.com/coreos/layering-examples>
+- <https://github.com/openshift/rhcos-image-layering-examples>
+
+[1]: https://github.com/coreos/fedora-coreos-docs/pull/540