From 1626789119062d5f43d5361e9979808a6c1d32cc Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 1 May 2023 16:02:26 -0400
Subject: [PATCH] Add a doc for container provisioning and updates

The layering model is an entirely new way to do systems
management.  Let's document the current state.
---
 modules/ROOT/pages/deriving-container.adoc | 100 +++++++++++++++++++++
 modules/ROOT/pages/getting-started.adoc    |   2 +-
 2 files changed, 101 insertions(+), 1 deletion(-)
 create mode 100644 modules/ROOT/pages/deriving-container.adoc

diff --git a/modules/ROOT/pages/deriving-container.adoc b/modules/ROOT/pages/deriving-container.adoc
new file mode 100644
index 00000000..67f56bd0
--- /dev/null
+++ b/modules/ROOT/pages/deriving-container.adoc
@@ -0,0 +1,100 @@
+= Deriving from Fedora CoreOS as a bootable container image
+
+== Bootable containers overview
+
+The operating system images used for Fedora CoreOS are available as a standard container image; there is one per stream. See xref:update-streams.adoc[Update Streams].
+
+- quay.io/fedora/fedora-coreos:stable
+- quay.io/fedora/fedora-coreos:next
+- quay.io/fedora/fedora-coreos:testing
+
+== Creating custom builds
+
+See the https://github.com/coreos/layering-examples[layering examples] git repository.  While the examples there tend to use Containerfile/Dockerfile style builds, you can use any tool which can build containers and push the result to a registry.
+
+== Using Ignition to switch to a bootable container image
+
+The https://coreos.github.io/rpm-ostree/container/[rpm-ostree container page] describes the commands for interacting with bootable ostree container images.
+
+In this example, we will use a systemd unit to fetch and reboot into the target custom container image, and also install a systemd unit which will enable
+automatic polling of the target tag, and reboot on changes.
+
+Note: This process means that OS updates are entirely triggered by pushes to the container registry.  Because `zincati` is not used here, the extra functionality described in xref:auto-updates.doc[Auto-Updates] such as wariness will work.
+
+[source,yaml]
+----
+variant: fcos
+version: 1.4.0
+systemd:
+  units:
+    # Our custom unit for rebasing
+    - name: rebase-custom.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Fetch and deploy target image
+        # Only run on the firstboot
+        ConditionFirstBoot=true
+        After=network-online.target
+        [Service]
+        # This ordering is important
+        After=ignition-firstboot-complete.service
+        Type=oneshot
+        RemainAfterExit=yes
+        ExecStart=rpm-ostree rebase --reboot ostree-unverified-registry:quay.io/example/example-derived:latest
+        [Install]
+        WantedBy=multi-user.target
+    # Our custom unit for automatic upgrades
+    - name: autoupdate-host.service
+      enabled: false
+      contents: |
+        [Unit]
+        Description=Automatic host upgrades
+        [Service]
+        Type=simple
+        ExecStart=rpm-ostree upgrade --reboot
+        StandardOutput=null
+    # zincati does not yet understand containers
+    - name: zincati.service
+      enabled: false
+    # Our custom unit for automatic upgrades
+    - name: autoupdate-host.timer
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Automatic daily host upgrades
+        [Timer]
+        OnBootSec=1h
+        OnUnitInactiveSec=1d
+        [Install]
+        WantedBy=timers.target
+----
+
+== Adding pull secrets for private container images
+
+If your registry requires authentication, then you can add a pull secret.  See https://coreos.github.io/rpm-ostree/container/#registry-authentication[container pull secrets].
+
+[source,yaml]
+----
+variant: fcos
+version: 1.4.0
+storage:
+  files:
+    - path: /etc/ostree/auth.json
+      mode: 0600
+      contents:
+        inline: >
+              {
+                   "auths": {
+                        "quay.io": {
+                             "auth": "..."
+                        }
+                   }
+              }
+----
+
+== Maintaining custom builds
+
+As the upstream container image (e.g. quay.io/fedora/fedora-coreos:stable) changes for security and functionality improvements, you are responsible for re-building your derived image.  Implementing this depends on your chosen container build system.
+
+However, key to this model is the assumption that if you're deploying Fedora CoreOS, you have already invested in container infrastructure and can manage the operating system updates in the same way as application containers.
diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc
index a0af4c33..081263ed 100644
--- a/modules/ROOT/pages/getting-started.adoc
+++ b/modules/ROOT/pages/getting-started.adoc
@@ -19,7 +19,7 @@ Fedora CoreOS does not have a separate install disk. Instead, every instance sta
 
 Each platform has specific logic to retrieve and apply the first boot configuration. For cloud deployments, Ignition gathers the configuration via user-data mechanisms. In the case of bare metal, Ignition can fetch its configuration from the disk or from a remote source.
 
-For more information on configuration, refer to the documentation for xref:producing-ign.adoc[Producing an Ignition File].
+For more information on configuration, refer to the documentation for xref:producing-ign.adoc[Producing an Ignition File].  There is also the ability to derive from the container base image, see xref:deriving-container.adoc[Booting a derived container image].
 
 == Quickstart