Setup artifacts layout

Synced from lytebase-infra/setup/README.md. Run pnpm sync:docs to refresh this snapshot.

Setup artifacts layout (multi-runtime test harness)

setup/ is treated as a repository-local test harness and reference fixture.

It is intentionally kept as:

1. A canonical fixture for integration testing.
2. A reference implementation of the project contract layout.
3. A safe place to exercise k3s/swarm and none/flux workflows.

It is not a hard engine dependency. The control-plane and CLI operate on any artifact repository that provides:

1. project.yaml.
2. A valid spec.setupRoot tree.
3. The required contract paths and schemas.

The API/CLI input of truth remains repo_path + project.yaml, not this repository’s setup/ path.

Layout

setup/
  schema/
    cluster-config.schema.json
    platform-input.schema.json
  catalog/
    runtime/
      k3s/
        infra/terraform/
        bootstrap/ansible/
        platform/
          base-manifests/
          addons/
        gitops/flux/
          bootstrap/
          clusters/
          components/{base,addons,platform,apps}/
      swarm/
        bootstrap/
        compose/{base,addons,apps}/
    charts/
      lytebase/
      shared-subcharts/
    extensions/
      k8s/
      swarm/
      shared/
  environments/
    .sops.yaml
    schema/
      secrets.schema.json
      runtime-values.schema.json
    defaults/
      values/{k3s.yaml,swarm.yaml,terraform.defaults.tfvars}
      templates/
    dev|staging|prod|ci/
      cluster.yaml
      runtime/
        k3s/
          config.yaml
          values/
          flux/{overlays,releases}/
        swarm/
          config.yaml
          compose/{overrides,stacks}/
      secrets/sops/
  ops/
    bootstrap/
    deploy/
    validate/
    destroy/
  scripts/
    runbooks/

Runtime naming

Runtime keys are k3s and swarm.

FluxCD compatibility

k3s GitOps is isolated to catalog/runtime/k3s/gitops/flux/ and environment overlays under:

• environments/<env>/runtime/k3s/flux/overlays/
• environments/<env>/runtime/k3s/flux/releases/

Swarm paths are fully separate and do not depend on Flux artifacts.

Runtime-state location

Generated outputs are not stored in setup/. Treat them as controller- or execution-generated artifacts outside the committed bundle, not as fixed checked-in paths.

Secrets policy

• Encryption standard: sops + age
• Only encrypted secret files (*.enc.yaml) are committed.
• Plaintext secrets are ignored.

SOPS rules live in setup/environments/.sops.yaml.

Ops ownership

• ops/ is for human runbooks and break-glass procedures.
• Primary automation ownership remains in lytebase-cli commands.

Harness guardrails

1. Keep fixtures deterministic and reviewable.
2. Do not couple control-plane services to a repository-local setup/ absolute path.
3. Validate both:
   • this setup/ harness fixture, and
   • external repos with custom setupRoot values.