gudo11y · beengud · Oct 7, 2025 · Oct 7, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -52,6 +52,35 @@ done
 tk show tanka/environments/mop-edge | kubectl apply --dry-run=client -f -
 ```
 
+### External Secrets Operator (ESO)
+```bash
+# Check ESO deployment status
+kubectl get pods -n mop -l app.kubernetes.io/name=external-secrets
+
+# View installed CRDs
+kubectl get crds | grep external-secrets
+
+# List SecretStores
+kubectl get secretstores -n mop
+kubectl get clustersecretstores
+
+# List ExternalSecrets and their sync status
+kubectl get externalsecrets -n mop
+kubectl describe externalsecret <name> -n mop
+
+# Check if secrets were created successfully
+kubectl get secrets -n mop
+
+# View ESO logs for troubleshooting
+kubectl logs -n mop -l app.kubernetes.io/name=external-secrets --tail=100
+
+# Apply example SecretStore
+kubectl apply -f <(tk show . <<< 'import "examples/eso-secretstore.jsonnet"' | yq 'select(.kind == "SecretStore")')
+
+# Apply example ExternalSecret
+kubectl apply -f <(tk show . <<< 'import "examples/eso-externalsecret.jsonnet"' | yq 'select(.kind == "ExternalSecret")')
+```
+
 ## Architecture and Structure
 
 ### Core Technologies
@@ -61,7 +90,7 @@ tk show tanka/environments/mop-edge | kubectl apply --dry-run=client -f -
 - **Kubernetes**: Deployment platform (configured for minikube context)
 
 ### Observability Stack Components
-The platform deploys: Prometheus, Grafana, Loki, Mimir, Tempo, Alloy/Alloy Operator, and optionally Backstage.
+The platform deploys: Prometheus, Grafana, Loki, Mimir, Tempo, Alloy/Alloy Operator, External Secrets Operator, and optionally Backstage.
 
 ### Three-Tier Environment Model
 - **mop-central**: Central management environment
@@ -78,8 +107,13 @@ Each environment is a separate Tanka environment with its own:
 tanka/
 ├── lib/                     # Shared Jsonnet libraries
 │   ├── common.libsonnet     # Common configurations and defaults
+│   ├── eso.libsonnet       # External Secrets Operator helpers
 │   ├── k.libsonnet         # Kubernetes utilities
 │   └── utils.libsonnet     # Utility functions
+├── examples/               # Example configurations and patterns
+│   ├── eso-secretstore.jsonnet       # SecretStore examples
+│   ├── eso-externalsecret.jsonnet    # ExternalSecret examples
+│   └── eso-backstage-migration.jsonnet # Backstage ESO migration
 ├── environments/           # Environment-specific configurations
 └── vendor/                # Vendored Jsonnet dependencies
 ```
@@ -101,4 +135,156 @@ tanka/
 - Environment-specific values are parameterized in `main.jsonnet`
 - Common configurations are abstracted in `tanka/lib/common.libsonnet`
 - Kubernetes utilities are available via `tanka/lib/k.libsonnet`
-- All environments target minikube context by default
+- All environments target minikube context by default
+
+## Secret Management with External Secrets Operator
+
+### ESO Architecture
+External Secrets Operator (ESO) syncs secrets from external secret management systems (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Kubernetes Secrets, etc.) into Kubernetes Secrets.
+
+**Key Components:**
+- **SecretStore**: Namespace-scoped configuration for secret backend
+- **ClusterSecretStore**: Cluster-scoped configuration for secret backend (recommended for production)
+- **ExternalSecret**: Defines which secrets to sync and how to map them
+
+### Using ESO Library (tanka/lib/eso.libsonnet)
+
+The ESO library provides helpers for common secret patterns:
+
+```jsonnet
+local eso = import 'eso.libsonnet';
+
+{
+  // Create a SecretStore for Kubernetes backend (dev/testing)
+  secretStore: eso.secretStore.new('kubernetes-backend', namespace='mop'),
+
+  // Create a ClusterSecretStore for AWS Secrets Manager
+  awsStore: eso.clusterSecretStore.awsSecretsManager(
+    name='aws-backend',
+    region='us-east-1',
+    role='arn:aws:iam::123456789012:role/external-secrets'
+  ),
+
+  // Create an API token secret
+  apiToken: eso.patterns.apiTokenSecret(
+    name='my-api-token',
+    namespace='mop',
+    secretStore='kubernetes-backend',
+    tokenKey='source-secret-name'
+  ),
+
+  // Create database credentials
+  dbCreds: eso.patterns.databaseSecret(
+    name='postgres-creds',
+    namespace='mop',
+    secretStore='kubernetes-backend',
+    dbSecretKey='postgres-config'
+  ),
+}
+```
+
+### Backend Configurations
+
+**Kubernetes Backend (Development):**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  store: eso.secretStore.new('kubernetes-backend', 'mop'),
+}
+```
+
+**AWS Secrets Manager:**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  store: eso.clusterSecretStore.awsSecretsManager(
+    name='aws-backend',
+    region='us-east-1',
+    role='arn:aws:iam::ACCOUNT:role/external-secrets'
+  ),
+}
+```
+
+**GCP Secret Manager:**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  store: eso.clusterSecretStore.gcpSecretManager(
+    name='gcp-backend',
+    projectID='my-project'
+  ),
+}
+```
+
+**HashiCorp Vault:**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  store: eso.clusterSecretStore.vault(
+    name='vault-backend',
+    server='https://vault.example.com:8200',
+    path='secret'
+  ),
+}
+```
+
+### Creating ExternalSecrets
+
+**Simple pattern:**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  secret: eso.externalSecret.new(
+    name='my-secret',
+    namespace='mop',
+    secretStore='kubernetes-backend',
+    refreshInterval='1h'
+  ) + eso.externalSecret.withData('key', 'remote-secret-name'),
+}
+```
+
+**With property selection (for JSON secrets):**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  secret: eso.externalSecret.new(
+    name='my-secret',
+    namespace='mop',
+    secretStore='kubernetes-backend'
+  ) + eso.externalSecret.withDataProperty('password', 'db-config', 'password'),
+}
+```
+
+**Using ClusterSecretStore:**
+```jsonnet
+local eso = import 'eso.libsonnet';
+{
+  secret: eso.externalSecret.new(
+    name='my-secret',
+    namespace='mop',
+    secretStore='aws-backend'
+  ) + eso.externalSecret.withClusterSecretStore('aws-backend')
+    + eso.externalSecret.withData('token', '/prod/api/token'),
+}
+```
+
+### Examples
+
+See `tanka/examples/` for comprehensive examples:
+- `eso-secretstore.jsonnet`: SecretStore and ClusterSecretStore examples for all backends
+- `eso-externalsecret.jsonnet`: ExternalSecret patterns (API tokens, database creds, TLS certs)
+- `eso-backstage-migration.jsonnet`: Real-world migration example for Backstage secrets
+- `README.md`: Detailed usage guide with troubleshooting
+
+### Migration Pattern
+
+To migrate existing hardcoded secrets to ESO:
+
+1. Create source secrets in your backend
+2. Create a SecretStore/ClusterSecretStore
+3. Create ExternalSecrets to sync from backend
+4. Update application manifests to reference ESO-managed secrets
+5. Verify secrets are syncing correctly
+6. Remove hardcoded secrets
+
+See `tanka/examples/eso-backstage-migration.jsonnet` for a complete example.