forgerock/secret-agent

secret-agent - Kubernetes密钥生成器和管理器

https://pkg.go.dev/badge/github.com/ForgeRock/secret-agent](https://pkg.go.dev/github.com/ForgeRock/secret-agent) https://goreportcard.com/badge/github.com/ForgeRock/secret-agent](https://goreportcard.com/report/github.com/ForgeRock/secret-agent)

!Secret agent logo a go gopher with sunglasses and hawaiian style shirt

secret-agent是一个Kubernetes操作器，用于生成ForgeRock®身份平台所需的密钥。这些密钥可存储在集群内作为Kubernetes密钥，也可存储在云密钥管理器中。

路线图

Secret agent目前已功能完备，未来更新将仅限于错误修复。

Secret agent最初设计用于短期目标，即为运行在Kubernetes上的ForgeRock平台创建和管理密钥。平台密钥管理的长期路线图主要包括：

• 使用ForgeRock的commons secrets API直接与云密钥管理集成（GCP Secret Manager、Vault等）。
• 使用certmanager.io管理证书，cert-manager是Kubernetes证书管理的事实标准。
• 使用云原生技术（如velero.io）或供应商提供的备份服务（如GKE Backup）备份和恢复Kubernetes密钥。

安装

要在Kubernetes环境中安装最新的secret-agent版本，运行：

bash
kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/latest/download/secret-agent.yaml

可通过以下命令安装特定版本的操作器：

bash
SA_VERSION=v0.1.0 kubectl apply -f https://github.com/ForgeRock/secret-agent/releases/download/${SA_VERSION}/secret-agent.yaml

配置

安装操作器后，可通过提供Secret Agent配置（SAC）对象生成新密钥。SAC是secret-agent操作器监控的自定义Kubernetes对象，所有密钥的规范都通过SAC定义。

有关创建SAC的更多信息，请参见Secret Agent配置模式和/或示例部分。

创建SAC文件后，可像其他资源一样推送到集群，例如：

bash
kubectl create -f config/samples/secret-agent_v1alpha1_secretagentconfiguration.yaml

需要注意的是，secret-agent生成的Kubernetes密钥将与SAC位于同一命名空间。如果需要在多个命名空间中使用类似密钥，则每个命名空间需要一个SAC。

使用方法

启用云备份

secret-agent可配置为将所有生成的密钥备份到云提供商的密钥管理器解决方案中。启用此功能后，存储在密钥管理器中的密钥被视为事实来源。

如果配置了云提供商，操作器将尝试从该云提供商加载密钥数据。如果在云提供商的密钥管理器中找到密钥，操作器将使用找到的数据作为Kubernetes密钥数据。仅当在云提供商中未找到密钥数据时，操作器才会生成新密钥。

secret-agent支持以下云提供商：

• Google Secret Manager
• AWS Secrets Manager
• Azure Key Vault

可以在不设置云提供商的情况下运行secret-agent，这在调试或测试应用程序时非常有用。要禁用云提供商支持，将spec.appConfig.secretsManager设置为“none”，但仅当spec.appConfig.createKubernetesObjects设置为true时才允许。

此外，可以将secret-agent配置为仅在密钥管理器中存储密钥，而不创建本地Kubernetes密钥。如果应用程序可以直接访问云密钥管理器，而secret-agent仅用于生成此类密钥，这将非常有用。要实现此目的，将spec.appConfig.createKubernetesObjects设置为false，且spec.appConfig.secretsManager不能设置为"none"。

要在AWS Secrets Manager中获取和存储密钥，用户必须提供具有必要权限的凭证。

使用AWS Secret Manager设置云备份

secret-agent期望通过标准https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials%E5%8F%91%E7%8E%B0%E5%87%AD%E8%AF%81%E3%80%82%E5%8F%AF%E9%80%9A%E8%BF%87%E9%93%BE%E6%8E%A5%E4%B8%AD%E6%8F%8F%E8%BF%B0%E7%9A%84%E5%A4%9A%E7%A7%8D%E6%96%B9%E5%BC%8F%E6%8F%90%E4%BE%9B%E8%BF%99%E4%BA%9B%E5%87%AD%E8%AF%81%E3%80%82

但在AWS内部运行时，首选方法是将serviceAccount附加到部署，并在角色上设置适当的作用域策略。

• 环境变量：

  • AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN
  • AWS_WEB_IDENTITY_TOKEN_FILE -> 这将由IAM控制器为每个正确设置了serviceAccount注解的部署处理

• 共享凭证文件：~/.aws/credentials

• 共享配置文件：~/.aws/config

• EC2实例元数据v2：从169.254.169.254获取凭证

  • 这不太理想，因为节点上的所有pod都将有权访问相同的策略，如果topologySkew未正确隔离不同节点/节点池上的工作负载，可能不是期望的结果

有关如何获取凭证并授予访问AWS Secrets Manager的必要权限，请参阅AWS文档。secret-agent需要读写密钥的权限，可通过允许访问arn:aws:iam::aws:policy/SecretsManagerReadWrite AWS托管策略实现。

在AWS环境外部运行时，可以通过Kubernetes密钥提供自定义凭证。在SAC的spec.appConfig.credentialsSecretName中提供密钥引用。在默认的secret-agent部署中，用户应在操作器所在的命名空间中发布云凭证密钥。可通过更改操作器清单中的运行时参数--cloud-secrets-namespace=[NS_NAME]来更改目标命名空间。如果完全省略此参数，命名空间将默认为每个SAC的命名空间。

将这些凭证发布到Kubernetes密钥后，下一步是使用SecretAgentConfiguration配置AWS Secret Manager。

例如，以下配置针对us-east-1区域的AWS Secret Manager：

yaml
apiVersion: secret-agent.secrets.forgerock.io/v1alpha1
kind: SecretAgentConfiguration
metadata:
  name: standard-forgerock-example
  namespace: test-sa
spec:
  appConfig:
    createKubernetesObjects: true
    credentialsSecretName: cloud-credentials [**可选**]
    secretsManager: AWS
    awsRegion: us-east-1

AWS可选：spec.appConfig.credentialsSecretName中引用的cloud-credentials密钥如下所示：

yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cloud-credentials
  namespace: test-sa
data:
  AWS_ACCESS_KEY_ID: QU....[base64编码的密钥].....GY=
  AWS_SECRET_ACCESS_KEY: cRB.....[base64编码的访问密钥].......BB==

注意：AWS支持的最大密钥大小为65Kb 更多信息，请参见AWS文档。

使用GCP Secret Manager设置云备份

secret-agent期望通过标准GCP机制发现凭证。可通过多种方式提供这些凭证，包括：

• 工作负载身份（推荐用于GKE部署）
• 凭证文件（用户账户或服务账户）

有关如何创建具有访问GCP Secrets Manager必要权限的服务账户，请参阅GCP文档。secret-agent需要读写密钥的权限，可通过为提供的服务账户分配Secret Manager Admin角色实现。

工作负载身份

工作负载身份是从GKE中运行的应用程序访问Google Cloud服务的推荐方式。有关如何启用工作负载身份，请参见GCP文档。

通常，用户创建一个附加了适当角色的Google Cloud服务账户，并在其GKE集群中启用工作负载身份。Kubernetes服务账户在secret-agent部署期间已创建。

运行以下命令为secret-agent部署启用工作负载身份：

bash
PROJECTID=myproject #GCP项目ID
GSA_NAME=mygcpserviceaccount #GCP服务账户名称
# 创建GCP IAM策略绑定
gcloud iam service-accounts add-iam-policy-binding --role roles/iam.workloadIdentityUser --member "serviceAccount:${PROJECTID}.svc.id.goog[secret-agent-system/secret-agent-controller-manager]" ${GSA_NAME}@${PROJECTID}.iam.gserviceaccount.com
# 为Kubernetes服务账户添加注解
kubectl -n secret-agent-system annotate serviceaccounts secret-agent-controller-manager iam.gke.io/gcp-service-account=${GSA_NAME}@${PROJECTID}.iam.gserviceaccount.com

注意：要使用工作负载身份，不应提供spec.appConfig.credentialsSecretName。如果提供了凭证，secret-agent将使用提供的凭证。

凭证文件

通过Kubernetes密钥的GOOGLE_CREDENTIALS_JSON数据键向操作器提供凭证。此密钥的名称在spec.appConfig.credentialsSecretName中提供。在默认的secret-agent部署中，操作器将在其自己的命名空间中查找具有提供名称的密钥。用户可通过设置参数--cloud-secrets-namespace=[NS_NAME]指定不同的命名空间。如果省略此参数，操作器的默认行为是从与SAC相同的命名空间获取凭证。

spec.appConfig.credentialsSecretName中引用的cloud-credentials密钥如下所示：

yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cloud-credentials
  namespace: test-sa
data:
  GOOGLE_CREDENTIALS_JSON: .....[base64编码的服务账户JSON].....

配置GCP Secret Manager

使用工作负载身份或凭证文件向secret-agent提供必要凭证后，下一步是使用SecretAgentConfiguration配置GCP Secret Manager。

例如，以下配置针对example-project-id项目的GCP Secret Manager：

yaml
apiVersion: secret-agent.secrets.forgerock.io/v1alpha1
kind: SecretAgentConfiguration
metadata:
  name: standard-forgerock-example
  namespace: test-sa
spec:
  appConfig:
    createKubernetesObjects: true
    credentialsSecretName: cloud-credentials [**使用工作负载身份时跳过**]
    secretsManager: GCP
    gcpProjectID: example-project-id

使用Azure Key Vault设置云备份

注意：Azure Key Vault的API响应时间较长，会延迟密钥创建。如果使用Azure Key Vault，建议在部署应用程序之前提前部署SAC。

secret-agent使用通过两种不同方法获取的凭证：Azure托管标识（推荐用于Azure部署）或显式凭证。显式凭证在SAC规范spec.appConfig.credentialsSecretName引用的密钥中配置。SAC的Azure配置示例：

yaml
apiVersion: secret-agent.secrets.forgerock.io/v1alpha1
kind: SecretAgentConfiguration
metadata:
  name: standard-forgerock-example
  namespace: test-sa
spec:
  appConfig:
    createKubernetesObjects: true
    credentialsSecretName: cloud-credentials [**可选**]
    secretsManager: Azure
    azureVaultName: secret-agent-vault

如果credentialsSecretName中未提供密钥，操作器的Azure客户端将尝试使用托管标识进行身份验证。有关更多信息，请参见Azure的文档。这是Azure AKS中部署的推荐配置。

否则，可在credentialsSecretName密钥中显式设置凭证。使用基于RBAC策略的Key Vault时，与密钥关联的服务主体需要Key Vault Secrets Officer角色。

凭证密钥示例：

yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: cloud-credentials
data:
  # AZURE_TENANT_ID: # 可选：使用Azure Key Vault时更新
  # AZURE_CLIENT_ID: # 可选：使用Azure Key Vault时更新
  # AZURE_CLIENT_SECRET: # 可选：使用Azure Key Vault时更新

注意：Azure支持的最大密钥大小为25Kb 更多信息，请参见Azure文档。

导入自定义密钥

除生成密钥外，secret-agent允许用户导入自己的密钥。这对于可被SAC中其他密钥引用的证书和证书颁发机构等非常有用。例如，用户可以导入组织的CA，并使用它签署secret-agent生成的证书。

只需提供与SAC中描述的名称和密钥名称相同的Kubernetes密钥。需要注意的是，如果启用了云备份功能，则要导入的密钥必须通过云管理器的密钥管理器提供。如果启用了云备份，secret-agent将忽略本地密钥。

云备份的命名约定

secret-agent使用命名约定在云密钥管理器中存储和读取密钥。通常，名称遵循以下格式：

bash
$prefix-$secretName-$keyName [如果提供secretsManagerPrefix]
$namespace-$secretName-$keyName [如果未提供前缀]

使用SecretsManagerPrefix写入密钥管理器时不使用命名空间，确保前缀唯一。

由于云提供商限制，密钥名称中的所有/、.和_字符在访问云密钥管理器时都替换为-。

例如，考虑以下密钥代理配置：

yaml
---
apiVersion: secret-agent.secrets.forgerock.io/v1alpha1
kind: SecretAgentConfiguration
metadata:
  name: forgerock-sac
  namespace: dev
spec:
  appConfig:
    secretsManagerPrefix: "devCluster"
    awsRegion: us-east-1
    secretsManager: AWS
  secrets:
  - name: ds-passwords
    keys:
      - name: dirmanager.pw
        type: password

由于secretsManagerPrefix，SAC生成的密钥将在AWS Secret Manager中存储为devCluster-ds-passwords-dirmanager-pw。相同的名称适用于其他云提供商。

某些密钥类型需要备份多个密钥。此类密钥类型需要单独存储的公钥和私钥组件。ca、keypair、ssh和keytool密钥类型就是这种情况。这些密钥使用上述命名约定，并在之前构建的主名称后附加后缀。

在上面的表格中，$NAME遵循本节顶部的约定。

示例

我们提供了一个示例SAC，展示了secret-agent的所有功能。请参见samples文件夹。

Secret Agent配置模式

以下表格列出了Secret Agent配置（SAC）的可配置参数及其默认值。

应用配置（App Config）

密钥配置（Secret Config）

密钥详情配置（Key Config）

| 参数 |