Validate embedded FCCs in CI (#240)

* *: add missing FCC variant/version

* ign-storage: use valid SHA-512 hash to pass FCC validation

* storage: fix [storage,yaml] delimiter

* Add script to validate all FCCs in docs

* workflows: add workflow to validate FCCs

.github/workflows/checks.yml

@@ -0,0 +1,18 @@
+---
+name: Checks
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  fcc:
+    name: Validate FCCs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+      - name: Run validator
+        run: ./check.py

check.py

@@ -0,0 +1,53 @@
+#!/usr/bin/python3
+#
+# Find all FCCs in the doc tree, use the podman FCCT container to run them
+# through fcct --strict, and fail on any errors.
+#
+# An FCC looks like this:
+#
+# [source,yaml]
+# ----
+# variant:[...]
+# ----
+#
+# If variant: is missing, we print a warning but continue, since there
+# might be non-FCC [source,yaml] documents.
+
+import os
+import re
+import subprocess
+import sys
+import textwrap
+
+container = os.getenv('FCCT_CONTAINER', 'quay.io/coreos/fcct:release')
+matcher = re.compile(r'^\[source,\s*yaml\]\n----\n(.+?\n)----$', re.MULTILINE | re.DOTALL)
+
+def handle_error(e):
+    raise e
+
+ret = 0
+for dirpath, _, filenames in os.walk('.', onerror=handle_error):
+    for filename in filenames:
+        filepath = os.path.join(dirpath, filename)
+        if not filename.endswith('.adoc'):
+            continue
+        with open(filepath) as fh:
+            filedata = fh.read()
+        # Iterate over YAML source blocks
+        for match in matcher.finditer(filedata):
+            fcc = match.group(1)
+            fccline = filedata.count('\n', 0, match.start(1)) + 1
+            if not fcc.startswith('variant:'):
+                print(f'Ignoring non-FCC at {filepath} line {fccline}')
+                continue
+            result = subprocess.run(
+                    ['podman', 'run', '--rm', '-i', container, '--strict'],
+                    universal_newlines=True, # can be spelled "text" on >= 3.7
+                    input=fcc,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.PIPE)
+            if result.returncode != 0:
+                formatted = textwrap.indent(result.stderr.strip(), '  ')
+                print(f'Invalid FCC at {filepath} line {fccline}:\n{formatted}')
+                ret = 1
+sys.exit(ret)

modules/ROOT/pages/customize-nic.adoc

@@ -8,6 +8,8 @@ For example, to name NIC with the MAC address `12:34:56:78:9a:bc` to "infra", pl
 .Example: Customize NIC via systemd Link File
 [source,yaml]
 ----
+variant: fcos
+version: 1.3.0
 storage:
   files:
     - path: /etc/systemd/network/25-infra.link
@@ -26,6 +28,8 @@ Similarly, also through Ignition configs, to name NIC with the MAC address `12:3
 .Example: Customize NIC via Udev Rules
 [source,yaml]
 ----
+variant: fcos
+version: 1.3.0
 storage:
   files:
     - path: /etc/udev/rules.d/80-ifname.rules

modules/ROOT/pages/ign-passwd.adoc

@@ -35,7 +35,9 @@ You can also add a password hash to this user, specify the user's groups, and ad
 .Example for modifying and adding users:
 [source, yaml]
 ----
-  passwd:
+variant: fcos
+version: 1.3.0
+passwd:
   users:
     - name: core
       ssh_authorized_keys:

modules/ROOT/pages/ign-storage.adoc

@@ -231,7 +231,7 @@ storage:
         verification:
           # The hash is sha512- followed by the 128 hex characters given by
           # the sha512sum command.
-          hash: sha512-5c84785eb10c9efdea1f...
+          hash: sha512-00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
       # Makes the tool file readable and executable by all.
       mode: 0555
   links:

modules/ROOT/pages/migrate-ah.adoc

@@ -27,6 +27,8 @@ This can be manually translated into a xref:ign-passwd.adoc[`passwd`] node withi
 .Example of users:
 [source, yaml]
 ----
+variant: fcos
+version: 1.3.0
 passwd:
   users:
     - name: core

modules/ROOT/pages/storage.adoc

@@ -150,7 +150,7 @@ boot_device:
 
 Here is an example to configure a LUKS device at `/var/lib/data`.
 
-[source.yaml]
+[source,yaml]
 ----
 variant: fcos
 version: 1.2.0
@@ -169,7 +169,7 @@ storage:
 The root filesystem can also be moved to LUKS. In the case of the root filesystem the LUKS device must be backed by https://github.com/coreos/ignition/blob/master/docs/operator-notes.md#clevis-based-devices[clevis]. There is simplified FCC syntax for encrypting the root filesystem; for example:
 
 .Moving the root filesystem to LUKS
-[source.yaml]
+[source,yaml]
 ----
 variant: fcos
 version: 1.3.0
@@ -181,7 +181,7 @@ boot_device:
 This is equivalent to the following expanded config:
 
 .Moving the root filesystem to LUKS without using boot_device
-[source.yaml]
+[source,yaml]
 ----
 variant: fcos
 version: 1.3.0
@@ -207,7 +207,7 @@ The expanded config doesn't include the `path` or `with_mount_unit` keys; FCOS k
 If you use Ignition to reconfigure or move the root partition, that partition is not automatically grown on first boot (see related discussions in https://github.com/coreos/fedora-coreos-tracker/issues/570[this issue]). In the case of moving the root partition to a new disk (or multiple disks), you should set the desired partition size using the `size_mib` field. If reconfiguring the root filesystem in place, as in the LUKS example above, you can resize the existing partition using the `resize` field:
 
 .Resizing the root partition to its maximum size
-[source.yaml]
+[source,yaml]
 ----
 variant: fcos
 version: 1.2.0
@@ -238,7 +238,7 @@ storage:
 This example configures a mirrored boot disk with a TPM2-encrypted root filesystem, overrides the sizes of the automatically-generated root partition replicas, and adds an encrypted mirrored `/var` partition which consumes the remainder of the disks.
 
 .Encrypted mirrored boot disk with separate /var
-[source.yaml]
+[source,yaml]
 ----
 variant: fcos
 version: 1.3.0