devantler-tech / devantler-tech/ksail

Spike: decide the platform capability-slot schema, preset composition, and the GitOps override contract

Open
#6,876 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.