managing-secrets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Secrets

密钥管理

Secure storage, rotation, and delivery of secrets (API keys, database credentials, TLS certificates) for applications and infrastructure.

为应用及基础设施提供密钥（API密钥、数据库凭证、TLS证书）的安全存储、轮换与分发服务。

When to Use This Skill

适用场景

Use when:

Storing API keys, database credentials, or encryption keys
Implementing secret rotation (manual or automatic)
Syncing secrets from external stores to Kubernetes
Setting up dynamic secrets (database, cloud providers)
Scanning code for leaked secrets
Implementing zero-knowledge patterns
Meeting compliance requirements (SOC 2, ISO 27001, PCI DSS)

适用于以下场景：

存储API密钥、数据库凭证或加密密钥
实现密钥轮换（手动或自动）
将密钥从外部存储同步至Kubernetes
配置动态密钥（数据库、云服务商）
扫描代码中的密钥泄露
实现零知识模式
满足合规要求（SOC 2、ISO 27001、PCI DSS）

Quick Decision Frameworks

快速决策框架

Framework 1: Choosing a Secret Store

框架1：选择密钥存储方案

Scenario	Primary Choice	Alternative
Kubernetes + Multi-Cloud	Vault + ESO	Cloud Secret Manager + ESO
Kubernetes + Single Cloud	Cloud Secret Manager + ESO	Vault + ESO
Serverless (AWS Lambda)	AWS Secrets Manager	AWS Parameter Store
Multi-Cloud Enterprise	HashiCorp Vault	Doppler (SaaS)
Small Team (<10 apps)	Doppler, Infisical	1Password Secrets Automation
GitOps-Centric	SOPS (git-encrypted)	Sealed Secrets (K8s-only)

Decision Tree:

Kubernetes? → External Secrets Operator (ESO) with chosen backend
Single cloud? → Cloud-native (AWS/GCP/Azure)
Multi-cloud/on-prem? → HashiCorp Vault
GitOps? → SOPS or Sealed Secrets

场景	首选方案	替代方案
Kubernetes + 多云	Vault + ESO	Cloud Secret Manager + ESO
Kubernetes + 单云	Cloud Secret Manager + ESO	Vault + ESO
无服务器（AWS Lambda）	AWS Secrets Manager	AWS Parameter Store
多云企业	HashiCorp Vault	Doppler（SaaS）
小型团队（<10个应用）	Doppler, Infisical	1Password Secrets Automation
GitOps优先	SOPS（git加密）	Sealed Secrets（仅K8s）

决策树：

涉及Kubernetes？→ 搭配所选后端使用External Secrets Operator (ESO)
单云环境？→ 使用云原生方案（AWS/GCP/Azure）
多云/本地部署？→ HashiCorp Vault
GitOps场景？→ SOPS或Sealed Secrets

Framework 2: Static vs. Dynamic Secrets

框架2：静态密钥 vs 动态密钥

Secret Type	Use Dynamic?	TTL	Solution
Database credentials	YES	1 hour	Vault DB engine
Cloud IAM (AWS/GCP)	YES	15 min	Vault cloud engine
SSH/RDP access	YES	5 min	Vault SSH engine
TLS certificates	YES	24 hours	Vault PKI / cert-manager
Third-party API keys	NO	Quarterly	Vault KV v2 (manual rotation)

密钥类型	是否使用动态密钥？	有效期（TTL）	解决方案
数据库凭证	是	1小时	Vault DB引擎
云IAM（AWS/GCP）	是	15分钟	Vault云引擎
SSH/RDP访问凭证	是	5分钟	Vault SSH引擎
TLS证书	是	24小时	Vault PKI / cert-manager
第三方API密钥	否	每季度	Vault KV v2（手动轮换）

Framework 3: Kubernetes Secret Delivery

框架3：Kubernetes密钥分发

Method	Use Case	Rotation	Restart Required
External Secrets Operator	Static secrets, periodic sync	Polling (1h)	Yes
Secrets Store CSI Driver	File-based, watch rotation	inotify	No
Vault Secrets Operator	Vault-specific, dynamic	Automatic renewal	Optional

方法	适用场景	轮换方式	是否需要重启
External Secrets Operator	静态密钥、定期同步	轮询（1小时）	是
Secrets Store CSI Driver	基于文件、监听轮换	inotify	否
Vault Secrets Operator	专属Vault、动态密钥	自动续期	可选

HashiCorp Vault Fundamentals

HashiCorp Vault 基础

Core Components

核心组件

Secrets Engines: KV v2 (static), Database (dynamic), AWS, PKI, SSH
Auth Methods: Kubernetes, JWT/OIDC, AppRole, LDAP
Policies: HCL-based access control (least privilege)
Leases: TTL for secrets, auto-renewal, auto-revocation

密钥引擎：KV v2（静态）、Database（动态）、AWS、PKI、SSH
认证方式：Kubernetes、JWT/OIDC、AppRole、LDAP
策略：基于HCL的访问控制（最小权限原则）
租赁机制：密钥有效期、自动续期、自动吊销

Static Secrets (KV v2)

静态密钥（KV v2）

bash

undefined

bash

undefined

Create secret

创建密钥

vault kv put secret/myapp/config api_key=sk_live_EXAMPLE

Read secret

读取密钥

vault kv get secret/myapp/config

List versions

查看版本

vault kv metadata get secret/myapp/config

undefined

vault kv metadata get secret/myapp/config

undefined

Dynamic Database Credentials

动态数据库凭证

bash

undefined

bash

undefined

Configure PostgreSQL

配置PostgreSQL

vault write database/config/postgres
plugin_name=postgresql-database-plugin
connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb"

Create role

创建角色

vault write database/roles/app-role
db_name=postgres
creation_statements="CREATE ROLE "{{name}}"..."
default_ttl="1h"

Generate credentials

生成凭证

vault read database/creds/app-role


For detailed Vault architecture, see `references/vault-architecture.md`.

vault read database/creds/app-role


如需了解Vault详细架构，请查看 `references/vault-architecture.md`。

Kubernetes Integration

Kubernetes 集成

External Secrets Operator (ESO)

Syncs secrets from 30+ providers to Kubernetes Secrets.

yaml

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      auth:
        kubernetes:
          role: "app-role"

yaml

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
  target:
    name: db-credentials
  data:
  - secretKey: password
    remoteRef:
      key: secret/data/database/config

将30+种服务商的密钥同步至Kubernetes Secrets。

yaml

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      auth:
        kubernetes:
          role: "app-role"

yaml

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
  target:
    name: db-credentials
  data:
  - secretKey: password
    remoteRef:
      key: secret/data/database/config

Vault Secrets Operator (VSO)

Kubernetes-native Vault integration with automatic lease renewal.

yaml

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  name: postgres-creds
spec:
  vaultAuthRef: vault-auth
  mount: database
  path: creds/app-role
  renewalPercent: 67  # Renew at 67% of TTL
  destination:
    name: dynamic-db-creds

For ESO vs CSI vs VSO comparison, see

references/kubernetes-integration.md

Kubernetes原生Vault集成，支持自动租赁续期。

yaml

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  name: postgres-creds
spec:
  vaultAuthRef: vault-auth
  mount: database
  path: creds/app-role
  renewalPercent: 67  # 在TTL的67%时续期
  destination:
    name: dynamic-db-creds

如需对比ESO、CSI与VSO，请查看

references/kubernetes-integration.md

。

Secret Rotation Patterns

密钥轮换模式

Pattern 1: Versioned Static Secrets (Blue/Green)

模式1：版本化静态密钥（蓝绿部署式）

Create new secret version in Vault
Update staging environment
Monitor for errors (24-48 hours)
Gradual production rollout (10% → 50% → 100%)
Revoke old secret (after 7 days)

在Vault中创建新版本密钥
更新预发布环境配置
监控运行错误（24-48小时）
逐步推广至生产环境（10% → 50% → 100%）
吊销旧密钥（7天后）

Pattern 2: Dynamic Database Credentials

模式2：动态数据库凭证

Vault auto-generates credentials with short TTL:

App fetches credentials from Vault
Vault automatically renews lease (at 67% of TTL)
On expiration, Vault revokes access
On renewal failure, app requests new credentials

Vault自动生成短有效期凭证：

应用从Vault获取凭证
Vault自动续期租赁（在TTL的67%时）
有效期结束后，Vault吊销访问权限
续期失败时，应用请求新凭证

Pattern 3: TLS Certificate Rotation

模式3：TLS证书轮换

Using cert-manager + Vault PKI:

cert-manager requests certificate from Vault
Automatically renews before expiration (default: 67% of duration)
Updates Kubernetes Secret on renewal
Optional pod restart (via Reloader)

For detailed rotation workflows, see

references/rotation-patterns.md

使用cert-manager + Vault PKI：

cert-manager从Vault请求证书
到期前自动续期（默认：有效期的67%）
续期后更新Kubernetes Secret
可选Pod重启（通过Reloader）

如需了解详细轮换流程，请查看

references/rotation-patterns.md

。

Multi-Language Integration

多语言集成

Python (hvac)

Python（hvac）

python

import hvac

client = hvac.Client(url='https://vault.example.com')
client.auth.kubernetes(role='app-role', jwt=jwt)

python

import hvac

client = hvac.Client(url='https://vault.example.com')
client.auth.kubernetes(role='app-role', jwt=jwt)

Fetch dynamic credentials

获取动态凭证

response = client.secrets.database.generate_credentials(name='postgres-role') username = response['data']['username'] password = response['data']['password']

undefined

response = client.secrets.database.generate_credentials(name='postgres-role') username = response['data']['username'] password = response['data']['password']

undefined

Go (Vault API)

Go（Vault API）

import vault "github.com/hashicorp/vault/api"

client, _ := vault.NewClient(vault.DefaultConfig())
k8sAuth, _ := auth.NewKubernetesAuth("app-role")
client.Auth().Login(context.Background(), k8sAuth)

secret, _ := client.Logical().Read("database/creds/postgres-role")

import vault "github.com/hashicorp/vault/api"

client, _ := vault.NewClient(vault.DefaultConfig())
k8sAuth, _ := auth.NewKubernetesAuth("app-role")
client.Auth().Login(context.Background(), k8sAuth)

secret, _ := client.Logical().Read("database/creds/postgres-role")

TypeScript (node-vault)

TypeScript（node-vault）

typescript

import vault from 'node-vault';

const client = vault({ endpoint: 'https://vault.example.com' });
await client.kubernetesLogin({ role: 'app-role', jwt });

const response = await client.read('database/creds/postgres-role');

For complete examples, see

examples/dynamic-db-credentials/

typescript

import vault from 'node-vault';

const client = vault({ endpoint: 'https://vault.example.com' });
await client.kubernetesLogin({ role: 'app-role', jwt });

const response = await client.read('database/creds/postgres-role');

如需完整示例，请查看

examples/dynamic-db-credentials/

。

Secret Scanning

密钥扫描

Pre-Commit Hooks (Gitleaks)

提交前钩子（Gitleaks）

bash

undefined

bash

undefined

Install Gitleaks

安装Gitleaks

brew install gitleaks

Run on staged files

对暂存文件进行扫描

gitleaks protect --staged --verbose


Pre-commit hook prevents secrets from being committed.
For setup, see `examples/secret-scanning/pre-commit`.

gitleaks protect --staged --verbose


提交前钩子可防止密钥被提交至仓库。如需配置，请查看 `examples/secret-scanning/pre-commit`。

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions

name: Run Gitleaks uses: gitleaks/gitleaks-action@v2

undefined

name: Run Gitleaks uses: gitleaks/gitleaks-action@v2

undefined

Remediation Workflow

修复流程

When a secret is leaked:

Rotate immediately (within 1 hour)
Revoke at provider
Remove from Git history (BFG Repo-Cleaner)
Force push (notify team)
Audit access (who had access during leak window)
Document incident

For detailed remediation, see

references/secret-scanning.md

发现密钥泄露时：

立即轮换（1小时内）
在服务商处吊销该密钥
从Git历史中移除（使用BFG Repo-Cleaner）
强制推送（通知团队成员）
审计访问记录（泄露窗口期内的访问人员）
记录事件

如需详细修复步骤，请查看

references/secret-scanning.md

。

Zero-Knowledge Patterns

零知识模式

Client-Side Encryption (E2EE)

客户端加密（端到端加密）

User password → PBKDF2 → encryption key → encrypt secret → send to server

Server stores only encrypted blobs (cannot decrypt).

用户密码 → PBKDF2 → 加密密钥 → 加密密钥内容 → 发送至服务器

服务器仅存储加密后的二进制数据（无法解密）。

Shamir's Secret Sharing

Shamir密钥分片

Split secret into N shares, require M to reconstruct (e.g., 3 of 5).

bash

undefined

将密钥拆分为N个分片，需M个分片才可恢复（例如5个分片中的3个）。

bash

undefined

Initialize Vault with Shamir shares

使用Shamir分片初始化Vault

vault operator init -key-shares=5 -key-threshold=3

Unseal requires 3 of 5 key shares

解封需要5个分片中的3个

vault operator unseal <KEY_1> vault operator unseal <KEY_2> vault operator unseal <KEY_3>


For implementations, see `references/zero-knowledge.md`.

vault operator unseal <KEY_1> vault operator unseal <KEY_2> vault operator unseal <KEY_3>


如需实现示例，请查看 `references/zero-knowledge.md`。

Library Recommendations (2025)

2025年工具库推荐

Secret Stores

密钥存储

Library	Use Case	Trust Score
HashiCorp Vault	Enterprise, multi-cloud	High (73.3/100)
External Secrets Operator	Kubernetes integration	High (85.0/100)
AWS Secrets Manager	AWS workloads	High
GCP Secret Manager	GCP workloads	High
Azure Key Vault	Azure workloads	High

工具库	适用场景	信任评分
HashiCorp Vault	企业级、多云	高（73.3/100）
External Secrets Operator	Kubernetes集成	高（85.0/100）
AWS Secrets Manager	AWS工作负载	高
GCP Secret Manager	GCP工作负载	高
Azure Key Vault	Azure工作负载	高

Secret Scanning

密钥扫描

Library	Use Case	Trust Score
Gitleaks	Pre-commit, CI/CD	High (89.9/100)
TruffleHog	Git history scanning	Medium

工具库	适用场景	信任评分
Gitleaks	提交前检查、CI/CD	高（89.9/100）
TruffleHog	Git历史扫描	中

Client Libraries

客户端库

Language	Library	Version
Python	`hvac`	2.2.0+
Go	`vault/api`	Latest
TypeScript	`node-vault`	0.10.2+
Rust	`vaultrs`	0.7+

语言	工具库	版本
Python	`hvac`	2.2.0+
Go	`vault/api`	最新版
TypeScript	`node-vault`	0.10.2+
Rust	`vaultrs`	0.7+

Common Workflows

常见工作流程

Workflow 1: Vault + ESO on Kubernetes

流程1：Kubernetes上的Vault + ESO部署

Install Vault (Helm chart)
Initialize and unseal Vault
Enable Kubernetes auth
Install External Secrets Operator
Create SecretStore (Vault connection)
Create ExternalSecret (secret mapping)

For step-by-step guide, see

examples/vault-eso-setup/

安装Vault（Helm Chart）
初始化并解封Vault
启用Kubernetes认证
安装External Secrets Operator
创建SecretStore（Vault连接配置）
创建ExternalSecret（密钥映射）

如需分步指南，请查看

examples/vault-eso-setup/

。

Workflow 2: Dynamic Database Credentials

流程2：动态数据库凭证配置

Enable database secrets engine
Configure database connection
Create role with TTL
App fetches credentials
Vault auto-renews lease

For implementation, see

examples/dynamic-db-credentials/

启用数据库密钥引擎
配置数据库连接
创建带有效期的角色
应用获取凭证
Vault自动续期租赁

如需实现示例，请查看

examples/dynamic-db-credentials/

。

Workflow 3: Secret Scanning Remediation

流程3：密钥泄露修复

Gitleaks detects secret
Block commit (pre-commit hook)
Developer removes secret
Developer stores in Vault
Developer references Vault path

For setup, see

examples/secret-scanning/

Gitleaks检测到密钥
提交前钩子阻止提交
开发者移除代码中的密钥
开发者将密钥存储至Vault
开发者引用Vault路径

如需配置，请查看

examples/secret-scanning/

。

Integration with Related Skills

与其他技能的集成

auth-security: OAuth client secrets, JWT signing keys
databases-*: Dynamic database credentials
deploying-applications: Container registry credentials
observability: Grafana/Datadog API keys
infrastructure-as-code: Cloud provider credentials

auth-security：OAuth客户端密钥、JWT签名密钥
databases-*：动态数据库凭证
deploying-applications：容器仓库凭证
observability：Grafana/Datadog API密钥
infrastructure-as-code：云服务商凭证

Security Best Practices

安全最佳实践

Never commit secrets to Git (use Gitleaks pre-commit hook)
Use dynamic secrets where possible
Rotate secrets regularly (quarterly for static, hourly for dynamic)
Implement least privilege (Vault policies, RBAC)
Enable audit logging
Encrypt at rest (Vault storage, etcd encryption)
Use short TTLs (< 24 hours for dynamic secrets)
Monitor failed access attempts

切勿将密钥提交至Git（使用Gitleaks提交前钩子）
尽可能使用动态密钥
定期轮换密钥（静态密钥每季度，动态密钥每小时）
实现最小权限原则（Vault策略、RBAC）
启用审计日志
静态加密（Vault存储、etcd加密）
使用短有效期（动态密钥<24小时）
监控失败的访问尝试

Common Pitfalls

常见误区

Secrets in Environment Variables

密钥存储在环境变量中

Environment variables visible in process lists. Solution: Use file-based secrets (Kubernetes volumes, CSI driver).

环境变量可在进程列表中被查看。 解决方案： 使用基于文件的密钥（Kubernetes卷、CSI驱动）。

Hardcoded Secrets in Manifests

清单文件中硬编码密钥

Base64 is not encryption. Solution: Use External Secrets Operator.

Base64编码并非加密。 解决方案： 使用External Secrets Operator。

No Secret Rotation

未配置密钥轮换

Stale credentials increase breach risk. Solution: Use dynamic secrets or automate rotation.

长期未更新的凭证会增加泄露风险。 解决方案： 使用动态密钥或自动轮换机制。

Root Token in Production

生产环境使用Root Token

Unlimited permissions. Solution: Use auth methods with least privilege policies.

Root Token拥有无限制权限。 解决方案： 使用带最小权限策略的认证方式。