From 6ebf105f06899218d74ce07ea6ed7f30f2b6a4d3 Mon Sep 17 00:00:00 2001
From: Noah White <noah@noahwhite.net>
Date: Fri, 23 Jan 2026 01:09:13 +0000
Subject: [PATCH 1/2] Add documentation for Alloy sysext version updates

- Add comment block in ghost.bu explaining image source and update process
- Add 'Updating Alloy Sysext Version' section to CLAUDE.md with step-by-step guide
- Document hash retrieval and infrastructure update commands
---
 CLAUDE.md                                     | 33 +++++++++++++++++++
 .../modules/vultr/instance/userdata/ghost.bu  | 17 ++++++++++
 2 files changed, 50 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index be6c0ad..3035fb9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -195,6 +195,39 @@ cd /var/mnt/storage/ghost-compose
 4. PR checks run automatically (fmt, plan)
 5. Merge triggers deployment (requires approval)
 
+### Updating Alloy Sysext Version
+
+The Grafana Alloy systemd-sysext image is built automatically by the
+[alloy-sysext-build](https://github.com/noahwhite/alloy-sysext-build) repository.
+
+**To update to a new version:**
+
+1. **Trigger a build** in alloy-sysext-build:
+   - Create a GitHub release with the version tag (e.g., `v1.11.0`)
+   - Or use workflow_dispatch with the version number
+
+2. **Wait for CI** to build and upload the image to R2
+
+3. **Get the SHA256 hash** from the build output or download the checksum file:
+   ```bash
+   curl -s https://ghost-sysext-images.separationofconcerns.dev/alloy-{VERSION}-amd64.raw.sha256
+   ```
+
+4. **Update ghost.bu** (`opentofu/modules/vultr/instance/userdata/ghost.bu`):
+   - Update the file path: `/opt/extensions/alloy/alloy-{VERSION}-amd64.raw`
+   - Update the source URL: `https://ghost-sysext-images.separationofconcerns.dev/alloy-{VERSION}-amd64.raw`
+   - Update the hash: `sha256-{HASH}`
+   - Update the symlink target in the `links` section
+
+5. **Apply infrastructure changes**:
+   ```bash
+   ./opentofu/scripts/tofu.sh dev plan
+   ./opentofu/scripts/tofu.sh dev apply
+   ```
+
+**Note:** The instance will need to be reprovisioned for the new sysext to take effect,
+as the Ignition config is only applied on first boot.
+
 ### Debugging deployment failures
 1. Check GitHub Actions logs
 2. SSH to instance and check container logs
diff --git a/opentofu/modules/vultr/instance/userdata/ghost.bu b/opentofu/modules/vultr/instance/userdata/ghost.bu
index 8df078b..903ae52 100644
--- a/opentofu/modules/vultr/instance/userdata/ghost.bu
+++ b/opentofu/modules/vultr/instance/userdata/ghost.bu
@@ -8,6 +8,22 @@ storage:
       label: ghost-storage
 
   files:
+    # ==========================================================================
+    # Grafana Alloy Sysext Image
+    # ==========================================================================
+    # This systemd-sysext image is built automatically by the alloy-sysext-build
+    # repository: https://github.com/noahwhite/alloy-sysext-build
+    #
+    # To update to a new Alloy version:
+    #   1. Trigger a build in alloy-sysext-build (release or workflow_dispatch)
+    #   2. CI builds and uploads the new image to the R2 bucket
+    #   3. Get the SHA256 hash from the .sha256 file or build output
+    #   4. Update the path, source URL, and hash below
+    #   5. Apply infrastructure changes via OpenTofu
+    #
+    # Quick hash retrieval:
+    #   curl -s https://ghost-sysext-images.separationofconcerns.dev/alloy-{VERSION}-amd64.raw.sha256
+    # ==========================================================================
     - path: /opt/extensions/alloy/alloy-1.10.2-amd64.raw
       mode: 0644
       contents:
@@ -82,6 +98,7 @@ storage:
       path: /etc/extensions/docker-compose.raw
       hard: false
 
+    # Symlink must be updated when changing Alloy version (path above)
     - target: /opt/extensions/alloy/alloy-1.10.2-amd64.raw
       path: /etc/extensions/alloy.raw
       hard: false

From d5de19f66a8c08527f032d526f29307eed31f603 Mon Sep 17 00:00:00 2001
From: Noah White <noah@noahwhite.net>
Date: Fri, 23 Jan 2026 15:03:13 +0000
Subject: [PATCH 2/2] Clarify note about instance reprovisioning behavior

Update note to explain that OpenTofu will destroy and recreate the instance
when Butane config changes, which is the expected idempotent behavior.
---
 CLAUDE.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3035fb9..7dda689 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -225,8 +225,9 @@ The Grafana Alloy systemd-sysext image is built automatically by the
    ./opentofu/scripts/tofu.sh dev apply
    ```
 
-**Note:** The instance will need to be reprovisioned for the new sysext to take effect,
-as the Ignition config is only applied on first boot.
+**Note:** Changing the Butane configuration (including the Alloy version) will cause
+OpenTofu to destroy and recreate the instance, as the Ignition config is immutable
+and only applied on first boot. This is the expected idempotent behavior.
 
 ### Debugging deployment failures
 1. Check GitHub Actions logs