在 GCP Secret Manager 中管理密钥

GCP Secret Manager 是一项完全托管的服务，用于存储、管理和访问敏感信息，如 API 密钥、密码和证书。它允许你通过加密集中存储密钥，自动进行版本控制，并使用 Google Cloud 的 IAM 策略控制访问。

本指南将向你展示如何使用 GCP Secret Manager 管理身份认证插件 key-auth 的用户凭证，以及如何在 APISIX 中检索密钥。

前置条件

• 安装 Docker。
• 安装 cURL 以向服务发送请求进行验证。
• 按照 快速入门教程 在 Docker 中启动一个新的 APISIX 实例。
• 拥有一个 GCP 帐户 并启用 Secret Manager。
• 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 ADMIN_API_KEY。请在 deployment.admin.admin_key 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

在 GCP Secret Manager 中创建密钥

在本节中，你将创建一个密钥来存储消费者 john 的 key-auth 身份认证密钥。

导航到控制台中的 GCP Secret Manager 并创建一个密钥。填写名称 apisix-john-key-auth 和密钥 john-key：

查看其余信息并完成密钥创建。你应该在 GCP Secret Manager 中看到列出的密钥：

获取 GCP 访问凭证

按照 服务帐号凭证 文档在 GCP 中创建一个服务帐号，为该帐号分配 Secret Manager Secret Accessor 角色，并为该帐号创建凭证。

你应该会看到生成并下载到你机器上的 JSON 文件，其中包含凭证，类似于以下内容：

{
  "type": "service_account",
  "project_id": "apisix-project",
  "private_key_id": "f039bb20b2xxxxxxxxxb43cb7132axxxxxx1f165",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "apisix-secret-manager@apisix-project.iam.gserviceaccount.com",
  "client_id": "115458xxxxxxx68702206",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/apisix-secret-manager%40apisix-project.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

按需配置私有 CA

APISIX 默认使用系统信任存储，因此访问公共 Google Cloud Secret Manager 端点无需更改信任存储。请保持 ssl_verify 启用。

如果网关必须信任私有 CA，请将当前配置和 Docker 镜像中的系统 CA 证书包复制到宿主机，并保留配置备份：

docker cp apisix-quickstart:/usr/local/apisix/conf/config.yaml ./config.yaml
docker cp apisix-quickstart:/etc/ssl/certs/ca-certificates.crt \
  ./system-ca-bundle.pem
cp ./config.yaml ./config.yaml.backup

将私有 CA 追加到系统根证书中，使 APISIX 继续信任公共端点：

cat ./system-ca-bundle.pem ./private-ca.pem > ./combined-ca-bundle.pem

在现有 apisix.ssl 映射下添加组合证书包的路径。请将此片段合并到完整配置中，而不要替换 config.yaml：

apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/conf/combined-ca-bundle.pem

将 CA 证书包和候选配置复制到容器中。重新加载 APISIX 之前，请验证完整配置：

docker cp ./combined-ca-bundle.pem \
  apisix-quickstart:/usr/local/apisix/conf/combined-ca-bundle.pem
docker cp ./config.yaml apisix-quickstart:/usr/local/apisix/conf/config.yaml
docker exec apisix-quickstart apisix test && \
  docker exec apisix-quickstart apisix reload

如果验证失败，请先恢复备份，再进行其他更改：

docker cp ./config.yaml.backup apisix-quickstart:/usr/local/apisix/conf/config.yaml

在 APISIX 中配置密钥

使用在 上一步 中获取的访问凭证，将 GCP Secret Manager 配置为 john 的密钥提供者：

curl "http://127.0.0.1:9180/apisix/admin/secrets/gcp/john" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "auth_config": {
    "client_email": "apisix-secret-manager@apisix-project.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "project_id": "apisix-project"
  },
  "ssl_verify": true
}'

❶ 替换为你的客户电子邮件。

❷ 替换为你的私钥。

❸ 替换为你的项目 ID。

❹ 启用 SSL 验证（默认）。

创建消费者及其凭证

创建消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "username": "john"
}'

为消费者 john 配置 key-auth 凭证，以从密钥提供者获取密钥：

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id": "cred-john-key-auth",
  "plugins": {
    "key-auth": {
      "key": "$secret://gcp/john/apisix-john-key-auth"
    }
  }
}'

创建带有身份认证的路由

创建一个示例路由并启用 key-auth 插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id": "key-auth-route",
  "uri": "/anything",
  "plugins": {
    "key-auth": {}
  },
  "upstream" : {
    "nodes": {
    "httpbin.org": 1
    }
  }
}'

验证

使用有效凭证向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: john-key'

你应该收到 HTTP/1.1 200 OK 响应。

使用无效凭证向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: wrong-key'

你应该收到 HTTP/1.1 401 Unauthorized 响应。

下一步

你现在已经了解了如何配置 APISIX 以从 GCP Secret Manager 获取密钥。

除了 GCP Secret Manager，APISIX 还支持与 HashiCorp Vault 和 AWS Secrets Manager 集成进行密钥管理。