Spike: build and publish pre-provisioned k3d local appliance image

[rowan-stein]

User request

Create a non-destructive spike in agynio/bootstrap to try building and publishing an image that already contains a fully provisioned local Agyn stack.

The goal is not to make normal bootstrap slightly faster by caching images. The goal is to investigate and implement a prototype artifact where the Kubernetes specs have already been applied, PVCs have already been created, service images are already present, and the local stack can start without running the full provisioning/reconciliation flow on the user's machine.

Important constraint: do not break or replace the existing bootstrap flow. Existing apply.sh, CI users, and downstream dependencies must continue working as-is by default.

Research / specification

agynio/architecture establishes that agynio/bootstrap is the source of truth for the full local Agyn cluster. This spike should therefore generate the appliance from bootstrap rather than maintain a separate topology.

Recommended prototype direction:

1. Add an opt-in build/publish path for a pre-provisioned k3d/k3s node image or equivalent local appliance artifact.
2. During artifact build:
   • create a normal local k3d cluster using existing bootstrap logic,
   • run full bootstrap,
   • wait for platform health,
   • stop the cluster cleanly,
   • capture the k3s node state needed to restart with the platform already installed.
3. Attempt to preserve:
   • k3s datastore containing applied Kubernetes objects,
   • Argo CD state and installed apps,
   • containerd image store or equivalent preloaded images,
   • local-path PVC backing data,
   • initialized local development data where applicable.
4. Publish a versioned image/artifact to GHCR if feasible.
5. Add documentation describing how to build, publish, and manually test the artifact.
6. Keep the existing bootstrap path unchanged unless an explicit new script/action/flag is used.

Potential implementation approaches to evaluate in the PR:

• Commit a fully bootstrapped k3d server container into a reusable image.
• If Docker volumes contain required state, snapshot and restore those volumes explicitly.
• If a single Docker image cannot capture enough state, document the limitation and add the minimum image+state artifact structure needed for a follow-up.

Validation target:

• Build/provision from clean state.
• Capture the local appliance image/artifact.
• Delete the build cluster.
• Recreate/start from the captured artifact.
• Confirm:
  • Kubernetes API starts,
  • nodes are ready,
  • pods become healthy without full bootstrap,
  • PVCs/PVs are present,
  • key platform services are reachable,
  • existing bootstrap still works normally.

Non-goals for this spike:

• Do not replace existing apply.sh behavior.
• Do not require all users to use the appliance path.
• Do not introduce a separate hand-maintained Docker Compose topology.
• Do not bake production/staging credentials or any external Agyn secrets into the artifact.

Security constraints:

The artifact may contain local-only development credentials if needed, but must not contain:

• GitHub tokens,
• GHCR write tokens,
• production/staging credentials,
• cloud credentials,
• real Ziti enrollment tokens for external environments,
• any secret that grants access to non-local Agyn infrastructure.