External Secrets Operator API 规范全解析：external-secrets.io/v1 与 v1alpha1/v1beta1 资源字段权威参考-迪斯科星球

External Secrets Operator API 规范全解析：external-secrets.io/v1 与 v1alpha1/v1beta1 资源字段权威参考

【免费下载链接】external-secretsExternal Secrets Operator reads information from a third-party service like AWS Secrets Manager and automatically injects the values as Kubernetes Secrets.项目地址: https://gitcode.com/GitHub_Trending/ex/external-secrets

导读

本文是 External Secrets Operator（ESO）的API 规范（spec）权威参考指南，以仓库中的 docs/api/spec.md 为核心骨架，完整梳理external-secrets.io/v1（核心 CRD：ExternalSecret、SecretStore、ClusterSecretStore、ClusterExternalSecret）、external-secrets.io/v1alpha1（PushSecret 推送能力）与generators.external-secrets.io/v1alpha1（密钥生成器）四个 Go 包下全部资源类型的字段定义、枚举取值与默认行为。读完本文，你将能够：准确编写可校验的 ExternalSecret / SecretStore / PushSecret 清单文件；理解data与dataFrom、creationPolicy与deletionPolicy、refreshPolicy与syncWindows等关键配置项的真实语义；并掌握如何在本仓库源码（apis/externalsecrets/v1/*.go）与生成的 CRD 清单（config/crds/bases）中核对每一项字段。文档入口：docs/api/spec.md（另见 docs/api/externalsecret.md、docs/api/secretstore.md、docs/api/pushsecret.md 等分篇指南）。

一、API 包总览：四个包的定位与关系

docs/api/spec.md在开头即给出包索引，全部 API 类型分布在以下四个包中：

包	版本定位	核心资源类型
`external-secrets.io/v1`	主版本（GA），当前默认使用	ExternalSecret、SecretStore、ClusterSecretStore、ClusterExternalSecret 及全部 Provider 配置
`external-secrets.io/v1alpha1`	早期版本，承载演进中的 PushSecret / ClusterPushSecret	PushSecret、ClusterPushSecret 及全部 PushSecret 子类型
`external-secrets.io/v1beta1`	Beta 版本（已进入弃用流程），结构与 v1 基本对齐	ExternalSecret、SecretStore、ClusterSecretStore、ClusterExternalSecret 及 Provider 配置
`generators.external-secrets.io/v1alpha1`	密钥生成器（Generator）专用	ACRAccessToken、ECRAuthorizationToken、GCRAccessToken、GitHubAccessToken、GitLabDeployToken、Password、SSHKey、UUID、VaultDynamicSecret、Webhook 等

对应源码位于 apis/externalsecrets/v1（含externalsecret_types.go、secretstore_types.go及secretstore_*.go系列文件）、apis/externalsecrets/v1alpha1 与 apis/generators/v1alpha1。生成的 CRD 清单见 config/crds/bases 下的 26 个 YAML 文件，二者字段一一对应，可作为校验清单的最佳事实来源。

二、SecretStore 与 ClusterSecretStore：密钥源的统一抽象

2.1 资源定位

SecretStore 是命名空间级资源，ClusterSecretStore 是集群级资源，二者承载相同的spec（SecretStoreSpec）与status（SecretStoreStatus）。ExternalSecret 通过spec.secretStoreRef引用它们，从而解耦“密钥从哪里来”与“密钥怎么用”。

2.2 SecretStoreSpec 核心字段

字段	类型	说明
`provider`	`SecretStoreProvider`	必填，Provider 专属配置，二选一（详见下文）
`refreshInterval`	`meta/v1.Duration`	可选，Provider 凭据的刷新间隔（Golang Duration 字符串，如`"1h"`）
`controller`	`string`	可选，指定由哪个 controller 实例处理；配合`--enable-controller`与 ControllerClass 实现多租户隔离
`retrySettings`	`SecretStoreRetrySettings`	可选，定义请求重试策略（`maxRetries`、`retryInterval`等），见`docs/api/secretstore.md`

2.3 SecretStoreProvider：Provider 专属配置的并集

SecretStoreProvider是一个“一字段一 Provider”的并集结构，docs/api/spec.md为其列出了数十个可选字段，每个字段对应一个 Provider 的完整配置类型：

云厂商密钥服务：aws（AWSProvider）、azurekv（AzureKVProvider）、gcpsm（GCPSMProvider）、oracle（OracleProvider）、ibm（IBMProvider）、yandexlockbox（YandexLockboxProvider）、yandexcertificatemanager（YandexCertificateManagerProvider）、volcengine（VolcengineProvider）、scaleway（ScalewayProvider）、cloudru（CloudruSMProvider）、nebius（NebiusMysteryboxProvider）；
Vault 生态：vault（VaultProvider）、openbao（OpenBaoProvider）、akeyless（AkeylessProvider）、fortanix（FortanixProvider）、conjur（ConjurProvider）；
DevOps / SaaS 平台：doppler（DopplerProvider）、infisical（InfisicalProvider）、onboardbase（OnboardbaseProvider）、previder（PreviderProvider）、passbolt（PassboltProvider）、passworddepot（PasswordDepotProvider）、secretserver（SecretServerProvider）、delinea（DelineaProvider）、keepersecurity（KeeperSecurityProvider）、senhasegura（SenhaseguraProvider）、bitwardensecretsmanager（BitwardenSecretsManagerProvider）、ngrok（NgrokProvider）、pulumi（PulumiProvider）、beyondtrust（BeyondtrustProvider）、beyondtrustworkloadcredentials（BeyondtrustWorkloadCredentialsProvider）、chef（ChefProvider）、dvls（DVLSProvider）；
代码托管 / GitOps：github（GithubProvider，仅支持写操作，即 PushSecret，无法从 GitHub 拉取）、gitlab（GitlabProvider）；
通用 / 基础设施：kubernetes（KubernetesProvider，读取其他集群的 Secret）、crd（CRDProvider，从任意 Kubernetes 资源读取，按 API group/version/kind 选择；注意读取 core v1 Secret 被有意禁用，应改用 Kubernetes Provider）、webhook（WebhookProvider，通用模板化 Webhook）、fake（FakeProvider，静态键值对，多用于测试与本地演示）、onepassword（OnePasswordProvider）、onepasswordSDK（OnePasswordSDKProvider）、ovh（OvhProvider）。

说明：GithubProvider在 spec 中被明确标注为“仅支持写操作（PushSecret）且无法从 GitHub 获取密钥”；CRDProvider则说明“group 可为空字符串以选择 ConfigMap 等核心资源，但读取 core v1 Secret 被有意阻止”。

2.4 以 AWSProvider 为例看 Provider 配置结构

AWSProvider是 Provider 配置中最具代表性的一个，其字段在 spec 中均有完整描述：

字段	类型	必填	说明
`service`	`AWSServiceType`	是	指定使用哪个 AWS 服务，枚举：`SecretsManager`、`ParameterStore`、`CertificateManager`
`region`	`string`	是	Provider 使用的 AWS 区域
`auth`	`AWSAuth`	否	认证信息；若不设置，AWS SDK 会从环境推断凭据
`role`	`string`	否	Provider 将扮演的 Role ARN
`additionalRoles`	`[]string`	否	在扮演最终 Role 之前依序扮演的链式 Role ARN 列表
`externalID`	`string`	否	设置在假定 IAM 角色上的 AWS External ID
`sessionTags`	`[]*Tag`	否	AWS STS assume role 会话标签
`transitiveTagKeys`	`[]string`	否	传递性会话标签，多规则场景必需
`sessionTagsPolicy`	`SessionTagsPolicy`	否	控制扮演角色时是否及如何附加 STS 会话标签：`None`（默认，不加）、`Simple`（自动附加`esoNamespace`、`esoStoreName`、`esoStoreKind`）、`Custom`（在 Simple 基础上追加`customSessionTags`）；使用 Simple/Custom 时 IAM 角色必须具备`sts:TagSession`权限
`customSessionTags`	`map[string]string`	否	`SessionTagsPolicy=Custom`时附加的自定义会话标签
`secretsManager`	`SecretsManager`	否	定义与 AWS SecretsManager 交互时的行为
`prefix`	`string`	否	为所有取回的值添加前缀

AWSAuth规定认证方式三选一：secretRef（静态凭据）、jwt（基于 ServiceAccount 令牌，AWSJWTAuth.serviceAccountRef）或都不设置（由 AWS SDK 默认链路解析）。AWSAuthSecretRef要求accessKeyIDSecretRef与secretAccessKeySecretRef必须同时定义才能正确认证；若为临时凭据，还需提供sessionTokenSecretRef。

最小可运行示例（AWS SecretsManager + 静态凭据）：

apiVersion: external-secrets.io/v1 kind: SecretStore metadata: name: aws-secretsmanager spec: provider: aws: service: SecretsManager region: us-east-1 auth: secretRef: accessKeyIDSecretRef: name: aws-credentials key: access-key secretAccessKeySecretRef: name: aws-credentials key: secret-access-key # 可选：角色扮演与会话标签 # role: arn:aws:iam::123456789012:role/eso-reader # sessionTagsPolicy: Simple

对应的完整 Provider 文档与示例可分别查看 docs/provider/aws-secrets-manager.md、docs/snippets/aws-sm-store.yaml。Provider 的类型定义源码位于 apis/externalsecrets/v1/secretstore_aws_types.go 等secretstore_*.go文件中。

三、ExternalSecret：把外部密钥变成 Kubernetes Secret

3.1 资源定义与核心 Spec 字段

spec 对 ExternalSecret 的定位是：“定义如何从外部 API 获取数据，并将其作为 Kubernetes Secrets 提供”（见ExternalSecret类型注释）。其spec（ExternalSecretSpec）字段如下：

字段	类型	说明
`secretStoreRef`	`SecretStoreRef`	可选，引用`SecretStore`或`ClusterSecretStore`（含`kind`字段区分二者）
`target`	`ExternalSecretTarget`	可选，定义要创建的 Kubernetes Secret 的蓝图
`refreshPolicy`	`ExternalSecretRefreshPolicy`	可选，刷新策略（见下）
`refreshInterval`	`meta/v1.Duration`	可选，从 Provider 重新读取值的间隔；默认`1h0m0s`
`syncWindows`	`ExternalSecretSyncWindows`	可选，限制周期刷新的时间窗口（仅对 Periodic 策略生效）
`data`	`[]ExternalSecretData`	可选，逐键映射：K8s Secret 键 ↔ Provider 数据
`dataFrom`	`[]ExternalSecretDataFromRemoteRef`	可选，批量拉取 Provider 数据的所有属性；多条按顺序合并

refreshInterval使用 Golang Duration 字符串，合法时间单位是ns、us（或µs）、ms、s、m、h，例如"1h0m0s"、"2h30m0s"、"10m0s"；设为"0s"表示只拉取并创建一次。

3.2 RefreshPolicy：三种刷新策略

ExternalSecretRefreshPolicy（string别名）在 spec 中定义了三个取值：

取值	语义
`CreatedOnce`	仅在 Secret 不存在时创建，之后不再更新
`Periodic`	按`refreshInterval`周期从外部源同步；若`refreshInterval`为 0 则不进行周期更新
`OnChange`	仅在 ExternalSecret 的 metadata 或 spec 发生变化时同步

syncWindows用于进一步约束 Periodic 刷新：每个条目由schedule（标准 5 段 cron 表达式，UTC 求值，也支持@daily、@every 1h等简写）与duration（窗口持续时长，如"8h"）组成；kind取allow（仅窗口激活期间允许刷新）或deny（窗口激活期间阻止刷新），同一列表内所有窗口共享一个 Kind。示例：schedule: "0 22 * * 1-5"、duration: "8h"表示每个工作日 22:00 UTC 打开 8 小时刷新窗口。

3.3 Target：目标 Secret 的创建策略

ExternalSecretTarget字段包括：

字段	类型	默认值 / 说明
`name`	`string`	默认为 ExternalSecret 的`.metadata.name`
`creationPolicy`	`ExternalSecretCreationPolicy`	默认`Owner`
`deletionPolicy`	`ExternalSecretDeletionPolicy`	默认`Retain`
`template`	`ExternalSecretTemplate`	目标 Secret 的蓝图（type、engineVersion、metadata、mergePolicy、data、templateFrom）
`manifest`	`ManifestReference`	改为创建自定义资源（如 ConfigMap、CR）而非 Secret；spec 明确警告这是 Generic target，需确保访问策略与加密配置正确
`immutable`	`bool`	最终 Secret 是否不可变

ExternalSecretCreationPolicy的五个取值（spec 有逐项语义说明）：

取值	语义
`CreateOrMerge`	缺失时创建，已存在时合并 data 字段且不设置 ownerReference；ExternalSecret 存在期间被删除的目标会被重建，删除 ExternalSecret 后 Secret 保留
`Merge`	不创建 Secret，仅将 data 字段合并进已有 Secret
`None`	不创建 Secret（预留给未来 injector 使用）
`Orphan`	创建 Secret 但不设置 ownerReference，ExternalSecret 删除后 Secret 被孤立保留
`Owner`	创建 Secret 并设置`.metadata.ownerReferences`指向 ExternalSecret（默认值）

3.4 data 与 dataFrom：单键映射与批量拉取

data[].ExternalSecretData是“一键一值”的显式映射：

字段	说明
`secretKey`	Kubernetes Secret 中存放值的键
`remoteRef`	指向远端密钥，定义拉取哪个 secret（version/property 等）
`sourceRef`	允许覆盖值的来源（`StoreSourceRef`）

remoteRef（ExternalSecretDataRemoteRef）的完整字段：

字段	必填	说明
`key`	是	Provider 中的密钥键，必填
`metadataPolicy`	否	是否拉取 Provider 密钥的 tags/labels：`Fetch`或`None`，默认`None`
`property`	否	当 Provider 值是 map 时选择特定属性（如 JSON 字段）
`version`	否	远端密钥版本（Provider 支持时）
`conversionStrategy`	否	值转换策略：`Default`/`Unicode`（`ExternalSecretConversionStrategy`）
`decodingStrategy`	否	解码策略（`ExternalSecretDecodingStrategy`），见 docs/guides/decoding-strategy.md

dataFrom[].ExternalSecretDataFromRemoteRef用于批量拉取，支持四种子模式（字段互斥组合）：

字段	说明
`extract`	从一个 secret 中提取多组键值对（不支持`sourceRef.Generator`）
`find`	基于 tags 或正则查找多个 secret（不支持`sourceRef.Generator`）
`rewrite`	对拉取到的 Secret 键做重写，支持多个操作按“先到后”分层应用
`sourceRef`	指向 store 或 generator（`StoreGeneratorSourceRef`）；指向 generator 时不支持 Extract/Find，generator 返回静态 map

ExternalSecretRewrite支持regexp（正则重写，ExternalSecretRewriteRegexp）与transform（变换重写，ExternalSecretRewriteTransform）两种操作，对应实战指南见 docs/guides/datafrom-rewrite.md 与 docs/api/selectable-fields.md。

最小可运行示例（data + dataFrom 组合）：

apiVersion: external-secrets.io/v1 kind: ExternalSecret metadata: name: app-secrets spec: refreshInterval: 10m refreshPolicy: Periodic secretStoreRef: name: aws-secretsmanager kind: SecretStore target: name: my-app-secret creationPolicy: Owner deletionPolicy: Retain template: type: Opaque data: - secretKey: db-password remoteRef: key: prod/db property: password dataFrom: - extract: key: prod/app-config - find: name: regexp: "^prod/feature-.*$" - rewrite: - regexp: source: "prod/" target: ""

3.5 Status 与观测字段

ExternalSecretStatus包含：refreshTime（最近一次拉取并更新目标 Secret 的时间）、syncedResourceVersion（最近同步版本）、conditions（条件列表）与binding（servicebinding.io Provisioned Service 引用）。ExternalSecretConditionType只有两个取值：Ready（已就绪并同步）与Deleted（已删除）。

四、ClusterExternalSecret：跨命名空间批量生成 ExternalSecret

ClusterExternalSecret（external-secrets.io/v1）与ClusterSecretStore（集群级）配套，解决“一个外部密钥源分发到多个命名空间”的问题。ClusterExternalSecretSpec在 spec 中完整列出了：

字段	说明
`externalSecretSpec`	嵌入的`ExternalSecretSpec`，作为每个命名空间中生成的 ExternalSecret 的模板
`namespaceSelector`/`namespaceList`	选择目标命名空间（标签选择器或显式列表）
`refreshInterval`	重新评估命名空间匹配并生成/回收 ExternalSecret 的间隔
`maxNamespaces`（推断）	单次最多生成的命名空间数上限

其状态（ClusterExternalSecretStatus）含conditions、generatedExternalSecrets（已生成的 ExternalSecret 数量）、failedNamespaces（ClusterExternalSecretNamespaceFailure，含 namespace 与失败原因）等观测字段。完整介绍见 docs/api/clusterexternalsecret.md 与设计文档 design/003-cluster-external-secret-spec.md。

五、PushSecret 与 ClusterPushSecret（v1alpha1）：把 Kubernetes Secret 推回 Provider

external-secrets.io/v1alpha1包承载方向相反的同步能力——将集群内的 Secret 推送到外部 Provider。PushSecretSpec核心字段：

字段	类型	说明
`refreshInterval`	`meta/v1.Duration`	尝试推送的间隔
`secretStoreRefs`	`[]PushSecretStoreRef`	目标 Provider 引用列表（可同时推送到多个 store）
`updatePolicy`	`PushSecretUpdatePolicy`	如何更新 Provider 中的 Secret
`deletionPolicy`	`PushSecretDeletionPolicy`	删除 ExternalSecret 时如何处理 Provider 中的 Secret
`selector`	`PushSecretSelector`	指定源 Kubernetes Secret
`data`	`[]PushSecretData`	逐键推送规则（`match`匹配源键、`conversionStrategy`转换策略）
`dataTo`	`[]PushSecretDataTo`	批量推送规则：把源 Secret 的键按`match`/正则展开为 Provider 条目（含`override`、`rewrite`、`template`、`metadata`等）
`template`	`ExternalSecretTemplate`	推送内容的模板

配套类型还包括：PushSecretDataToMatch（all/regexp）、PushSecretRewrite、PushSecretMetadata、PushSecretRemoteRef、PushSecretSecret、PushSecretStoreRef（storeRef +generation）以及SyncedPushSecretsMap（status.syncedPushSecrets记录各 store 的同步结果）。PushSecretStatus提供refreshTime、syncedResourceVersion、syncedPushSecrets三个观测字段。

最小示例（推送到 AWS SecretsManager）：

apiVersion: external-secrets.io/v1alpha1 kind: PushSecret metadata: name: push-db-creds spec: refreshInterval: 10m secretStoreRefs: - name: aws-secretsmanager kind: SecretStore selector: secret: name: my-app-secret data: - match: secretKey: db-password remoteRef: remoteKey: prod/db-password

完整说明见 docs/api/pushsecret.md、docs/guides/pushsecrets.md 与设计文档 design/002-pushsecret.md。注意：PushSecret 属于 v1alpha1，字段仍可能演进。

六、generators.external-secrets.io/v1alpha1：在集群内生成新密钥

generators.external-secrets.io/v1alpha1提供“生成器”能力——不再从外部系统拉取，而是在集群内按需生成新凭据，并通过 ExternalSecret 的dataFrom[].sourceRef.generatorRef消费。spec 中列出了完整的生成器类型，包括：

生成器	用途
`ACRAccessToken`	Azure Container Registry 短期访问令牌
`ECRAuthorizationToken`	AWS ECR 授权令牌
`GCRAccessToken`	Google Container Registry 访问令牌
`GitHubAccessToken`	GitHub App 安装访问令牌
`GitLabDeployToken`	GitLab Deploy Token 创建
`Password`	按规则生成随机密码（长度、字符集、数字/符号数量等）
`SSHKey`	生成 RSA/ECDSA SSH 密钥对
`UUID`	生成 UUID
`VaultDynamicSecret`	从 Vault 动态 secret 引擎获取租约凭据
`Webhook`	通过自定义 Webhook 生成
其他	Quay、Cloudsmith、Fake、Grafana、MFA、STS、beyondtrustworkloadcredentials 等

典型用法：ExternalSecret 的dataFrom[].sourceRef指向generatorRef（GeneratorRef，含apiVersion、kind、name）。例如用 Password 生成器：

apiVersion: external-secrets.io/v1 kind: ExternalSecret metadata: name: generated-password spec: secretStoreRef: name: fake-store kind: SecretStore target: name: generated-secret dataFrom: - sourceRef: generatorRef: apiVersion: generators.external-secrets.io/v1alpha1 kind: Password name: my-password --- apiVersion: generators.external-secrets.io/v1alpha1 kind: Password metadata: name: my-password spec: length: 32 digits: 8 symbols: 4

生成器的 API 文档分篇见 docs/api/generator，示例见 docs/snippets/generator-password-example.yaml；其实现位于 generators/v1 下的独立子模块（每个生成器一个 Go module）。生成器的状态机与条件说明见 design/011-generator-state.md。

七、v1 与 v1beta1：版本关系与迁移提示

spec 中external-secrets.io/v1beta1的绝大部分类型与external-secrets.io/v1同名同构（如AWSAuth、ExternalSecret、SecretStore、VaultProvider等），但存在少量差异，例如：

v1beta1 提供AlibabaAuth/AlibabaProvider/AlibabaRRSAAuth、Device42Provider等 v1 中未出现的 Provider 类型；
v1beta1 未包含 v1 中的部分新字段（如ExternalSecretRewriteMerge、ExternalSecretSyncWindows、sessionTagsPolicy、externalID等演进特性集中在 v1）。

从仓库文档 docs/guides/v1beta1.md 与 docs/introduction/deprecation-policy.md 可以看出，项目维护者持续推进 API 收敛：新功能优先落在external-secrets.io/v1，存量 v1beta1 用户应逐步迁移到 v1。设计动机见 design/001-design-crd-v1beta1.md。

八、如何在仓库中核对每一项字段

由于 spec.md 是代码生成文档（仓库 hack/api-docs 负责生成），核对字段时推荐以下“三重校验”路径：

类型定义：阅读 apis/externalsecrets/v1 下对应*_types.go文件，例如externalsecret_types.go、secretstore_types.go、secretstore_aws_types.go、secretstore_vault_types.go等，字段注释即 spec.md 的原始来源；
CRD 清单：查看 config/crds/bases 下对应 YAML（如externalsecrets.external-secrets.io_externalsecrets.yaml），确认 JSON schema 与校验规则；
校验器与测试：阅读 apis/externalsecrets/v1/externalsecret_validator.go 与测试文件（externalsecret_validator_test.go、secretstore_validator_test.go），理解 Webhook 校验逻辑；端到端用例见 e2e/suites。

结语

docs/api/spec.md是一份覆盖面极广的 API 权威参考——从 ExternalSecret 的data/dataFrom双通道拉取、creationPolicy/deletionPolicy/refreshPolicy三策略矩阵，到 SecretStoreProvider 的四十余种 Provider 配置、PushSecret 的反向推送，再到 Generator 的集群内密钥生成。本文已按“包结构 → Store → ExternalSecret → 集群级资源 → PushSecret → Generator → 版本迁移 → 源码核对”的主线将其完整展开。当你需要编写或审查 ESO 清单文件时，建议以 docs/api/spec.md 查字段语义、以 config/crds/bases 验 schema、以 apis/externalsecrets/v1 的 Go 注释追溯设计意图，三管齐下即可保证配置的准确性与可维护性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析