external-secrets

External Secrets Operator 外部密钥同步

补充说明

External Secrets Operator（ESO）把 Vault、AWS Secrets Manager、阿里云 KMS、腾讯云 Secret Manager 等外部密钥同步成 Kubernetes Secret。它支持自动刷新、模板、命名空间隔离和 PushSecret。

核心资源：SecretStore、ClusterSecretStore、ExternalSecret、PushSecret 和 SecretStore 的 provider 配置。

语法

安装：

helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  --namespace external-secrets --create-namespace
kubectl -n external-secrets get pods

创建 SecretStore（以 Vault 为例）：

kubectl apply -f - <<'EOF'
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault
  namespace: demo
spec:
  provider:
    vault:
      server: https://vault.example.com
      path: secret
      version: v2
      auth:
        kubernetes:
          mountPath: kubernetes
          role: demo
EOF

创建 ExternalSecret：

kubectl apply -f - <<'EOF'
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db
  namespace: demo
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault
    kind: SecretStore
  target:
    name: db-secret
  data:
  - secretKey: password
    remoteRef:
      key: demo/db
      property: password
EOF

查看同步状态：

kubectl get externalsecret -n demo
kubectl describe externalsecret db -n demo
kubectl get secret db-secret -n demo

使用 ClusterSecretStore 跨命名空间：

kubectl apply -f - <<'EOF'
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-global
spec:
  provider:
    vault:
      server: https://vault.example.com
      path: secret
      version: v2
      auth:
        kubernetes:
          mountPath: kubernetes
          role: global
EOF

注意

• SecretStore 的认证角色和 Vault 策略不匹配，同步报 permission denied。
• remoteRef.key 的路径对 KV v2 要省略 data/，版本和路径写法容易错。
• refreshInterval 太长会导致密钥轮换后应用长时间使用旧值。
• 多个 ExternalSecret 写同一个 Secret，会互相覆盖。
• ClusterSecretStore 权限过大，任何命名空间都能读取。
• 外部密钥删除后，ESO 默认保留最后同步的 Secret，需确认删除策略。
• 网络不通或证书不受信任时，同步失败但应用可能仍在用旧 Secret。
• Secret 内容出现在日志或事件中，注意脱敏。

相关命令

• kubectl get externalsecret -A — 查看同步对象
• kubectl describe externalsecret — 查看失败原因
• kubectl get secretstore,clustersecretstore — 查看存储配置
• kubectl logs -n external-secrets deploy/external-secrets — 控制器日志
• vault / aws secretsmanager — 核对远端密钥

参考链接

• https://external-secrets.io/
• https://github.com/external-secrets/external-secrets
• https://external-secrets.io/latest/provider/vault/