project-infra/k8s/README.md

Kubernetes Packaging

This tree is organized for many independently owned workloads.

Entry points:

• overlays/<env>/ renders the whole environment skeleton.
• overlays/<env>/<domain>/ renders one namespace/domain boundary.
• overlays/<env>/managing/vault-secrets-operator/ is applied after the VSO CRDs are installed.
• scripts/env/ contains environment bootstrap and teardown orchestration.
• scripts/ contains imperative bootstrap and break-glass operations only.
• vso/ contains Vault Secrets Operator installation lifecycle files.

Scale rules:

• Do not place hundreds of workloads directly under one package.
• Add workloads under base/app/units/<unit>/<domain>/<workload-kind>/<workload>/.
• Add matching environment overrides under overlays/<env>/app/units/<unit>/<domain>/<workload-kind>/<workload>/ only when that workload has environment-specific differences.
• A workload package owns its Kubernetes object files together, such as deployment.yaml, service.yaml, configmap.yaml, cronjob.yaml, statefulset.yaml, or pvc.yaml.
• Do not create kind-based package roots such as deployments/, services/, or configmaps/.

Example for a 1000-workload organization:

base/app/units/
├── commerce/
│   ├── checkout/
│   │   ├── services/order-api/
│   │   ├── services/payment-api/
│   │   ├── workers/payment-settlement-worker/
│   │   ├── schedulers/cart-expiry-scheduler/
│   │   └── stateful/orders-postgres/
│   └── catalog/
│       ├── services/catalog-api/
│       ├── workers/search-index-worker/
│       └── jobs/catalog-backfill-job/
├── identity/
│   ├── auth/
│   │   ├── services/auth-api/
│   │   ├── services/token-api/
│   │   └── schedulers/token-cleanup-scheduler/
│   └── profile/
│       ├── services/profile-api/
│       └── workers/profile-event-worker/
├── media/
│   ├── playback/
│   │   ├── services/playback-api/
│   │   └── workers/session-event-worker/
│   └── recommendation/
│       ├── services/recommendation-api/
│       ├── workers/model-feature-worker/
│       └── jobs/model-refresh-job/
└── data/
    ├── ingestion/
    │   ├── workers/event-ingest-worker/
    │   └── stateful/ingest-kafka/
    └── analytics/
        ├── schedulers/daily-report-scheduler/
        └── jobs/monthly-rollup-job/