home-ops: Skill for Claude Code

Flux GitOps: apps, overlays, health checks and live testing

Flux reconciles from kubernetes/clusters/main only. cluster-meta builds kubernetes/apps/base/flux-system/meta; cluster-apps builds kubernetes/apps/main. There is no separate FluxInstance manifest: the flux-instance HelmRelease sets values.instance.sync.path.

Tripwires

1. healthChecks target the workload, and a Kustomization that owns a kopiur or VolSync claim keeps wait false. A HelmRelease-kind check stays Ready through a crashloop. Point the list at the Deployment, StatefulSet, DaemonSet, CronJob, or the CR whose status is the real signal. Flux ignores spec.healthChecks when spec.wait: true and assesses the whole inventory instead (usually just the HelmRelease). healthCheckExprs run only for objects already in that assessment set. wait: true is correct for a pure dependency gate that others dependsOn (checked 2026-09-30, 20 live): CRDs (agentgateway-crds, toolhive-crds), operators and clusters (cloudnative-pg, postgres-cluster-17, dragonfly-operator, emqx-*, surrealdb, keda), secret stores (external-secrets, onepassword-store, database-secrets), cluster-meta, multus-networks, certificates-import, cloudflare-dns, coder. None of them includes components/kopiur or components/volsync, which deadlocks wait: true. Recount with kubectl get ks -A -o json | jq '[.items[]|select(.spec.wait==true)]|length'.
2. Suspend the Kustomization before a live HelmRelease edit. Its interval (or any flux reconcile ks) reapplies main and drops the experiment. flux resume itself reconciles back to main.
3. kubectl apply cannot remove a values key on a Flux-managed HelmRelease. There is no last-applied-configuration, so apply merges and keeps keys you deleted. Use kubectl replace, or delete the key, and re-read .spec.values.
4. Helm cannot unset a field it never rendered. A hand-added securityContext, or a new volumes / volumeMounts entry, survives flux reconcile --force. Undo with a strategic-merge $patch: delete.
5. Namespace/flux-system is exempt from cluster-apps. The live object carries kustomize.toolkit.fluxcd.io/ssa: Ignore and empty managedFields. A label that kustomize build renders for it still needs a live check after merge. Do not add a base/flux-system/namespace.yaml to chase it.
6. flate -n is a false green. -n filters the result and the exit code. A broken Kustomization in another namespace still exits 0. task flux:test:all (unscoped) is the gate. It also does not catch a literal ${...} collision: skill flux-substitution.
7. A stale Ready=False can hide a fix already applied. controller-runtime backs off. Compare lastTransitionTime to now and check operator logs before changing anything else. Restarting a stateless reconciler clears the backoff; do not restart cloudnative-pg mid-switchover or rook-ceph mid-OSD update.
8. A new app is done when it renders. task flux:test:all is the pre-merge bar. Live confirmation is a post-merge follow-up. An out-of-band kubectl apply of a brand-new app is the drift GitOps exists to prevent.
9. Never seed a Secret with client-side kubectl apply. The value is copied into kubectl.kubernetes.io/last-applied-configuration. Use kubectl create, or server-side apply. Skill secrets-1password.
10. FluxResourceSuspendedTooLong keys exported_namespace. flux_resource_info is the only live suspended signal. kube-state-metrics has no Flux CRD state. The metric's namespace label is always flux-system, because it is a metric on the operator.
11. FluxResourceNotReadyTooLong is the state alert for a stuck release. A HelmRelease that fails its first install goes Stalled (MissingRollbackTarget) and emits no further events, so the one-shot Flux Alert event is the only other signal. The rule fires when a HelmRelease or Kustomization is not Ready=True for 30m, aggregated over kind, namespace and name so retries flipping False/Unknown and changing reason do not reset the timer; fix the cause, then flux reconcile hr <name> -n <ns> --reset.