From 197d23d16b0454ab61d6bb3f96d9b16c6fa0545d Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Tue, 27 Jul 2021 13:28:10 -0400
Subject: [PATCH] docs: Add a "Creating derived configs" section

xref https://github.com/openshift/machine-config-operator/issues/1720

This also came up in e.g.
https://github.com/coreos/fedora-coreos-docs/pull/264/files#diff-089ac9657fd668d3f0f2d3dcb663fe1c75e72aaefac2ff1d78ae70c9cf96e46eR185
---
 docs/examples.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 test             |  1 +
 2 files changed, 46 insertions(+)

diff --git a/docs/examples.md b/docs/examples.md
index 50a7a122..093c4324 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -374,6 +374,51 @@ systemd:
         WantedBy=multi-user.target
 ```
 
+### Creating derived configs
+
+A common scenario will be to have a "base" Ignition config, and then
+you want to create machine-specific versions that e.g. contain
+static IP addressing or a static `/etc/hostname`, etc.
+
+Another common scenario is to have a pool of bare metal machines
+where some have e.g. SATA disks, other newer machines have NVMe
+drives, etc.
+
+In the following, the `base.ign` is an Ignition config file you
+have locally.  It could be generated via whatever mechanism you prefer (could also be butane, or not).
+These examples just change the value of `/etc/hostname`, but everything
+above (storage configuration etc.) can be added too.
+
+<!-- butane-config -->
+```yaml
+variant: fcos
+version: 1.1.0
+ignition:
+  config:
+    merge:
+      - local: base.ign
+storage:
+  files:
+    - path: /etc/hostname
+      contents:
+        inline: foo.example.com
+```
+
+<!-- butane-config -->
+```yaml
+variant: fcos
+version: 1.1.0
+ignition:
+  config:
+    merge:
+      - local: base.ign
+storage:
+  files:
+    - path: /etc/hostname
+      contents:
+        inline: bar.example.com
+```
+
 [spec]: specs.md
 [dropins]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description
 [fcos-auth-docs]: https://docs.fedoraproject.org/en-US/fedora-coreos/authentication
diff --git a/test b/test
index a8b76cdd..2c2dade8 100755
--- a/test
+++ b/test
@@ -28,6 +28,7 @@ trap 'rm -r tmpdocs' EXIT
 # Create files-dir contents expected by configs
 mkdir -p tmpdocs/files-dir/tree
 touch tmpdocs/files-dir/{config.ign,ca.pem,file,file-epilogue,local-file3}
+ln -sr tmpdocs/files-dir/{config,base}.ign
 
 for doc in docs/*md
 do