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

external-secrets

Skill4 starsChanged 5 months agoMITView on GitHub

Use when working with External Secrets Operator (ESO) — syncing K8s Secrets from external providers (HashiCorp Vault, AWS, GCP, Azure). Covers SecretStore, ExternalSecret, PushSecret, template engine, Helm values, Vault provider auth.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 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.

  • 2

    Very specific

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

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

    refreshInterval: "CreatedOnce" doesn't update: If the provider value changes, ESO won't re-fetch.

    line 242
  2. Distinctive:

    ClusterSecretStore can reference any namespace SA: Make sure the SA referenced has appropriate permissions.

    line 245
  3. Very specific:

    Metrics port conflicts: If another service uses port 8080, set metrics.service.port or disable metrics.

    line 246

≈ “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

External Secrets Operator

Overview

External Secrets Operator (ESO) synchronizes Kubernetes Secrets from external secret management systems. It watches custom resources and reconciles K8s Secrets from the provider's values.

CRDs: SecretStore, ClusterSecretStore, ExternalSecret, ClusterExternalSecret, PushSecret, ClusterPushSecret.

Latest: chart 2.6.0, app v2.6.0.

Architecture

K8s API (ExternalSecret CR)
  → ESO controller watches for changes
    → Queries external provider (Vault, AWS, GCP, Azure...)
      → Creates/updates K8s Secret
        → Template engine processes data (v2)

Three components:

ComponentRole
Core ControllerWatches ExternalSecret/SecretStore CRs, reconciles Secrets, calls provider APIs
Cert ControllerManages webhook certificate lifecycle (can use cert-manager)
WebhookValidating/mutating webhook for CRD validation

CRDs

SecretStore / ClusterSecretStore

Defines how ESO authenticates to a provider. SecretStore is namespaced, ClusterSecretStore is cluster-scoped.

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "http://vault.vault:8200"
      path: "secret"
      version: v2
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "eso-reader"
          serviceAccountRef:
            name: "external-secrets"

Key fields:

FieldDescription
spec.providerProvider type (vault, aws, gcp, azure, etc.)
spec.retrySettingsMax retries + retry interval on provider failure
spec.conditionsService reference for namespace validation

Provider auth methods (Vault):

AuthConfigUse case
kubernetesSA bound to role via vault policy write + K8s auth roleIn-cluster, SA-based
tokenStatic token from SecretKeyRefExternal or bootstrapping
approleroleId + secretId from SecretKeyRefMachine-to-machine
certClient cert from SecretKeyRefmTLS
jwtJWT from SA or SecretKeyRefOIDC-integrated

ExternalSecret

Defines what secret to fetch and how to store it as a K8s Secret.

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: app-secrets
spec:
  refreshInterval: "1h"
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: my-app-secret          # K8s Secret name
    creationPolicy: Owner
    deletionPolicy: Retain
    template:
      type: Opaque
      metadata:
        labels:
          app: my-app
  data:
    - secretKey: password
      remoteRef:
        key: secret/data/myapp
        property: password
  dataFrom:
    - extract:
        key: secret/data/myapp

Key fields:

FieldDescription
spec.refreshIntervalHow often to re-fetch from provider (1h, 5m, CreatedOnce)
spec.secretStoreRefReference to SecretStore or ClusterSecretStore
spec.target.nameName of the K8s Secret to create/update
spec.target.creationPolicyOwner (ESO manages), Orphan, Merge, None
spec.target.deletionPolicyRetain (keep Secret on ES delete), Delete
spec.target.templateTemplate engine to transform data before writing to Secret
spec.dataIndividual key mapping with remoteRef
spec.dataFromBulk fetch: extract (all keys), find (by regex/name)

PushSecret

Pushes a K8s Secret value to an external provider (reverse sync).

apiVersion: external-secrets.io/v1beta1
kind: PushSecret
metadata:
  name: push-myapp
spec:
  refreshInterval: "1h"
  secretStoreRefs:
    - name: vault-backend
      kind: ClusterSecretStore
  data:
    - match:
        secretKey: password
        remoteRef:
          remoteKey: secret/data/pushed/myapp

ClusterExternalSecret

Cluster-scoped ExternalSecret that projects into multiple namespaces:

apiVersion: external-secrets.io/v1beta1
kind: ClusterExternalSecret
metadata:
  name: cluster-app-secrets
spec:
  externalSecretName: app-secrets
  namespaceSelector:
    matchLabels:
      eso-inject: "true"
  refreshTime: "1h"

Template Engine (v2)

ESO's template engine uses Go text/template. Applied via spec.target.template:

spec:
  target:
    template:
      type: kubernetes.io/tls
      data:
        tls.crt: "{{ .crt | base64decode }}"
        tls.key: |
          {{ .key | base64decode | strings.TrimSuffix "\n" }}

Available functions:

FunctionDescription
base64decode / base64encodeBase64 encode/decode
upper / lowerString casing
trim / trimSuffix / trimPrefixString trimming
replaceAllString replacement
toJSON / fromJSONJSON marshal/unmarshal
keys / valuesMap key/value iteration
toString / toBytesType conversion

mergePolicy: Controls how template data merges with secret data:

PolicyBehavior
ReplaceTemplate output entirely replaces fetched data (default)
MergeTemplate keys override fetched keys, others pass through

Refresh Policies

PolicyBehavior
PeriodicRe-fetch at refreshInterval (default 1h)
CreatedOnceFetch once at creation, never refresh
OnChangeWatch the provider for changes (provider-dependent)

Helm Values

ValueDefaultDescription
installCRDstrueInstall CRDs (must be true for Helm-managed)
replicaCount1Controller replicas
serviceMonitor.enabledfalsePrometheus ServiceMonitor
serviceMonitor.interval30sScrape interval
webhook.port9443Webhook server port
webhook.certManager.enabledfalseUse cert-manager for webhook cert
webhook.certManager.issuerRef—Issuer reference (ClusterIssuer or Issuer)
certController.enabledtrueEnable cert controller (disable if cert-manager used)
certController.replicaCount1Cert controller replicas
concurrent1Max concurrent reconcilers
leaderElecttrueLeader election for HA
vault.enableTokenCachetrueCache Vault tokens (disable for short-lived token testing)
scopedRBACfalseRestrict RBAC per SecretStore namespace
controllerClass—Controller class filter (multi-controller setups)
crds.concurrency10CRD patch concurrency
podDisruptionBudget.enabledfalsePDB for HA
global.imagePullSecrets[]Image pull secrets

Metrics

ESO exposes Prometheus metrics on port 8080 (default):

MetricTypeDescription
externalsecret_sync_calls_totalCounterTotal sync calls by status (success/error)
externalsecret_reconcile_duration_secondsHistogramReconcile duration
externalsecret_ready_countGaugeReady ExternalSecrets count
provider_api_calls_countCounterProvider API calls by provider type
secretstore_duration_secondsHistogramSecretStore validation duration

Common Mistakes

  • KV v1 vs v2 path mismatch. Vault KV v2 paths use data/ prefix internally. ESO handles this when version: v2 is set. Set version: v1 for KV v1 engines. Wrong version = 404 errors.
  • K8s auth role without policy. The role eso-reader must be created in Vault first with a policy attached. ESO errors with permission denied if the role exists but has no policy.
  • ServiceAccount in wrong namespace. serviceAccountRef.name must exist in the ESO controller namespace (not the ExternalSecret namespace). Cross-namespace SA references require serviceAccountRef.namespace.
  • refreshInterval: "CreatedOnce" doesn't update. If the provider value changes, ESO won't re-fetch. Use Periodic for dynamic secrets.
  • Template errors are silent. A bad template renders the secret with empty values. Use kubectl describe externalsecret to check status conditions.
  • creationPolicy: Orphan on existing Secret. ESO won't take ownership but also won't update it. The Secret becomes read-only from ESO's perspective.
  • ClusterSecretStore can reference any namespace SA. Make sure the SA referenced has appropriate permissions. ClusterSecretStore is NOT namespace-scoped.
  • Metrics port conflicts. If another service uses port 8080, set metrics.service.port or disable metrics.

Deployment (Flux HelmRelease)

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: external-secrets
  namespace: external-secrets
spec:
  chart:
    spec:
      chart: external-secrets
      sourceRef:
        kind: HelmRepository
        name: external-secrets
      version: 2.6.0
  values:
    installCRDs: true
    serviceMonitor:
      enabled: true
    webhook:
      certManager:
        enabled: true
        issuerRef:
          kind: ClusterIssuer
          name: letsencrypt-production
    certController:
      enabled: false
    vault:
      enableTokenCache: false
    concurrent: 1
    leaderElect: true

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.