External Secrets Operator 集成 ngrok Provider使用 PushSecret 向 ngrok Vault 同步 Kubernetes 密钥【免费下载链接】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官方 ngrok Provider 文档为核心讲解如何将 Kubernetes Secret 单向推送到 ngrok 的 Secrets for Traffic Policy 密钥库Vault涵盖 SecretStore/ClusterSecretStore 配置、PushSecret 编排、描述与元数据自定义并结合仓库源码深入说明其只写WriteOnly能力、认证解析、Vault 解析与自动校验和checksum等底层机制帮助读者在流量策略中安全复用集群内已有的密钥数据。ngrok Provider 概览为流量策略Traffic Policy供应密钥External Secrets Operator 通过 ngrok Provider 与 ngrok 集成将 Kubernetes Secret 同步到 ngrok 的Secrets for Traffic Policy功能所使用的密钥库中。ngrok 流量策略Traffic Policy可以在请求转发链中引用这些密钥例如向上游服务注入认证头而 ESO 的作用就是让这些密钥的单一事实来源仍然留在 Kubernetes 集群内由集群统一管理、轮换与审计。需要特别注意的是从源码看ngrok Provider 目前是**只写WriteOnly**的在 providers/v1/ngrok/provider.go 中Capabilities()返回esv1.SecretStoreWriteOnly相应地在 providers/v1/ngrok/client.go 中GetSecret、GetSecretMap、GetAllSecrets三个读方法均直接返回errWriteOnlyOperationsnot implemented - the ngrok provider only supports write operations。因此只支持通过PushSecret向 ngrok 推送密钥不支持通过ExternalSecret从 ngrok 拉取密钥这意味着SecretStore的read能力检查对该 Provider 不适用配置层面只需关注推送所需的认证与目标 Vault。前置准备ngrok API Key 与 Vault在开始配置前需要先完成以下 ngrok 侧的准备在 ngrok 控制台创建API Key用于调用 ngrok API 认证参见 ngrok API 的 authentication 文档在 ngrok 中创建或准备一个Vault用于存放要推送的密钥将 API Key 预先放入 Kubernetes Secret作为 Provider 的认证凭据来源示例中为名为ngrok-credentials的 Secret 中的api-key字段。ngrok API 的默认入口为https://api.ngrok.com若是企业版 ngrok 实例可自定义 API URL。配置 SecretStore / ClusterSecretStore验证ngrokProvider 已出现在KindSecretStore或ClusterSecretStore中。其中auth与vault两个属性为必填apiUrl为可选默认值为https://api.ngrok.com。参考官方示例 docs/snippets/ngrok-secret-store.yamlapiVersion: external-secrets.io/v1 kind: SecretStore metadata: name: ngrok spec: provider: ngrok: # apiURL: Default https://api.ngrok.com, for enterprise ngrok instances uncomment and use your API URL. auth: apiKey: secretRef: name: ngrok-credentials key: api-key vault: name: my-vault # Name of the ngrok vault to use for storing secrets配置字段详解对照 API 类型定义 apis/externalsecrets/v1/secretstore_ngrok_types.goProvider 配置由三个部分构成字段路径必填说明apiUrlspec.provider.ngrok.apiUrl否ngrok API 地址默认https://api.ngrok.comkubebuilder 默认值见kubebuilder:defaulthttps://api.ngrok.com企业版实例可覆盖auth.apiKey.secretRefspec.provider.ngrok.auth.apiKey.secretRef是引用包含 ngrok API Key 的 Kubernetes Secretname/key可选namespacevault.namespec.provider.ngrok.vault.name是要同步密钥的目标 ngrok Vault 名称其中auth结构带有kubebuilder:validation:MinProperties1/MaxProperties1约束即目前只支持apiKey这一种认证方式。配置校验逻辑源码视角在 providers/v1/ngrok/provider.go 的getConfig中配置校验顺序依次为Store 及其spec、spec.provider必须存在spec.provider.ngrok必须存在否则返回errInvalidNgrokProvapiUrl为空时填充默认值非空时必须能通过url.Parse否则返回errInvalidAPIURLauth.apiKey必须配置否则返回errInvalidAuthAPIKeyRequiredvault.name不能为空否则返回errMissingVaultName。命名空间解析规则与 ClusterSecretStore 注意事项NewClient中有一个容易被忽略的限制providers/v1/ngrok/provider.go如果使用ClusterSecretStore且auth.apiKey.secretRef未显式指定namespace会直接返回错误errClusterStoreRequiresNamespacecluster store requires namespace。原因是doesConfigDependOnNamespace检测到该引用未携带命名空间providers/v1/ngrok/provider.go而 ClusterSecretStore 是集群级资源没有默认命名空间可推断。因此使用SecretStore命名空间级时secretRef默认从 Store 所在命名空间解析使用ClusterSecretStore时必须在secretRef中显式写明namespace。同时NewClient在初始化时会通过getVaultByName按名称查找 Vault 并缓存其 ID若 Vault 不存在则报错vault %q not foundproviders/v1/ngrok/provider.go相当于在客户端创建阶段就验证了目标 Vault 可达。创建 PushSecret 向 ngrok 推送密钥要将 Kubernetes Secret 与 ngrok 中的外部密钥同步需要创建一个KindPushSecret的资源。参考官方示例 docs/snippets/ngrok-push-secret.yamlapiVersion: external-secrets.io/v1alpha1 kind: PushSecret metadata: name: ngrok-push-secret-example spec: deletionPolicy: Delete refreshInterval: 10m0s # Refresh interval for which push secret will reconcile secretStoreRefs: # A list of secret stores to push secrets to - name: ngrok # Must match SecretStore on the cluster kind: SecretStore selector: secret: name: SECRET_NAME # Source Kubernetes secret to be pushed data: - match: # The key in the Kubernetes secret to push. Leave empty to push all keys, JSON encoded. # secretKey: secretKey: MY_K8S_SECRET_KEY remoteRef: remoteKey: MY_NGROK_SECRET_NAME # The name of the secret in the ngrok vault关键字段说明字段说明spec.deletionPolicy当 PushSecret 被删除时对远端密钥的处理策略。示例使用Delete即删除 ngrok 侧对应的密钥spec.refreshIntervalPushSecret 的调谐reconcile间隔示例为10m0s用于周期性地比对并同步集群与 ngrok 之间的密钥差异spec.secretStoreRefs目标 SecretStore 引用列表name必须与集群中已创建的 SecretStore 名称一致kind为SecretStore也可使用ClusterSecretStorespec.selector.secret.name源 Kubernetes Secret 的名称SECRET_NAME即要被推送的数据来源spec.data[].match.secretKey源 Kubernetes Secret 中要推送的键名留空注释掉的secretKey: 表示把整个 Secret 的所有键以 JSON 编码后整体推送spec.data[].match.remoteRef.remoteKey密钥在 ngrok Vault 中的名称推送行为的源码实现在 providers/v1/ngrok/client.go 的PushSecret方法中实际流程如下验证 Vault 名称与 ID 一致性调用verifyVaultNameStillMatchesID若 Vault 被删除或重命名则重新按名称解析 IDrefreshVaultID取值指定secretKey时直接从secret.Data中取对应键的值未指定时用json.Marshal(secret.Data)将整个 Secret 数据编码为 JSON计算校验和对取值结果计算 SHA-256并写入推送元数据中的_sha256键详见下文元数据一节存在性判断与写操作通过getSecretByVaultIDAndName判断密钥是否已存在——不存在则调用Createngrok.SecretCreateVaultID、Name、Value、Metadata、Description已存在则调用Update更新值、元数据与描述。此外还实现了两个配套方法SecretExistsproviders/v1/ngrok/client.go用于判断远端密钥是否存在DeleteSecretproviders/v1/ngrok/client.go按引用删除远端密钥若 Vault 或密钥本身已不存在则视为删除成功幂等。自定义 ngrok 密钥的描述与元数据PushSecret Metadata除了推送密钥值本身你还可以控制密钥在 ngrok 中的description描述与metadata元数据。参考官方示例 docs/snippets/ngrok-push-secret-with-metadata.yamlapiVersion: external-secrets.io/v1alpha1 kind: PushSecret metadata: name: ngrok-push-secret-example spec: deletionPolicy: Delete refreshInterval: 10m0s # Refresh interval for which push secret will reconcile secretStoreRefs: # A list of secret stores to push secrets to - name: ngrok # Must match SecretStore on the cluster kind: SecretStore selector: secret: name: SECRET_NAME # Source Kubernetes secret to be pushed data: - match: # The key in the Kubernetes secret to push. Leave empty to push all keys, JSON encoded. # secretKey: secretKey: MY_K8S_SECRET_KEY remoteRef: remoteKey: MY_NGROK_SECRET_NAME # The name of the secret in the ngrok vault metadata: apiVersion: kubernetes.external-secrets.io/v1alpha1 kind: PushSecretMetadata spec: # See https://ngrok.com/docs/api/resources/secrets/#parameters # We currently support customizing the description and metadata for the secret. description: This is a secret for the API credentials # Metadata for the secret in the ngrok vault. This will be merged with auto-generated metadata. metadata: environment: production team: devopsMetadata 字段说明字段说明metadata.apiVersion/metadata.kind固定为kubernetes.external-secrets.io/v1alpha1与PushSecretMetadata用于标识元数据结构spec.description密钥在 ngrok API 中的描述文本对应 ngrok Secrets API 的description参数spec.metadata附加到 ngrok 密钥上的自定义键值对会与自动生成的元数据合并merge后写入自动元数据与默认值源码视角在 providers/v1/ngrok/client.go 的parseAndDefaultMetadata中默认描述为Managed by External Secrets Operator常量defaultDescription见 providers/v1/ngrok/client.go只有用户在PushSecretMetadata.spec.description中显式提供描述时才会覆盖元数据解析复用runtime/esutils/metadata包metadata.ParseMetadataParameters这与仓库中其他支持 PushSecret Metadata 的 Provider如 AWS、Azure Key Vault 等保持一致推送时会在用户提供的元数据之上追加_sha256键值为本次推送值的 SHA-256 十六进制摘要providers/v1/ngrok/client.go。该自动元数据可用于审计或后续比对密钥内容是否发生变化若用户未提供任何元数据块则使用默认描述 空元数据的组合此时_sha256仍会被追加。PushSecretMetadataSpec结构定义在 providers/v1/ngrok/client.go包含descriptionstring与metadatamap[string]string两个字段。使用 ClusterSecretStore 推送ngrok Provider 同样支持集群级ClusterSecretStore。只需将上文 SecretStore 清单的kind改为ClusterSecretStore并确保auth.apiKey.secretRef中显式指定namespace见上文命名空间解析规则例如apiVersion: external-secrets.io/v1 kind: ClusterSecretStore metadata: name: ngrok spec: provider: ngrok: auth: apiKey: secretRef: name: ngrok-credentials namespace: external-secrets # 必须显式指定ClusterSecretStore 无法推断命名空间 key: api-key vault: name: my-vault随后在 PushSecret 的secretStoreRefs中将kind设为ClusterSecretStore、name设为对应的集群级 Store 名称即可。Provider 注册与构建约束ngrok Provider 通过 pkg/register/ngrok.go 注册到 ESO 中其文件头部带有构建标签//go:build ngrok || all_providers这意味着编译 ESO 控制器时需要通过ngrok或all_providers构建标签显式启用该 Providerregister包中其他 Provider 也遵循相同的按需编译模式。注册时同时传入了ngrok.NewProvider()Provider 实例实现esv1.Provider接口ngrok.ProviderSpec()Provider 的 Spec 结构esv1.SecretStoreProvider{Ngrok: esv1.NgrokProvider{}}ngrok.MaintenanceStatus()维护状态为MaintenanceStatusMaintained受维护表明该 Provider 处于官方持续维护中。在 CRD 快照 tests/snapshot/secretstore-v1.yaml 中也可以看到生成的字段骨架ngrok下的apiUrl默认https://api.ngrok.com、auth.apiKey.secretRefkey/name/namespace与vault.name与上文配置表格一一对应。测试与验证仓库为 ngrok Provider 提供了完整的单元测试与 fake 客户端providers/v1/ngrok/provider_test.go覆盖NewClient、配置解析与校验如缺少 API Key、缺少 Vault 名称、非法 API URL、ClusterSecretStore 命名空间依赖、ValidateStore等逻辑测试中通过newTestNgrokClusterSecretStore/newTestNgrokSecretStore构造不同形态的 Storeproviders/v1/ngrok/client_test.go覆盖PushSecret创建与更新路径、指定 key / 全量 JSON 推送、校验和与元数据合并、SecretExists、DeleteSecret等客户端行为providers/v1/ngrok/fake/fake.go为VaultClient与SecretsClient提供内存版 fake 实现用于在测试中模拟 ngrok API。你可以在本地完成配置验证的两种途径单元测试进入 providers/v1/ngrok 目录执行go test ./...验证 Provider 与客户端逻辑端到端演练按照上述 YAML 清单在集群中创建 API Key Secret、SecretStore 与 PushSecret然后观察 PushSecret 的 status/事件确认密钥成功出现在 ngrok Vault 中。限制与注意事项只支持推送ngrok Provider 是 WriteOnly 能力ExternalSecret拉取、GetAllSecrets等读取能力均未实现目标 Vault 必须预先存在NewClient会按名称查找 Vault不存在则初始化失败Vault 在运行期被删除时verifyVaultNameStillMatchesID会触发重新解析此时若仍不存在推送会报错ClusterSecretStore 必须显式指定 secretRef 的命名空间否则创建客户端即报错元数据为合并语义用户提供的metadata会与自动生成的_sha256合并后整体写入 ngrok描述默认值为Managed by External Secrets Operator可被覆盖企业版 API URL非默认 ngrok API 地址需通过spec.provider.ngrok.apiUrl配置构建期启用使用自建镜像时需以ngrok或all_providers构建标签编译否则该 Provider 不会注册参见 pkg/register/ngrok.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），仅供参考