跳转到内容
CrewAI 中文文档

Google Cloud Secret Manager

概览

Section titled “概览”

本指南会带你完成将 Google Cloud Secret Manager 配置为 CrewAI Platform 组织的密钥 provider 的全过程，使用的是 service account credentials。完成后，CrewAI Platform 就能够读取你 Google Cloud project 中存放的密钥，并在运行时将其注入为环境变量值。

前提条件

Section titled “前提条件”

第 1 步 - 创建 Service Account

Section titled “第 1 步 - 创建 Service Account”

service account 是 CrewAI Platform 在 GCP 侧进行认证时使用的身份。

在 IAM & Admin → Service Accounts console 中，点击 Create Service Account。

  • Service account name: crewai-secrets-reader
  • Service account ID: 会根据名称自动填充（例如 crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com）
  • Description (optional): “Read-only access to Secret Manager for CrewAI Platform”

点击 Create and Continue。在此屏幕上跳过可选的 grants - 你会在第 2 步附加 role。然后点击 Done。

完整细节请参见 GCP 文档：Create service accounts。

第 2 步 - 授予 Secret Manager 访问权限

Section titled “第 2 步 - 授予 Secret Manager 访问权限”

CrewAI Platform 需要在你的 project 中列出并读取 secrets 的权限。你可以使用两种 scope - 为了简单可选 project-wide，为了最小权限可选 per-secret。

Project-wide (simpler)

在 IAM console 中点击 Grant Access，然后：

  • New principals: 第 1 步中 service account 的 email。
  • Role: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)。

点击 Save。

或者通过 gcloud：

Terminal window
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"
Per-secret (least privilege)

只在 CrewAI Platform 应该访问的具体 secrets 上授予该 role。对每个 secret 重复执行：

Terminal window
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
  --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor" \
  --project=YOUR_PROJECT_ID

或者在控制台中：打开 Secret Manager 中的每个 secret，点击右侧面板的 Permissions，并为 service account 授予 Secret Manager Secret Accessor。

第 3 步 - 创建 Service Account Key

Section titled “第 3 步 - 创建 Service Account Key”

在 IAM & Admin → Service Accounts console 中打开第 1 步中的 service account。

  • 点击 Keys 标签页。
  • 点击 Add Key → Create new key。
  • Key type: JSON。
  • 点击 Create。浏览器会下载一个 JSON 文件 - 请妥善保管；它无法重新下载。

或者通过 gcloud：

Terminal window
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
  --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com

第 4 步 - 在 CrewAI Platform 中添加凭据

Section titled “第 4 步 - 在 CrewAI Platform 中添加凭据”

在 CrewAI Platform 中，进入 Settings → Secret Provider Credentials，然后点击 Add Credential。

填写表单：

  • Name: 描述性名称，例如 gcp-prod。
  • Provider: Google Cloud Secret Manager。
  • Project ID: 你的 GCP project ID（例如 my-crewai-prod）。
  • Service Account JSON: 粘贴第 3 步下载的 JSON 文件全部内容。 -（可选）勾选 Set as default credential for this provider。环境变量如果引用 GCP secrets 但没有显式指定凭据，就会使用默认凭据。

点击 Create。

第 5 步 - 在 GCP 中至少创建一个 Secret

Section titled “第 5 步 - 在 GCP 中至少创建一个 Secret”

如果你还没有在 GCP Secret Manager 中创建 secrets，请现在创建一个，以便在第 6 步验证连接。

在 Secret Manager console 中，点击 Create secret。

  • Name: 唯一名称，例如 openai-api-key。
  • Secret value: 粘贴原始值或上传文件。
  • 除非你有特殊要求，否则保留 rotation、replication 和其他设置的默认值。

点击 Create secret。

或者通过 gcloud：

Terminal window
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
  --data-file=- \
  --project=YOUR_PROJECT_ID \
  --replication-policy=automatic

完整细节请参见 GCP 文档：Create a secret。

第 6 步 - 测试连接

Section titled “第 6 步 - 测试连接”

回到 CrewAI Platform，在 Secret Provider Credentials 页面找到你刚创建的凭据，并点击 Test Connection。

成功提示会确认 CrewAI Platform 能够对 GCP 进行认证，并从你的 project 中读取 secrets。

如果测试失败，请检查最常见的原因：

症状可能原因
PERMISSION_DENIED on listing secretsservice account 缺少 roles/secretmanager.secretAccessor，或者你将其限定到了 per-secret（因此没有授予 list）。重新检查第 2 步。
PERMISSION_DENIED on secretmanager.secrets.access原因同上，但针对的是某个具体 secret。确认 service account 对该 secret 拥有 accessor role。
unauthorized_client / invalid_grant粘贴的 Service Account JSON 无效、已过期，或者来自已删除的 service account。重新创建 key（第 3 步）并重新粘贴。
Project ID does not matchCrewAI Platform 中的 Project ID 字段与拥有该 service account / secrets 的 project 不一致。重新检查第 4 步。
API not enabled该 project 尚未启用 Secret Manager API。请参见前提条件。

下一步

Section titled “下一步”

现在 GCP 已连接，前往 Using the Secrets Manager，以：

  • 为组织成员授予使用（或管理）Secrets Manager 的正确权限。
  • 从 CrewAI Platform 环境变量中引用你的 GCP secrets。

如果你想要rotation-aware 的密钥，并且希望在不重新部署的情况下传播，请切换到 GCP Workload Identity Federation - 同一个密钥存储，不用静态凭据，密钥会在每次 kickoff 时获取。