overlays

docs/REFERENCE.md

@@ -148,12 +148,30 @@ launchpad/
 │       └── auth-sidecar-injector.yaml
 │
 ├── secrets/                       # Application secrets (sealed)
-│   ├── argocd-mcp-credentials.yaml
-│   ├── dot-ai-secrets.yaml
-│   ├── gitea-credentials-sealed.yaml
-│   ├── gitea-runner-token-sealed.yaml
-│   ├── mcp10x-credentials-sealed.yaml
-│   └── musicman-credentials.yaml
+│   ├── base/                     # All SealedSecrets (shared across clouds)
+│   │   ├── kustomization.yaml
+│   │   ├── argocd-forte-helm-secret-sealed.yaml
+│   │   ├── argocd-mcp-credentials.yaml
+│   │   ├── argocdmcp-auth-oidc-sealed.yaml
+│   │   ├── dot-ai-secrets.yaml
+│   │   ├── forte10x-app-credentials-sealed.yaml
+│   │   ├── gitea-backup-s3-sealed.yaml
+│   │   ├── gitea-credentials-sealed.yaml
+│   │   ├── gitea-runner-token-sealed.yaml
+│   │   ├── gitea-smtp-secret-sealed.yaml
+│   │   ├── keycloak-credentials-sealed.yaml
+│   │   ├── musicman-auth-oidc-sealed.yaml
+│   │   ├── musicman-credentials.yaml
+│   │   └── renovate-env-sealed.yaml
+│   └── overlays/                 # Per-cloud overlays (reference base)
+│       ├── aks-dev/kustomization.yaml
+│       ├── aks-prod/kustomization.yaml
+│       ├── eks-dev/kustomization.yaml
+│       ├── eks-prod/kustomization.yaml
+│       ├── gke-dev/kustomization.yaml
+│       ├── gke-prod/kustomization.yaml
+│       ├── upc-dev/kustomization.yaml
+│       └── upc-prod/kustomization.yaml
 │
 ├── scripts/                       # Operational helper scripts
 │   ├── gitea-backup.sh            # S3 backup helper (list/download)
@@ -706,6 +724,10 @@ spec:
 **Chart**: `sealed-secrets/sealed-secrets-controller`
 **Namespace**: `kube-system`
 
+**Directory Structure**: `secrets/base/` contains all SealedSecrets with a `kustomization.yaml`. Per-cloud overlays in `secrets/overlays/<cloud>/` reference the base via Kustomize. The ArgoCD `secrets` Application points to the active overlay (e.g., `secrets/overlays/upc-dev`), and `infra/overlays/upc-prod` patches the path to `secrets/overlays/upc-prod`.
+
+To add cloud-specific secrets, create a new SealedSecret in the overlay directory and add it to the overlay's `kustomization.yaml`.
+
 **Public Certificate**:
 ```bash
 kubeseal --fetch-cert \
@@ -1734,8 +1756,9 @@ To add support for a new cloud (e.g., `oci-dev` for Oracle Cloud):
    - `opencost-values.yaml` — pricing model or cloud billing integration
 3. **Kustomize overlay**: `infra/overlays/oci-dev/kustomization.yaml` — patch `valueFiles[1]` for each Application
 4. **App-of-apps**: `_app-of-apps-oci-dev.yaml` — points to `infra/overlays/oci-dev`
-5. **Sealed Secrets**: `secrets/oci-dev/` — TLS certs, credentials, backup S3 config
-6. **Bootstrap**: `./bootstrap.sh oci-dev`
+5. **Secrets overlay**: `secrets/overlays/oci-dev/kustomization.yaml` — references `../../base`, add cloud-specific SealedSecrets if needed
+6. **Secrets patch**: Add patch to `infra/overlays/oci-dev/kustomization.yaml` to swap secrets path to `secrets/overlays/oci-dev`
+7. **Bootstrap**: `./bootstrap.sh oci-dev`
 
 ---