devantler-tech / devantler-tech/ksail
Spike: decide the platform capability-slot schema, preset composition, and the GitOps override contract
- Dominant language
- Go
- Stars
- 165
- Forks
- 12
- Avg merge
- 5h 51m
- Merged PRs (30d)
- 347
Description
> 🤖 Generated by the Agentic Engineer
Part of #6875.
## Why this is first
Everything else in #6875 depends on three unsettled decisions. Building a single production component
before they are made would bake the wrong shape into the schema and the rendering path, and the cost
of changing them later is a breaking config migration.
## The questions this spike must answer
1. **Where do platform slots live in the schema.** Extend `spec.cluster` (which already holds `cni`,
`csi`, `policyEngine`, `gitOpsEngine`, `certManager`, `oidc`, `sops`, `autoscaler`,
`metricsServer`, `loadBalancer`, `imageVerification`, `localRegistry`, `cdi`, `nodeAutoscaling`),
or introduce a sibling `spec.platform`? The existing 14 slots are cluster-infrastructure concerns;
the new ones are platform/day-2 concerns, and some are arguably neither. Decide the boundary and
whether any existing slot moves.
2. **What a slot *is*, precisely.** A slot needs: an enum of supported implementations plus `None`, a
default, version pinning, a place for implementation-specific settings, and a declared dependency
relationship to other slots (secrets management needs a store before an operator; progressive
delivery needs a service mesh or ingress). Settle that contract once.
3. **How presets compose slots.** Maintainer direction is *slots as the substrate, granular presets on
top*. Decide preset composition semantics: what a preset sets, how a user overrides one slot of a
preset without abandoning it, whether presets nest or compose, and how a preset is versioned so an
upgrade is reviewable rather than silent.
4. **The GitOps override and extension contract — the hard one.** #6875 makes it non-negotiable that
every KSail-managed component and configuration stays overridable and extensible via GitOps, while
the built-in path requires no hand-written GitOps config. Those pull in opposite directions.
Decide: where KSail-rendered output lands, how a user's own manifests layer over it, what happens
to an override on the next reconcile, and how a user takes full ownership of a component without
forking everything. **State the precedence rules explicitly.**
5. **What "built into the code" means for content.** Whether components are rendered from embedded
templates, vendored chart references, or generated Flux/Argo resources — and how component versions
are pinned and upgraded without an external source being required at provision time.
## Explicit non-goals
Choosing which components fill which slots. That is the inventory work, and it is a separate child so
this spike stays a schema-and-contract decision rather than a catalogue argument.
## Definition of done
Per the portfolio's Spike type: **a recorded decision plus follow-up issues, not a PR.**
- [ ] An ADR under `docs/adr/` recording the decisions above with their alternatives and trade-offs.
- [ ] The precedence rules for GitOps override written out concretely enough to test against.
- [ ] A worked example: one existing slot and one new slot expressed in the decided schema.
- [ ] Follow-up issues filed for each implementation stream the decision implies, linked to #6875.
- [ ] Any decision that contradicts an existing ADR names it and says why.
## Size
Medium. Timeboxed — the output is a decision, and an unresolved question is recorded as a follow-up
rather than blocking the whole spike.
Contributor guide
Research direction
Start by reading #6875 and the existing ADRs under docs/adr/ to identify current constraints and any conflicting decisions. Work through the five questions and record alternatives, trade-offs, explicit GitOps precedence rules, and worked slot examples in a new ADR. Finish by filing linked follow-up issues for each implementation stream.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- 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