/secrets

name: secrets
description: Secrets strategy, External Secrets Operator scaffolding, Sealed Secrets seal/rotate/backup, rotation runbooks, and Kubernetes-side secrets audit.
argument-hint: "[design|eso|sealed|rotate|audit] [namespace or manifest path]"
title: "Secrets Command"
sidebar_label: "secrets"
custom_edit_url: null

Secrets Command

Structured guidance for secrets strategy, External Secrets Operator, Sealed Secrets, rotation, and Kubernetes-side secrets audit.

Activation

/platform-skills:secrets design   # ESO vs Sealed Secrets decision; choose a strategy for the cluster
/platform-skills:secrets eso      # ExternalSecret/SecretStore scaffold; debug sync errors
/platform-skills:secrets sealed   # seal, rotate, backup master key; troubleshoot decryption failures
/platform-skills:secrets rotate   # rotation runbook — update provider value, force sync, verify pods reload
/platform-skills:secrets audit    # find bad SA tokens, unhealthy ExternalSecrets, missing secrets

---

Interactive Wizard (fires when no mode is provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. design   — choose ESO vs Sealed Secrets for a cluster or workload
  2. eso      — scaffold ExternalSecret/SecretStore, or debug a sync error
  3. sealed   — seal a new secret, rotate an existing one, or back up the master key
  4. rotate   — end-to-end rotation runbook for a live secret
  5. audit    — find service account token secrets, unhealthy ExternalSecrets, plain secrets in Git

Enter 1–5 or mode name:

**Q2 — Context** (after mode selected):

• **design**: `What is the backend — AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or no cloud provider?`
• **eso**: `Paste the ExternalSecret or SecretStore YAML, or describe the sync error.`
• **sealed**: `New secret or rotating an existing one? Which namespace?`
• **rotate**: `Which secret is rotating — database password, API key, TLS cert? Which backend?`
• **audit**: `Cluster name and namespace scope. Any specific concern — Git scan, SA tokens, ESO health?`

---

Mode: design

**Triggers:** which pattern, ESO vs Sealed Secrets, choose secrets strategy, what should I use

Read `references/secrets.md` before responding.

Decision matrix

| Pattern | Best for | Tradeoff | |---|---|---| | External Secrets Operator (ESO) | Cloud-native backends: AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault | Runtime dependency on provider; requires workload identity or static credentials | | Sealed Secrets | Air-gapped or GitOps-first teams; no external runtime dependency | Rotation requires re-sealing and a Git commit; master key backup is critical |

**Pick ESO when:**

• Cluster has workload identity (IRSA on EKS, Azure Workload Identity on AKS, Vault Kubernetes auth)
• Rotation should propagate automatically without a Git commit
• Secrets are managed centrally in a provider (team already uses AWS SM / Azure KV / Vault)

**Pick Sealed Secrets when:**

• No cloud provider or Vault
• Air-gapped environment
• Team prefers all cluster state — including encrypted secrets — reviewable in Git without a runtime backend

**Handoffs:**

• For filesystem or Git history scanning for leaked secrets → `/platform-skills:trivy` (`--scanners secret`)
• For Azure Key Vault identity setup → `/platform-skills:azure identity`
• For AWS IRSA setup → `/platform-skills:aws`

---

Mode: eso

**Triggers:** ExternalSecret, SecretStore, ClusterSecretStore, sync error, ESO, external secrets operator, SecretSyncError

Read `references/secrets.md` → External Secrets Operator section before responding.

> **Before generating commands, confirm:** > - ESO namespace — common values: `external-secrets`, `platform-system`, `kube-system`. Discover with: `kubectl get pods -A | grep external-secrets` > - ESO deploy name — common values: `external-secrets`, `external-secrets-controller`. Discover with: `kubectl get deploy -n <eso-namespace>` > - ESO service account name — the SA annotated with IRSA or Workload Identity. Common: `external-secrets-sa`, but teams name it differently. > > Substitute these into all namespace flags, `kubectl logs`, and `serviceAccountRef` fields below.

ExternalSecret scaffold (provider-agnostic)

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
  namespace: app-team
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: my-secret-store
    kind: SecretStore
  target:
    name: database-credentials
    creationPolicy: Owner
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: prod/app-team/db
        property: password

SecretStore — provider examples

**AWS Secrets Manager (IRSA):**

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: my-secret-store
  namespace: app-team
spec:
  provider:
    aws:
      service: SecretsManager
      region: eu-north-1
      auth:
        jwt:
          serviceAccountRef:
            name: external-secrets-sa

Required IAM (least privilege):

{
  "Effect": "Allow",
  "Action": "secretsmanager:GetSecretValue",
  "Resource": "arn:aws:secretsmanager:<region>:<account>:secret:prod/app-team/*"
}

**Azure Key Vault (Workload Identity):**

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: my-secret-store
  namespace: app-team
spec:
  provider:
    azurekv:
      authType: WorkloadIdentity
      vaultUrl: "https://my-keyvault.vault.azure.net"
      serviceAccountRef:
        name: external-secrets-sa

The managed identity needs `Key Vault Secrets User` on the Key Vault.

**HashiCorp Vault (Kubernetes auth):**

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: my-secret-store
  namespace: app-team
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      path: "secret"
      version: "v2"
      auth:
        kubernetes: