linode / linode/apl-core

Everything-is-an-app: migrate existing clusters (offline settings + runtime diff-extraction)

Open
#3,580 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ready-for-agent
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.