k8s-servant/k8s-skills

k8s-external-secrets-troubleshooting

Use when External Secrets Operator does not create or update a Kubernetes Secret: an ExternalSecret with SecretSyncedError ("could not get secret data from provider"), SecretOwnedByOther ("target is owned by another ExternalSecret"), SecretMissing or Secret…

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/k8s-servant/k8s-skills --skill k8s-external-secrets-troubleshooting

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

External Secrets troubleshooting

Find out why External Secrets Operator (ESO) does not create or update a Secret, and propose a fix. Read first, ask before changing. Run the investigation commands freely. Run a command under an "Ask first" line only after the user approves that exact command; if your credentials do not allow it, give it to the user to run. Never run a "Proposed fix"; hand it to the user.

An ExternalSecret says which keys to fetch from an external store and which Kubernetes Secret to write (spec.target). It uses a SecretStore (one namespace) or ClusterSecretStore (any allowed namespace) that holds the provider configuration (a cloud secret manager, Vault, and others). The ESO controller syncs on spec.refreshInterval and reports the result on the ExternalSecret's Ready condition.

Never read Secrets, here least of all: not the target Secret ESO writes, not the provider credentials a store references, not the webhook's certificate. You can tell whether a sync worked from the ExternalSecret's status and events. If the user wants to check a value, they look at it themselves.

The commands use placeholders: my-namespace, my-app-config (the ExternalSecret and its target Secret), my-app-store (the store) and external-secrets (the namespace ESO runs in; a Helm install usually uses external-secrets, the release manifest default). Replace them with the real names.

When to use

  • A Secret that an ExternalSecret should create is missing, or has old values.
  • kubectl get externalsecrets shows SecretSyncedError, SecretOwnedByOther,

SecretMissing or SecretImmutable.

  • A SecretStore or ClusterSecretStore is not Ready.
  • A ClusterExternalSecret did not create its ExternalSecrets in some namespaces.

Hand-offs, by skill name. When the evidence points elsewhere, continue with that skill; if it is not installed, keep going with the steps here and tell the user which skill would help:

  • The Secret exists and the app still fails (it does not read it, the pod is not

restarted after a change, it crashes): k8s-workload-troubleshooting.

  • The ESO pods crash or stay Pending: k8s-workload-troubleshooting.

Investigate

Work through the steps in order. Stop when you have the cause and its evidence.

1. List the ExternalSecrets with their store, status and last sync.

bash
kubectl get externalsecrets -n my-namespace
kubectl get clusterexternalsecrets

2. Read the ExternalSecret: its store reference, target, keys, and conditions and events.

bash
kubectl describe externalsecret my-app-config -n my-namespace
kubectl get externalsecret my-app-config -n my-namespace -o jsonpath='{.spec.secretStoreRef}{"\n"}{.spec.target}{"\n"}{.spec.data}{"\n"}{.spec.dataFrom}{"\n"}{.status.conditions}{"\n"}'
kubectl events -n my-namespace --for externalsecret/my-app-config

3. Read the store it points at.

bash
kubectl get secretstores -n my-namespace
kubectl get clustersecretstores
kubectl describe secretstore my-app-store -n my-namespace

4. Read the controller's logs. Since ESO 2.14 the ExternalSecret's status and events say only could not get secret data from provider for every store or provider problem; the actual cause is in the controller's log, under Reconciler error.

bash
kubectl get deployments -A -l app.kubernetes.io/name=external-secrets
kubectl logs -n external-secrets deployment/external-secrets --tail=200 | grep my-app-config

5. Open the matching reference and follow its steps:

What you seeReference
SecretSyncedError could not get secret data from provider: a missing key, a wrong store name, store not ready, namespace not allowedreferences/sync-errors.md
A store not Ready: InvalidProviderConfig, ProviderNotFound, ValidationUnknownreferences/stores.md
SecretOwnedByOther, SecretMissing, SecretImmutable, values that do not refresh, ClusterExternalSecrets, removed v1beta1references/target-and-refresh.md

Read the results

What the common findings mean (ESO 2.14):

  • Ready False, reason SecretSyncedError, `could not get secret data from

provider**: the generic message. The controller log for that ExternalSecret has the real error, for example error processing spec.data[0] (key: <key>), err: Secret does not exist (the key is not in the store) or could not get SecretStore "<name>"` (no store of that name in the namespace).

  • **Reason SecretOwnedByOther, `target is owned by another ExternalSecret: ... secret

is owned by another ExternalSecret: <name>`**: two ExternalSecrets write the same target Secret. The first one owns it; the other cannot sync.

  • A store `Ready` `False`, `InvalidProviderConfig` (unable to create client or

unable to validate store): ESO cannot reach or authenticate to the provider with the store's configuration. Credentials are in Secrets: the user checks them.

  • `Ready` `True`, `secret synced`, but the app sees an old value: ESO wrote the

Secret; either the external value changed after the last refresh (spec.refreshInterval, refreshPolicy), or the app reads the Secret only at start.

  • A store event `StoreUnmaintained` (store isn't currently maintained): the

provider is marked unmaintained in this ESO version; it may still work.

State the cause in one sentence, then the evidence you saw (the condition, the event, the log line, the spec field), then the proposed fix.

Proposed fix

Show each fix to the user before running it: what it changes and how to undo it. Patching an ExternalSecret's store reference or remote key, and asking ESO to sync now, are reversible, so they go under "Ask first" and run only after the user says yes. Creating or changing Secrets (provider credentials, the target), changing stores, and deleting ExternalSecrets or their target Secrets are never run by you: hand them to the user as proposed fixes. Prefer fixing the source the ExternalSecret is deployed from. Write each undo with the values you found.

Point an ExternalSecret at the store that exists (to test before fixing the source):

Ask first: the agent runs this only after the user approves it.
bash
kubectl patch externalsecret my-app-config -n my-namespace --type=merge -p '{"spec": {"secretStoreRef": {"name": "my-app-store"}}}'
# Undo: kubectl patch externalsecret my-app-config -n my-namespace --type=merge -p '{"spec": {"secretStoreRef": {"name": "my-store"}}}'

Ask ESO to sync now instead of waiting for the refresh interval (use the current time as the value; any new value triggers a sync):

Ask first: the agent runs this only after the user approves it.
bash
kubectl annotate externalsecret my-app-config -n my-namespace force-sync=2026-10-24T12:00:00Z --overwrite
# Undo: nothing to undo; the annotation only asks for one sync

Sources

Checked against the External Secrets Operator 2.14 documentation and source (v2.14.0):

and the FAQ, whose last debug step reads the created Secret, which this skill leaves to the user.

SecretStore, ClusterSecretStore and ClusterExternalSecret: fields, policies, refresh and force-sync.

creation and deletion policies, ownership.

v1beta1 no longer served.

  • Conditions, messages and the 2.14 change that keeps provider errors out of status

(PR #7149), from the source: externalsecret_types.go, externalsecret_controller.go, statuserr.go. The messages quoted here were also seen on a Kubernetes 1.37 kind cluster with ESO 2.14.0.

同じリポジトリから

関連する Skills

すべての Skills
k8s-servant
コミュニティ

k8s-api-troubleshooting

Use when the Kubernetes API server itself refuses or fails a request, before any controller acts on it: "failed calling webhook", "admission webhook ... denied the request", "ValidatingAdmissionPolicy ... denied request", a ReplicaSet with FailedCreate and no pods, an APIService "False (ServiceNotFound)", "FailedDiscoveryCheck" or "MissingEndpoints", "unable to retrieve the complete list of server APIs", a namespace stuck in Terminating, "no matches for kind" or "ensure CRDs are installed first"

1時間の導入数
1
GitHub Stars
38
更新日
11月20日
k8s-servant
コミュニティ

k8s-argocd-troubleshooting

Use when Argo CD does not deploy or update an application in Kubernetes: an Application that is OutOfSync, Unknown, Degraded, Missing or Progressing, a ComparisonError ("app path does not exist", "unable to resolve ... to a commit SHA"), an InvalidSpecError ("do not match any of the allowed destinations in project"), a sync that fails ("one or more objects failed to apply"), auto-sync that never runs, resources that stay OutOfSync after a sync, or ApplicationSets that generate nothing. Investiga

1時間の導入数
1
GitHub Stars
38
更新日
11月20日
k8s-servant
コミュニティ

k8s-cert-manager-troubleshooting

Use when cert-manager does not issue or renew a certificate in Kubernetes: a Certificate that stays READY False, a CertificateRequest that is Pending, Denied or Failed, an Issuer or ClusterIssuer that is not Ready ("Error getting keypair for CA issuer"), "Referenced \"Issuer\" not found", ACME Orders or Challenges stuck pending (HTTP-01, DNS-01, rate limits), a certificate that expired or did not renew, or "failed calling webhook \"webhook.cert-manager.io\"" when applying resources. Investigates

1時間の導入数
1
GitHub Stars
38
更新日
11月20日
k8s-servant
コミュニティ

k8s-cilium-troubleshooting

Use when networking fails on a Kubernetes cluster that runs Cilium as its CNI: traffic between pods dropped or timing out after a CiliumNetworkPolicy or CiliumClusterwideNetworkPolicy, "Policy denied" drops in Hubble, DNS that stops resolving after an egress policy, HTTP 403 "Access denied" from an L7 rule, toFQDNs rules that do not match, pods stuck ContainerCreating with "unable to connect to Cilium agent", Cilium agent or operator pods not ready, CiliumEndpoints not ready, or IPAM exhaustion.

1時間の導入数
1
GitHub Stars
38
更新日
11月20日