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 OperatorESO的API 规范spec权威参考指南以仓库中的 docs/api/spec.md 为核心骨架完整梳理external-secrets.io/v1核心 CRDExternalSecret、SecretStore、ClusterSecretStore、ClusterExternalSecret、external-secrets.io/v1alpha1PushSecret 推送能力与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 / ClusterPushSecretPushSecret、ClusterPushSecret 及全部 PushSecret 子类型external-secrets.io/v1beta1Beta 版本已进入弃用流程结构与 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 是集群级资源二者承载相同的specSecretStoreSpec与statusSecretStoreStatus。ExternalSecret 通过spec.secretStoreRef引用它们从而解耦“密钥从哪里来”与“密钥怎么用”。2.2 SecretStoreSpec 核心字段字段类型说明providerSecretStoreProvider必填Provider 专属配置二选一详见下文refreshIntervalmeta/v1.Duration可选Provider 凭据的刷新间隔Golang Duration 字符串如1hcontrollerstring可选指定由哪个 controller 实例处理配合--enable-controller与 ControllerClass 实现多租户隔离retrySettingsSecretStoreRetrySettings可选定义请求重试策略maxRetries、retryInterval等见docs/api/secretstore.md2.3 SecretStoreProviderProvider 专属配置的并集SecretStoreProvider是一个“一字段一 Provider”的并集结构docs/api/spec.md为其列出了数十个可选字段每个字段对应一个 Provider 的完整配置类型云厂商密钥服务awsAWSProvider、azurekvAzureKVProvider、gcpsmGCPSMProvider、oracleOracleProvider、ibmIBMProvider、yandexlockboxYandexLockboxProvider、yandexcertificatemanagerYandexCertificateManagerProvider、volcengineVolcengineProvider、scalewayScalewayProvider、cloudruCloudruSMProvider、nebiusNebiusMysteryboxProviderVault 生态vaultVaultProvider、openbaoOpenBaoProvider、akeylessAkeylessProvider、fortanixFortanixProvider、conjurConjurProviderDevOps / SaaS 平台dopplerDopplerProvider、infisicalInfisicalProvider、onboardbaseOnboardbaseProvider、previderPreviderProvider、passboltPassboltProvider、passworddepotPasswordDepotProvider、secretserverSecretServerProvider、delineaDelineaProvider、keepersecurityKeeperSecurityProvider、senhaseguraSenhaseguraProvider、bitwardensecretsmanagerBitwardenSecretsManagerProvider、ngrokNgrokProvider、pulumiPulumiProvider、beyondtrustBeyondtrustProvider、beyondtrustworkloadcredentialsBeyondtrustWorkloadCredentialsProvider、chefChefProvider、dvlsDVLSProvider代码托管 / GitOpsgithubGithubProvider仅支持写操作即 PushSecret无法从 GitHub 拉取、gitlabGitlabProvider通用 / 基础设施kubernetesKubernetesProvider读取其他集群的 Secret、crdCRDProvider从任意 Kubernetes 资源读取按 API group/version/kind 选择注意读取 core v1 Secret 被有意禁用应改用 Kubernetes Provider、webhookWebhookProvider通用模板化 Webhook、fakeFakeProvider静态键值对多用于测试与本地演示、onepasswordOnePasswordProvider、onepasswordSDKOnePasswordSDKProvider、ovhOvhProvider。说明GithubProvider在 spec 中被明确标注为“仅支持写操作PushSecret且无法从 GitHub 获取密钥”CRDProvider则说明“group 可为空字符串以选择 ConfigMap 等核心资源但读取 core v1 Secret 被有意阻止”。2.4 以 AWSProvider 为例看 Provider 配置结构AWSProvider是 Provider 配置中最具代表性的一个其字段在 spec 中均有完整描述字段类型必填说明serviceAWSServiceType是指定使用哪个 AWS 服务枚举SecretsManager、ParameterStore、CertificateManagerregionstring是Provider 使用的 AWS 区域authAWSAuth否认证信息若不设置AWS SDK 会从环境推断凭据rolestring否Provider 将扮演的 Role ARNadditionalRoles[]string否在扮演最终 Role 之前依序扮演的链式 Role ARN 列表externalIDstring否设置在假定 IAM 角色上的 AWS External IDsessionTags[]*Tag否AWS STS assume role 会话标签transitiveTagKeys[]string否传递性会话标签多规则场景必需sessionTagsPolicySessionTagsPolicy否控制扮演角色时是否及如何附加 STS 会话标签None默认不加、Simple自动附加esoNamespace、esoStoreName、esoStoreKind、Custom在 Simple 基础上追加customSessionTags使用 Simple/Custom 时 IAM 角色必须具备sts:TagSession权限customSessionTagsmap[string]string否SessionTagsPolicyCustom时附加的自定义会话标签secretsManagerSecretsManager否定义与 AWS SecretsManager 交互时的行为prefixstring否为所有取回的值添加前缀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 Secret3.1 资源定义与核心 Spec 字段spec 对 ExternalSecret 的定位是“定义如何从外部 API 获取数据并将其作为 Kubernetes Secrets 提供”见ExternalSecret类型注释。其specExternalSecretSpec字段如下字段类型说明secretStoreRefSecretStoreRef可选引用SecretStore或ClusterSecretStore含kind字段区分二者targetExternalSecretTarget可选定义要创建的 Kubernetes Secret 的蓝图refreshPolicyExternalSecretRefreshPolicy可选刷新策略见下refreshIntervalmeta/v1.Duration可选从 Provider 重新读取值的间隔默认1h0m0ssyncWindowsExternalSecretSyncWindows可选限制周期刷新的时间窗口仅对 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三种刷新策略ExternalSecretRefreshPolicystring别名在 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字段包括字段类型默认值 / 说明namestring默认为 ExternalSecret 的.metadata.namecreationPolicyExternalSecretCreationPolicy默认OwnerdeletionPolicyExternalSecretDeletionPolicy默认RetaintemplateExternalSecretTemplate目标 Secret 的蓝图type、engineVersion、metadata、mergePolicy、data、templateFrommanifestManifestReference改为创建自定义资源如 ConfigMap、CR而非 Secretspec 明确警告这是 Generic target需确保访问策略与加密配置正确immutablebool最终 Secret 是否不可变ExternalSecretCreationPolicy的五个取值spec 有逐项语义说明取值语义CreateOrMerge缺失时创建已存在时合并 data 字段且不设置 ownerReferenceExternalSecret 存在期间被删除的目标会被重建删除 ExternalSecret 后 Secret 保留Merge不创建 Secret仅将 data 字段合并进已有 SecretNone不创建 Secret预留给未来 injector 使用Orphan创建 Secret 但不设置 ownerReferenceExternalSecret 删除后 Secret 被孤立保留Owner创建 Secret 并设置.metadata.ownerReferences指向 ExternalSecret默认值3.4 data 与 dataFrom单键映射与批量拉取data[].ExternalSecretData是“一键一值”的显式映射字段说明secretKeyKubernetes Secret 中存放值的键remoteRef指向远端密钥定义拉取哪个 secretversion/property 等sourceRef允许覆盖值的来源StoreSourceRefremoteRefExternalSecretDataRemoteRef的完整字段字段必填说明key是Provider 中的密钥键必填metadataPolicy否是否拉取 Provider 密钥的 tags/labelsFetch或None默认Noneproperty否当 Provider 值是 map 时选择特定属性如 JSON 字段version否远端密钥版本Provider 支持时conversionStrategy否值转换策略Default/UnicodeExternalSecretConversionStrategydecodingStrategy否解码策略ExternalSecretDecodingStrategy见 docs/guides/decoding-strategy.mddataFrom[].ExternalSecretDataFromRemoteRef用于批量拉取支持四种子模式字段互斥组合字段说明extract从一个 secret 中提取多组键值对不支持sourceRef.Generatorfind基于 tags 或正则查找多个 secret不支持sourceRef.Generatorrewrite对拉取到的 Secret 键做重写支持多个操作按“先到后”分层应用sourceRef指向 store 或 generatorStoreGeneratorSourceRef指向 generator 时不支持 Extract/Findgenerator 返回静态 mapExternalSecretRewrite支持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条件列表与bindingservicebinding.io Provisioned Service 引用。ExternalSecretConditionType只有两个取值Ready已就绪并同步与Deleted已删除。四、ClusterExternalSecret跨命名空间批量生成 ExternalSecretClusterExternalSecretexternal-secrets.io/v1与ClusterSecretStore集群级配套解决“一个外部密钥源分发到多个命名空间”的问题。ClusterExternalSecretSpec在 spec 中完整列出了字段说明externalSecretSpec嵌入的ExternalSecretSpec作为每个命名空间中生成的 ExternalSecret 的模板namespaceSelector/namespaceList选择目标命名空间标签选择器或显式列表refreshInterval重新评估命名空间匹配并生成/回收 ExternalSecret 的间隔maxNamespaces推断单次最多生成的命名空间数上限其状态ClusterExternalSecretStatus含conditions、generatedExternalSecrets已生成的 ExternalSecret 数量、failedNamespacesClusterExternalSecretNamespaceFailure含 namespace 与失败原因等观测字段。完整介绍见 docs/api/clusterexternalsecret.md 与设计文档 design/003-cluster-external-secret-spec.md。五、PushSecret 与 ClusterPushSecretv1alpha1把 Kubernetes Secret 推回 Providerexternal-secrets.io/v1alpha1包承载方向相反的同步能力——将集群内的 Secret 推送到外部 Provider。PushSecretSpec核心字段字段类型说明refreshIntervalmeta/v1.Duration尝试推送的间隔secretStoreRefs[]PushSecretStoreRef目标 Provider 引用列表可同时推送到多个 storeupdatePolicyPushSecretUpdatePolicy如何更新 Provider 中的 SecretdeletionPolicyPushSecretDeletionPolicy删除 ExternalSecret 时如何处理 Provider 中的 SecretselectorPushSecretSelector指定源 Kubernetes Secretdata[]PushSecretData逐键推送规则match匹配源键、conversionStrategy转换策略dataTo[]PushSecretDataTo批量推送规则把源 Secret 的键按match/正则展开为 Provider 条目含override、rewrite、template、metadata等templateExternalSecretTemplate推送内容的模板配套类型还包括PushSecretDataToMatchall/regexp、PushSecretRewrite、PushSecretMetadata、PushSecretRemoteRef、PushSecretSecret、PushSecretStoreRefstoreRef generation以及SyncedPushSecretsMapstatus.syncedPushSecrets记录各 store 的同步结果。PushSecretStatus提供refreshTime、syncedResourceVersion、syncedPushSecrets三个观测字段。最小示例推送到 AWS SecretsManagerapiVersion: 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 中列出了完整的生成器类型包括生成器用途ACRAccessTokenAzure Container Registry 短期访问令牌ECRAuthorizationTokenAWS ECR 授权令牌GCRAccessTokenGoogle Container Registry 访问令牌GitHubAccessTokenGitHub App 安装访问令牌GitLabDeployTokenGitLab Deploy Token 创建Password按规则生成随机密码长度、字符集、数字/符号数量等SSHKey生成 RSA/ECDSA SSH 密钥对UUID生成 UUIDVaultDynamicSecret从 Vault 动态 secret 引擎获取租约凭据Webhook通过自定义 Webhook 生成其他Quay、Cloudsmith、Fake、Grafana、MFA、STS、beyondtrustworkloadcredentials 等典型用法ExternalSecret 的dataFrom[].sourceRef指向generatorRefGeneratorRef含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 注释追溯设计意图三管齐下即可保证配置的准确性与可维护性。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考