Everything-is-an-app: migrate existing clusters (offline settings + runtime diff-extraction)
Nobody has claimed this yet.
- Dominant language
- Go Template
- Stars
- 2.3k
- Forks
- 186
- Avg merge
- 3d 11h
- Merged PRs (30d)
- 66
Description
## Parent
linode/apl-core#3515
> **Design update (supersedes original §3/§8):** offline settings migration populates `AplCluster.spec.apps` enable flags in `env/settings/cluster.yaml` (not `env/settings/apps.yaml`) via leaf-path `values-changes.yaml` relocations. See linode/apl-core#3515 comment and ADR `adr/2026-08-21-app-enable-flags-in-aplcluster.md`.
## What to build
The **final step**: migrate existing clusters onto the new layout without losing user configuration, delivered as two coordinated tracks.
End-to-end behavior:
- **Offline settings migration** — the existing `otomi migrate` / `values-changes.yaml` pipeline (kept, not retired) moves platform **settings** files into their new locations, including populating `AplCluster.spec.apps` enable flags in `env/settings/cluster.yaml`. Enable flags migrate as **leaf-path** relocations (`apps..enabled: cluster.apps..enabled`, plus nested gating exceptions such as `apps.istio.egressGateway.enabled: cluster.apps.istio.egressGateway.enabled`), so only enablement leaves move — the rest of `apps.` flows to the runtime app-values track below.
- **Runtime app-values migration** — a one-time, cluster-aware operator upgrade step reconstructs each app's `values.custom.yaml` from the running cluster:
1. Read the existing `Application`'s effective values from the cluster (inline `spec.source.helm.values`, fallback `helm get values `).
2. Render the app's new `values.managed.yaml`.
3. `values.custom.yaml = deepDiff(existingEffective, managed)` — a key lands in custom **iff** it is absent from or differs from managed (minimal custom.yaml).
4. Write `custom` + `managed`, commit, and let the multi-source `Application` (same `-` name) supersede the inline one as an update, not a replace.
- Because the cluster already holds vendor-shaped effective values, this auto-handles curated→vendor translation and multi-release splitting with no hand-authored per-app mapping.
Must run after all cutover batches so the new layout exists for every app.
## Acceptance criteria
- [ ] `otomi migrate` moves platform settings and populates `AplCluster.spec.apps` enable flags in `env/settings/cluster.yaml` (leaf-path relocations) on an existing values repo.
- [ ] The runtime step reconstructs a minimal `values.custom.yaml` per app via `deepDiff(existing effective values, managed)` and commits `custom` + `managed`.
- [ ] The updated multi-source `Application` supersedes the inline one in place (same `-` name) with no drift / no destroy-recreate.
- [ ] A customized app on an existing cluster retains its customizations after migration.
- [ ] Unit tests cover the diff rule (absent-or-differing → custom) with fixtures, no real git/K8s.
## Blocked by
- linode/apl-core#3575
- linode/apl-core#3576
- linode/apl-core#3577
- linode/apl-core#3578
- linode/apl-core#3579
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ADR `adr/2026-08-21-app-enable-flags-in-aplcluster.md`, the `otomi migrate`/`values-changes.yaml` pipeline, and `env/settings/cluster.yaml`. Trace how runtime values are read and how `values.custom.yaml` and `values.managed.yaml` are written, then add fixture-based unit tests for the diff rule; done means settings and runtime values migrate without losing customizations or replacing the existing Application.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, helm, kubernetes
- Domain
- devops, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100