alexei.dolgolyov
7733e64b08
A dockerfile or static workload can opt in to reading its deploy config from a
.tinyforge.yml in its own repo. Tinyforge fetches the file, shows field-level
drift vs the live config, and an admin applies it with an explicit Sync. The
repo becomes the source of truth for the declared fields. Manual-sync only;
no auto-apply on deploy, no multi-workload reconcile, no create/delete in v1.
Scope is deliberately source-aware and source_config-resident: dockerfile
declares port/healthcheck/deploy_strategy, static declares deploy_strategy.
The file never carries repo coords or secrets (those stay in the encrypted
DB), which keeps credentials out of the repo.
Backend:
- internal/gitops: Spec/ParseSpec (KnownFields rejects unknown keys), a
source-aware ApplyPlan/BuildPlan, MergeAndValidate (omitted-field-preserving
deep merge + validate-the-merged-result-then-commit — never a partial
config), declared-only Drift with normalization, and Fetch with
ok/no_file/fetch_failed/invalid statuses and token-redacted messages.
- staticsite: DownloadFile added to GitProvider + Gitea/GitHub/GitLab impls,
reusing each provider's SSRF-safe client; 64 KiB cap; ErrFileNotFound.
- store: 4 additive gitops_* columns + setters (disjoint from UpdateWorkload
so the edit-form save and a sync never clobber each other).
- api: GET /workloads/{id}/gitops (status + raw + live drift + managed_fields),
PUT /gitops (admin, enable/path, traversal-safe), POST /gitops/sync (admin,
per-workload locked read->merge->validate->write, audited to event_log).
Frontend:
- GitOpsPanel.svelte: status pill, a purpose-built field-level drift view,
.tinyforge.yml preview, enable ToggleSwitch, Sync via ConfirmDialog; all five
statuses handled, admin affordances gated on the real viewer role.
- GitOps-managed badge (list + detail hero) and a read-only edit-form banner.
- api.ts fetchers + types; i18n apps.detail.gitops.* (en + ru parity).
Built phase-by-phase with an adversarial plan review (caught 5 design flaws
pre-implementation) and an independent review per phase (go / security / ts /
final) — all APPROVE, 0 CRITICAL/HIGH. docs/gitops.md documents the schema and
what's intentionally out of v1. Plan: plans/gitops/.
116 lines
6.9 KiB
Markdown
116 lines
6.9 KiB
Markdown
# Tinyforge GitOps v1 — config-as-code for repo-backed workloads
|
|
|
|
**Status:** ✅ Complete (squash-merged to main 2026-06-21)
|
|
**Branch:** `feat/gitops-config-as-code`
|
|
**Mode:** Automated · Orchestrator (hybrid: backend built direct, Phase 3 via frontend implementer) · Incremental
|
|
**Started:** 2026-06-21
|
|
|
|
## Summary
|
|
|
|
A `dockerfile` or `static` workload can opt in to reading its **deploy config** from a
|
|
`.tinyforge.yml` file in its own repo. Tinyforge fetches the file, shows it, computes
|
|
**drift** vs the live config, and lets an admin **sync** (repo → live) with one explicit
|
|
action. The repo becomes the source of truth for the *declared* fields; the UI locks
|
|
those fields and renders a drift view.
|
|
|
|
### v1 scope (deliberate)
|
|
|
|
- **In:** opt-in per workload (dockerfile/static only); `.tinyforge.yml` declares only
|
|
**source_config-resident** fields (`port`, `healthcheck`, `deploy_strategy`,
|
|
`resources.{cpu_limit,memory_limit}`, `max_instances`); manual explicit sync;
|
|
declared-field drift view; GitOps-managed badge + read-only gate.
|
|
- **Out (documented future seams):** `env`/`faces` declaration (separate stores —
|
|
needs typed multi-target apply); auto-apply-on-deploy (must be a Source-plugin concern,
|
|
not a dispatch concern); multi-workload reconcile with create/delete (Framing B);
|
|
image/compose sources (not git-backed / overlapping config surface).
|
|
|
|
### `.tinyforge.yml` v1 schema
|
|
|
|
```yaml
|
|
version: 1
|
|
deploy:
|
|
port: 8080
|
|
healthcheck: /healthz
|
|
deploy_strategy: blue-green # "" | recreate | blue-green (validated per source)
|
|
resources: { cpu_limit: 0.5, memory_limit: 256 }
|
|
max_instances: 1
|
|
```
|
|
|
|
No repo location, no tokens, no secrets — those stay in the encrypted DB.
|
|
|
|
## Design constraints (from the adversarial review — non-negotiable)
|
|
|
|
- **C1** Overlay is a typed `ApplyPlan{SourceConfigPatch}` routed to `source_config` only.
|
|
env/faces are NOT in source_config (they live in `workload_env` / `public_faces`), so
|
|
they are cut from v1; the typed plan reserves their slots for later.
|
|
- **C2** No `env` in v1 → no secrets-in-repo hole.
|
|
- **C3** No auto-apply-on-deploy in v1 (SHA is resolved *inside* `src.Deploy`; image has
|
|
no repo). Future auto-apply lands as a Source-plugin concern.
|
|
- **C4** Sync is explicit-action only, with a hard gate:
|
|
parse → build overlay → **omitted-field-preserving** deep-merge onto a fresh copy of the
|
|
live source_config → run `Source.Validate` on the *merged* result → persist in one
|
|
transaction only if valid.
|
|
- **C5** Drift is computed **only over declared leaves**, post-normalization
|
|
(`deploy_strategy:"" == "recreate"`; YAML int vs JSON coercion). Omitted = unmanaged.
|
|
- Reuse `staticsite.NewGitProvider` (inherits SSRF defense); add a size-capped
|
|
`DownloadFile`. Route all fetch errors through the existing `sanitizeError(msg, token)`.
|
|
Distinct `no_file` status. Sync audit is NOT `deploy_history` (rollback assumes
|
|
deployable rows). Gate enable to `dockerfile|static`. Derive read-only fields from the
|
|
declared overlay leaves (no provenance column). 4 additive `gitops_*` columns only.
|
|
|
|
## Phases
|
|
|
|
| # | Title | Subplan | Status |
|
|
|---|-------|---------|--------|
|
|
| 1 | GitOps core (backend, no UI/mutation) | [phase-1-core.md](phase-1-core.md) | ✅ Done |
|
|
| 2 | Store + API (manual sync) | [phase-2-api.md](phase-2-api.md) | ✅ Done |
|
|
| 3 | Frontend experience (UI/UX showcase) | [phase-3-frontend.md](phase-3-frontend.md) | ✅ Done |
|
|
| 4 | Hardening + docs + final review | [phase-4-hardening.md](phase-4-hardening.md) | ✅ Done |
|
|
|
|
## Phase progress log
|
|
|
|
- **Phase 1 — Done (2026-06-21).** Migration (4 additive `gitops_*` columns) + `Workload`
|
|
read path. New `internal/gitops` package: `Spec`/`ParseSpec` (KnownFields rejects
|
|
unknown keys incl. env/faces attempts), source-aware `ApplyPlan`/`BuildPlan`
|
|
(dockerfile: port/healthcheck/deploy_strategy; static: deploy_strategy only — `resources`/
|
|
`max_instances` dropped after confirming they aren't on dockerfile/static configs),
|
|
`MergeAndValidate` (omitted-field-preserving + validate-then-commit), `Drift`
|
|
(declared-only, normalized), `Fetch` (no_file/fetch_failed/invalid statuses, token-redacted).
|
|
`DownloadFile` added to the `GitProvider` interface + 3 impls (64 KiB cap, ErrFileNotFound,
|
|
SSRF-safe client reused, GitHub raw media type). Independent go-review: **APPROVE**, no
|
|
CRITICAL/HIGH; M1 (GitLab doc comment) fixed; M2 (validate GitOpsPath at write) carried
|
|
into Phase 2. 28/28 packages green.
|
|
- **Phase 2 — Done (2026-06-21).** Store setters `SetWorkloadGitOps` / `RecordGitOpsSync`
|
|
(targeted column updates — disjoint from `UpdateWorkload`, so neither writer clobbers the
|
|
other). API: `GET /gitops` (single rich payload: status + raw + live drift + meta — folded
|
|
the separate `/drift` endpoint in to avoid a double fetch), `PUT /gitops` (admin,
|
|
enable/disable + path, rejects non-eligible source + traversal/URL-injection paths),
|
|
`POST /gitops/sync` (admin: fetch → MergeAndValidate → UpdateWorkload → RecordGitOpsSync →
|
|
event-log audit). Sync recorded to `event_log` (not `deploy_history` — review S6). Tests:
|
|
store round-trip + `validGitOpsPath` + `planFields`. Independent **security review:
|
|
clean, no CRITICAL/HIGH** (token never leaks, SSRF locked by safe dialer, authZ correct,
|
|
no field loss); LOW-1 (path query/fragment injection) hardened in `validGitOpsPath`. Full
|
|
backend suite green.
|
|
- **Phase 3 — Done (2026-06-21).** Built by a frontend implementation agent.
|
|
`GitOpsPanel.svelte` (self-fetching panel: status pill, purpose-built field-level drift
|
|
view — repo→live per declared field on the forge/ember palette, `.tinyforge.yml` preview,
|
|
enable `ToggleSwitch`, "Sync now" via `ConfirmDialog`, all five status states). api.ts
|
|
fetchers + `GitOpsStatus`/`GitOpsDriftEntry`; `gitops_*` on the `Workload` TS type;
|
|
GitOps-managed badge on the detail hero + apps list (payload already carries
|
|
`gitops_enabled`); read-only edit-form banner (banner-only — hard-disabling inputs would
|
|
need prop-threading through all 4 source forms; deferred). Backend `managed_fields` added
|
|
to `GET /gitops` for the gate. i18n `apps.detail.gitops.*` en+ru (parity 1804/1804).
|
|
Independent ts-review: one HIGH (`isAdmin` hardcoded true) + 2 MEDIUM — **all fixed**:
|
|
real role wired via `getCurrentUser()` (panel default now `false`), stale-guard on the
|
|
edit-open fetch, misleading `eligible` comment trimmed. check 0 errors · build · 26/26.
|
|
- **Phase 4 — Done (2026-06-21).** Concurrent-sync guard (review S5): a per-workload
|
|
`keyedMutex` on `Server`; `syncWorkloadGitOps` locks by id and loads the row inside the
|
|
lock, serializing the read→merge→write so two syncs can't race. Docs: `docs/gitops.md`
|
|
(enable flow, v1 schema, drift/sync semantics, explicit "not in v1": env/faces, auto-apply,
|
|
multi-workload, image/compose). Backend green. Final comprehensive review + merge gate
|
|
next.
|
|
|
|
## Amendment log
|
|
|
|
_(plan changes require approval + an entry here)_
|