Skip to content

docs: add a migration guide for Foreman users - #3

Open
Defilan wants to merge 5 commits into
mainfrom
docs/migrating-from-foreman
Open

Defilan wants to merge 5 commits into
mainfrom
docs/migrating-from-foreman

Conversation

@Defilan

@Defilan Defilan commented Nov 19, 2026

Copy link
Copy Markdown
Member

What

Adds docs/migrating-from-foreman.md, a step-by-step guide for moving a running Foreman install to Meitheal. It also fixes the CRD migration steps in the README, which now point to the guide instead of repeating them, and two stale lines in docs/README.md.

Why

Foreman moved out of LLMKube into this repository as Meitheal (defilantech/LLMKube#2526, removal in defilantech/LLMKube#2594). The new API group means new CRDs, so an existing install moves over beside Meitheal rather than upgrading in place. The old chart templates its CRDs without helm.sh/resource-policy: keep, so getting the order wrong deletes every Agent, AgenticTask, AgentRelease, FleetNode, ModelProfile and Workload.

The README's first step was wrong. It said to annotate the CRDs with keep and then uninstall, but helm uninstall reads that annotation from the release's stored manifest, not from the live CRD, so the annotation alone doesn't keep them.

How

Three commits:

  1. docs: add a migration guide for Foreman users: the guide.
    • The old-to-new name table: API group, labels, images, chart, CLI, metrics, macOS identifiers.
    • Six ordered steps:
      1. Record the resources, then annotate the CRDs.
      2. helm upgrade the foreman release at its installed chart version with --reuse-values --set crds.install=false, then confirm the CRDs and resources are still there. helm upgrade checks the live annotation before deleting a resource that left the manifest, so this takes the CRDs out of the release without deleting them.
      3. Install the meitheal chart beside it.
      4. Copy the durable resources.
      5. Let in-flight work finish.
      6. Uninstall foreman, then delete the old CRDs explicitly.
    • Edge cases found while writing it:
      • --reuse-values carries crds.install=false into exported values, so the install sets it back to true.
      • AgentReleases whose agentKind is foreman-agent are dropped, and the rest come back with approved: false.
      • Secrets are copied with kubectl create, never apply, and the git credentials Secret's default name changed.
      • Job-mode Agents need the new meitheal-coder service account and image.
      • Native macOS and Linux agents are reinstalled under the new identifiers.
  2. docs: fix the Foreman CRD migration steps: the README's migration section now explains why annotating alone fails and links the guide. docs/README.md links it too.
  3. docs: file issues in the Meitheal repo and fix the docs logo path: "Where to file issues" pointed at defilantech/LLMKube, and the logo path in docs/README.md went one directory too high.

The Helm behavior was checked against Helm's source (pkg/action/uninstall.go reads the stored manifest; pkg/kube/client.go re-reads the live object on upgrade). The jq filters were run against test objects. I haven't run the full sequence against a live Foreman release yet.

meitheal.dev (defilantech/meitheal-web) renders this guide in its docs once this merges.

Checklist

  • Tests added/updated
  • make test passes locally
  • make lint passes locally
  • Commit messages follow conventional commits
  • All commits are signed off (git commit -s) per DCO
  • AI assistance (if any) is disclosed above, per CONTRIBUTING.md
  • Documentation updated (if user-facing change)

Signed-off-by: Christopher Maher <chris@mahercode.io>
The README told Foreman users to annotate the six foreman.llmkube.dev CRDs with helm.sh/resource-policy: keep and then helm uninstall the release. helm uninstall reads the resource policy from the manifest stored with the release, not from the live objects, so the annotation alone would not have kept the CRDs or the resources in them. The migration guide takes the CRDs out of the release with a helm upgrade first, which does read the live annotation. Point the README and the docs index at that guide instead of repeating the steps.

Signed-off-by: Christopher Maher <chris@mahercode.io>
Signed-off-by: Christopher Maher <chris@mahercode.io>
Signed-off-by: Christopher Maher <chris@mahercode.io>
… migration

Signed-off-by: Christopher Maher <chris@mahercode.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant