agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/sealed-secrets/SKILL.md

sealed-secrets

Skill4 starsChanged 5 months agoMITView on GitHub

Use when working with Sealed Secrets — encrypting Kubernetes Secrets for safe Git storage. Covers SealedSecret CRD, kubeseal, key management, encryption flow, Helm values, controller config, key rotation.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every keyrenewperiod → new key generated, added to registry

    line 134
  2. Very specific:

    Cluster-wide: Use --scope cluster-wide with kubeseal to allow any namespace

    line 192
  3. Distinctive:

    Compromised key: re-encryption is not enough: If a sealing key leaked, assume all secrets encrypted with that key are compromised.

    line 218
  4. Very specific:

    skipRecreate: false (default): When a managed Secret is deleted, the controller recreates it.

    line 219

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Sealed Secrets

Overview

Sealed Secrets provides one-way encryption for Kubernetes Secrets. A SealedSecret custom resource can be safely stored in public Git repos. Only the controller running in the target cluster can decrypt it, recovering the original Secret.

CRD: SealedSecret (bitnami.com/v1alpha1).

Latest: chart 2.18.5, controller v0.36.6 (Apr 2026).

Architecture

Developer workstation:
  kubeseal --fetch-cert         ← fetches controller's public key
    → creates SealedSecret YAML   ← encrypts Secret data with public key
      → committed to Git

Cluster controller:
  watches SealedSecret resources
    → decrypts using private key
      → creates/reconciled K8s Secret

CRD: SealedSecret

apiVersion: bitnami.com/v1alpha1, kind: SealedSecret

apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: mysecret
  namespace: myapp
spec:
  encryptedData:
    password: AgBy7x...base64-encrypted...
  template:
    metadata:
      labels:
        app: myapp
    type: Opaque   # or kubernetes.io/dockerconfigjson, etc.

Key fields:

FieldDescription
spec.encryptedDataMap of key → encrypted value (the sealed ciphertext)
spec.template.metadataLabels/annotations applied to the decrypted Secret
spec.template.typeSecret type (Opaque, kubernetes.io/dockerconfigjson, etc.)
spec.template.dataUnencrypted key-value pairs merged into the output Secret

The namespace in metadata.namespace is binding — the controller will only create the Secret in the same namespace as the SealedSecret.

kubeseal CLI

Install

# Linux amd64
wget https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.36.6/kubeseal-0.36.6-linux-amd64.tar.gz
tar xzf kubeseal-*-linux-amd64.tar.gz
sudo install kubeseal /usr/local/bin/

Common Operations

# Fetch the public certificate (for offline sealing)
kubeseal --fetch-cert \
  --controller-name=sealed-secrets-controller \
  --controller-namespace=kube-system \
  > pub-cert.pem

# Seal a Secret from stdin
kubectl create secret generic mysecret \
  --dry-run=client -o yaml \
  --from-literal=password=my-value \
  | kubeseal \
    --controller-name=sealed-secrets-controller \
    --controller-namespace=kube-system \
    --format=yaml \
  > mysealedsecret.yaml

# Seal offline (no cluster access needed)
kubectl create secret generic mysecret \
  --dry-run=client -o yaml \
  --from-literal=password=my-value \
  | kubeseal \
    --cert=pub-cert.pem \
    --format=yaml \
  > mysealedsecret.yaml

# Re-encrypt existing SealedSecret with latest key
kubeseal --re-encrypt \
  --controller-name=sealed-secrets-controller \
  --controller-namespace=kube-system \
  < mysealedsecret.yaml \
  > mysealedsecret-reencrypted.yaml

# Validate a SealedSecret
kubeseal --validate \
  --controller-name=sealed-secrets-controller \
  --controller-namespace=kube-system \
  < mysealedsecret.yaml

# Merge with existing Secret (update individual keys)
# Create new SealedSecret with only the changed key, controller patches it

Controller Configuration

Key Management

Sealed Secrets controller maintains a key registry of RSA key pairs (4096-bit):

controller:
  keyrenewperiod: "30d"    # Generate new key every 30 days
  # keyttl: "10y"          # Certificate validity (default 10 years)
  # keycutofftime: ""      # Force key generation at specific time (RFC1123)

Keys are stored as Kubernetes Secrets named sealed-secrets-key in the controller namespace, with labels sealedsecrets.bitnami.com/key=(active|compromised).

Key lifecycle:

  1. Initial install → controller generates first key pair
  2. Every keyrenewperiod → new key generated, added to registry
  3. Old keys retained → existing SealedSecrets remain decryptable
  4. --key-cutoff-time → force immediate key generation (early renewal)
  5. Key never deleted automatically — manual cleanup via kubeseal --re-encrypt

Namespace Scope

controller:
  additionalNamespaces: []

By default, the controller only watches the namespace it's installed in. additionalNamespaces extends watch scope. To watch all namespaces, set global.namespace: "".

Security Context

controller:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1001
    runAsGroup: 1001
    allowPrivilegeEscalation: false
    capabilities:
      drop: [ALL]
  podSecurityContext:
    fsGroup: 1001
    seccompProfile:
      type: RuntimeDefault

Logging & Metrics

controller:
  logInfoStdout: true
  logLevel: INFO
  logFormat: text        # or json
  metrics:
    enabled: true
    serviceMonitor:
      enabled: false      # Deployed uses pod annotations instead
    podAnnotations:
      prometheus.io/scrape: "true"
      prometheus.io/port: "8080"
      prometheus.io/path: "/metrics"

Encryption Flow

  1. Developer creates Secret YAML locally (dry-run)
  2. kubeseal encrypts each value in data/stringData with the controller's public key
  3. SealedSecret YAML is committed to Git (safe — only public key can encrypt)
  4. Controller detects SealedSecret → decrypts with private key → creates K8s Secret
  5. Secret is reconciled — if deleted, controller recreates it from SealedSecret

The encryption scope is bound to:

  • Namespace (default): SealedSecret only decrypts in the same namespace
  • Cluster-wide: Use --scope cluster-wide with kubeseal to allow any namespace
  • Strict: Namespace + name must match exactly

Helm Values

ValueDefaultDescription
global.namespace—Controller namespace
controller.image.taglatestController image version
controller.keyrenewperiod""Key renewal interval
controller.logLevelINFOLog level
controller.additionalNamespaces[]Extra namespaces to watch
controller.createtrueCreate controller deployment
secretNamesealed-secrets-keyExisting TLS secret for key
service.typeClusterIPService type
service.port8080Service port
networkPolicy.createfalseNetwork policy
crds.createtrueInstall SealedSecret CRD
rbac.createtrueRBAC resources

Common Mistakes

  • Controller not in expected namespace. kubeseal defaults to kube-system and controller name sealed-secrets-controller. If installed with a different name/namespace, pass --controller-name and --controller-namespace.
  • SealedSecret in wrong namespace = won't decrypt. The namespace is embedded in the encryption. A SealedSecret created for namespace: foo will NOT decrypt in namespace: bar. Re-seal with --scope cluster-wide if needed.
  • Key renewal ≠ secret rotation. Renewing the sealing key only adds a new key pair. Old keys remain valid. This does NOT rotate your actual passwords/API keys. You must rotate secrets separately.
  • Re-encryption doesn't update in-cluster objects. kubeseal --re-encrypt outputs new YAML to stdout. It does NOT patch the SealedSecret in the cluster. Apply the output manually.
  • Compromised key: re-encryption is not enough. If a sealing key leaked, assume all secrets encrypted with that key are compromised. Rotate actual secrets (passwords, tokens) not just re-encrypt.
  • skipRecreate: false (default). When a managed Secret is deleted, the controller recreates it. Set skipRecreate: true if you want to allow manual deletion without auto-recreation.
  • Metrics require Service or Pod annotations. The deployed config uses prometheus.io/* pod annotations for scraping. If using Prometheus Operator, enable serviceMonitor.
  • Helm chart version ≠ controller version. Chart 2.18.4 bundles controller 0.36.0. Always check the image.tag value to know which controller version runs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.