infra-kubernetes

Imported from sca-templates/infra-kubernetes (AGENTS.md). Install upstream with npx skills add sca-templates/infra-kubernetes. Copyright stays with the author.

infra-kubernetes — Platform Guide

GitOps source of truth for the sca infrastructure platform on Kubernetes. ArgoCD reconciles this repository: nothing is deployed by hand — every change lands through git. The Docker Compose sibling repositories (sca-templates/infra-*) remain the local-dev counterpart only, outside this repo.

1. What this repo is

• Single source of truth for the platform components: environments, secret projections. Services do not live here — each service owns its deploy/ in its own repo (app-repo-as-source, docs/onboarding-new-service.md).
• ArgoCD app-of-apps: one root Application per environment renders two ApplicationSets — apps-<env>.yaml (platform catalog) and services-<env>.yaml (services registry; present for dev/qa/prod only, never local).
• A clean restart of the previous infra-kubernetes (which churned in fix commits): a human-reviewed gate per logical change, rollback over forward-fix.
• A template: it must be clonable standalone. Zero references to local paths outside the repo; sibling knowledge is always an external link.

Knowledge base: this guide is the rules of engagement; the file-accurate documentation set lives in docs/ (start at docs/INDEX.md). From Phase 1 onward the docs are the source of truth: phase prompts read them first, execute against their gates, and update status.md / architecture.md as components land. Prefer the docs over recollection.

2. Environment model

local is a platform-only sandbox (kind): the full catalog for iteration and CI smoke, but no services. Services deploy from dev upward: dev/qa promoted by syncing the ArgoCD Application of their own repo from the service promote workflow, prod by bumping the version tag pin in the services registry (chore(services) PR = go/no-go).

Sync policies follow ADR-003. Platform-component promotion is gated by the promote-test; services promote by ArgoCD app syncs (dev/qa) and a verified version bump (prod), and a service PR to its main only happens after dev and qa (docs/workflow.md).

3. Component catalog

17 components + ArgoCD. Status column is the source of truth (planned (Phase N) until the phase lands; deployed from then on). Chart and image pins are set inside each phase and live under infrastructure/<component>/ + envs/<env>/.

Intentional exclusions (per the restart plan): no Consul in-cluster (ADR-001; native DNS + Linkerd replace it), no Unleash, no KafkaConnect/Debezium, no kafka-ui, no linkerd-viz in-cluster. No latest tags; this repo builds nothing. Services are not part of this catalog — each service owns its deploy/ and is registered in argocd/services-<env>.yaml (docs/onboarding-new-service.md).

4. Dependency order (sync-waves)

ArgoCD sync-wave annotations, integers spaced ≥10 apart. Operators/CRDs before CRs; Vault before ESO syncs; datastores before consumers.

The normative map with rationale lives in docs/architecture.md.

5. Image policy (strict)

Infrastructure uses official upstream images pinned by version. This repo builds nothing. No floating tags, no latest, ever — enforced by the CI pin guards (docs/security.md).

6. Commands

The Makefile is a thin wrapper: after bootstrap, deployments happen exclusively via git push → ArgoCD.

OS support: Linux (any distro) and macOS for the toolchain; Windows is only supported via WSL2 (this platform is POSIX — no native Windows shell support; sca fails fast with a pointer to WSL2).

7. Conventions (strict)

• English only: content, commits, PR descriptions.
• Conventional commits: feat(platform): …, feat(vault): …, docs(readme): ….
• Changes land via reviewed PRs. A component often ships as a single PR, but the number of PRs and commits is a judgment call driven by the change — the work is dynamic and grouping is not a rule. A blocked change rolls back rather than being patched forward with fix chains; nothing is deployed by hand after make bootstrap.
• Changes land through PRs (initial population excepted, straight to main).
• Git writes are the user's: do not git commit/git push/reset/amend or stage anything on your own. Draft commits/messages only; ask before any git mutation. The user commits and pushes.
• Never commit .env, .secrets/, kubeconfigs, unseal keys, tokens, dumps. Vault is the secrets SSOT; .secrets/ lives only on disk.
• Shared values changed must be mirrored across all envs/<env>/<c>.yaml.
• Respect sync-waves: a new component gets a wave ≥10 apart from its dependencies.
• From Phase 1, the commit that lands a component also updates docs/roadmap.md (Work Log row) and docs/architecture.md (Status, deviations log) / docs/status.md. Docs are updated as components land. The roadmap is tracked on the GitHub Projects board, Milestones and Issues and linked from docs/roadmap.md.
• Consult the sca-docs notes below before touching topology, ports or networks.

8. Documentation to consult (always)

Fetch from the sca-docs vault (raw URLs, no local checkout assumed):

• 00-ecosystem/platform-overview.md — ecosystem vision
• 00-ecosystem/conventions.md — naming, links, catalogs
• 06-decisions/adr-001 … adr-007 — locked architecture decisions (ADR-001 no in-cluster Consul, ADR-003 sync policies)
• 04-infrastructure/<component>.md — per-component canonical notes

Base URL: https://raw.githubusercontent.com/sca-templates/sca-docs/main/<path>

9. Troubleshooting quick refs

Full runbooks live in docs/workflow.md.

CodeGraph

In repositories indexed by CodeGraph (a .codegraph/ directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:

• MCP tool (when available): codegraph_explore answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.
• Shell (always works): codegraph explore "<symbol names or question>" prints the same output.

If there is no .codegraph/ directory, skip CodeGraph entirely — indexing is the user's decision.