diff --git a/docs/en/latest/terminology/secret.md b/docs/en/latest/terminology/secret.md index bc233f3d9ce1..cd47bd8b0b8d 100644 --- a/docs/en/latest/terminology/secret.md +++ b/docs/en/latest/terminology/secret.md @@ -38,7 +38,8 @@ Its working principle is shown in the figure: APISIX currently supports storing secrets in the following ways: - [Environment Variables](#use-environment-variables-to-manage-secrets) -- [HashiCorp Vault](#use-vault-to-manage-secrets) +- [HashiCorp Vault](#use-hashicorp-vault-to-manage-secrets) +- [GCP Secrets Manager](#use-gcp-secrets-manager-to-manage-secrets) You can use APISIX Secret functions by specifying format variables in the consumer configuration of the following plugins, such as `key-auth`. @@ -133,7 +134,7 @@ Using HashiCorp Vault to manage secrets means that you can store secrets informa $secret://$manager/$id/$secret_name/$key ``` -- manager: secrets management service, could be the HashiCorp Vault, AWS, etc. +- manager: secrets management service, could be the HashiCorp Vault, AWS, GCP etc. - id: APISIX Secrets resource ID, which needs to be consistent with the one specified when adding the APISIX Secrets resource - secret_name: the secret name in the secrets management service - key: the key corresponding to the secret in the secrets management service @@ -190,3 +191,56 @@ curl http://127.0.0.1:9180/apisix/admin/consumers \ ``` Through the above two steps, when the user request hits the `key-auth` plugin, the real value of the key in the Vault will be obtained through the APISIX Secret component. + +## Use GCP Secrets Manager to manage secrets + +Using the GCP Secrets Manager to manage secrets means you can store the secret information in the GCP service, and reference it using a specific format of variables when configuring plugins. APISIX currently supports integration with the GCP Secrets Manager, and the supported authentication method is [OAuth 2.0](https://developers.google.com/identity/protocols/oauth2?hl=zh-cn). + +### Reference Format + +``` +$secret://$manager/$id/$secret_name/$key +``` + +The reference format is the same as before: + +- manager: secrets management service, could be the HashiCorp Vault, AWS, GCP etc. +- id: APISIX Secrets resource ID, which needs to be consistent with the one specified when adding the APISIX Secrets resource +- secret_name: the secret name in the secrets management service +- key: the key corresponding to the secret in the secrets management service + +### Required Parameters + +| Name | Required | Default | Description | +|-------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| auth_config | True | | Either `auth_config` or `auth_file` must be provided. | +| auth_config.client_email | True | | Email address of the Google Cloud service account. | +| auth_config.private_key | True | | Private key of the Google Cloud service account. | +| auth_config.project_id | True | | Project ID in the Google Cloud service account. | +| auth_config.token_uri | True | https://oauth2.googleapis.com/token | Token URI of the Google Cloud service account. | +| auth_config.entries_uri | False | https://secretmanager.googleapis.com/v1/ | The API access endpoint for the Google Secrets Manager. | +| auth_config.scopes | False | https://www.googleapis.com/auth/cloud-platform | Access scopes of the Google Cloud service account. See [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes) | +| auth_file | True | | Path to the Google Cloud service account authentication JSON file. Either `auth_config` or `auth_file` must be provided. | +| ssl_verify | False | true | When set to `true`, enables SSL verification as mentioned in [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | + +You need to configure the corresponding authentication parameters, or specify the authentication file through auth_file, where the content of auth_file is in JSON format. + +### Example + +Here is a correct configuration example: + +``` +curl http://127.0.0.1:9180/apisix/admin/secrets/gcp/1 \ +-H "X-API-KEY: $admin_key" -X PUT -d ' +{ + "auth_config" : { + "client_email": "email@apisix.iam.gserviceaccount.com", + "private_key": "private_key", + "project_id": "apisix-project", + "token_uri": "https://oauth2.googleapis.com/token", + "entries_uri": "https://secretmanager.googleapis.com/v1/", + "scopes": "https://www.googleapis.com/auth/cloud-platform" + } +}' + +``` diff --git a/docs/zh/latest/terminology/secret.md b/docs/zh/latest/terminology/secret.md index 100a44475eb3..0392feb8b0a8 100644 --- a/docs/zh/latest/terminology/secret.md +++ b/docs/zh/latest/terminology/secret.md @@ -39,6 +39,7 @@ APISIX 目前支持通过以下方式存储密钥： - [环境变量](#使用环境变量管理密钥) - [HashiCorp Vault](#使用-vault-管理密钥) +- [GCP Secrets Manager](#使用-gcp-secrets-manager-管理密钥) 你可以在以下插件的 consumer 配置中通过指定格式的变量来使用 APISIX Secret 功能，比如 `key-auth` 插件。 @@ -134,7 +135,7 @@ curl http://127.0.0.1:9180/apisix/admin/consumers \ $secret://$manager/$id/$secret_name/$key ``` -- manager: 密钥管理服务，可以是 Vault、AWS 等 +- manager: 密钥管理服务，可以是 Vault、AWS、GCP 等 - APISIX Secret 资源 ID，需要与添加 APISIX Secret 资源时指定的 ID 保持一致 - secret_name: 密钥管理服务中的密钥名称 - key：密钥管理服务中密钥对应的 key @@ -191,3 +192,56 @@ curl http://127.0.0.1:9180/apisix/admin/consumers \ ``` 通过上面两步操作，当用户请求命中 `key-auth` 插件时，会通过 APISIX Secret 组件获取到 key 在 Vault 中的真实值。 + +## 使用 GCP Secrets Manager 管理密钥 + +使用 GCP Secret Manager 来管理密钥意味着你可以将密钥信息保存在 GCP 服务中，在配置插件时通过特定格式的变量来引用。APISIX 目前支持对接GCP Secret Manager, 所支持的验证方式是[OAuth 2.0](https://developers.google.com/identity/protocols/oauth2?hl=zh-cn)。 + +### 引用方式 + +``` +$secret://$manager/$id/$secret_name/$key +``` + +引用方式和之前保持一致： + +- manager: 密钥管理服务，可以是 Vault、AWS\GCP 等 +- APISIX Secret 资源 ID，需要与添加 APISIX Secret 资源时指定的 ID 保持一致 +- secret_name: 密钥管理服务中的密钥名称 +- key：密钥管理服务中密钥对应的 key + +### 必要参数 + +| 名称 | 必选项 | 默认值 | 描述 | +| ----------------------- | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| auth_config | 是 | | `auth_config` 和 `auth_file` 必须配置一个。 | +| auth_config.client_email | 是 | | 谷歌服务帐号的 email 参数。 | +| auth_config.private_key | 是 | | 谷歌服务帐号的私钥参数。 | +| auth_config.project_id | 是 | | 谷歌服务帐号的项目 ID。 | +| auth_config.token_uri | 是 | https://oauth2.googleapis.com/token | 请求谷歌服务帐户的令牌的 URI。 | +| auth_config.entries_uri | 否 | https://secretmanager.googleapis.com/v1/ | 谷歌密钥服务访问端点 API。 | +| auth_config.scopes | 否 | https://www.googleapis.com/auth/cloud-platform | 谷歌服务账号的访问范围，可参考 [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes)| +| auth_file | 是 | | `auth_config` 和 `auth_file` 必须配置一个。 | +| ssl_verify | 否 | true | 当设置为 `true` 时，启用 `SSL` 验证。 | + +你需要配置相应的认证参数，或者通过auth_file来指定认证文件，其中auth_file的内容为认证参数的json格式。 + +### 示例 + +以下一种正确的配置实例： + +``` +curl http://127.0.0.1:9180/apisix/admin/secrets/gcp/1 \ +-H "X-API-KEY: $admin_key" -X PUT -d ' +{ + "auth_config" : { + "client_email": "email@apisix.iam.gserviceaccount.com", + "private_key": "private_key", + "project_id": "apisix-project", + "token_uri": "https://oauth2.googleapis.com/token", + "entries_uri": "https://secretmanager.googleapis.com/v1/", + "scopes": "https://www.googleapis.com/auth/cloud-platform" + } +}' + +``` diff --git a/t/secret/gcp.t b/t/secret/gcp.t index ad8335cac934..f374f081ea75 100644 --- a/t/secret/gcp.t +++ b/t/secret/gcp.t @@ -203,7 +203,7 @@ GET /t --- config location /t { content_by_lua_block { - local conf = { + local conf = { auth_config = { client_email = "email@apisix.iam.gserviceaccount.com", private_key = [[