Skip to content

Commit

Permalink
docs(secret): integrating gcp usage introduction
Browse files Browse the repository at this point in the history
  • Loading branch information
@HuanXin-Chen
HuanXin-Chen committed Jul 25, 2024
1 parent 0e5538c commit 8eabd06
Show file tree
Hide file tree
Showing 3 changed files with 112 additions and 4 deletions.
58 changes: 56 additions & 2 deletions docs/en/latest/terminology/secret.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 protected]",
"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"
}
}'

```
56 changes: 55 additions & 1 deletion docs/zh/latest/terminology/secret.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ APISIX 目前支持通过以下方式存储密钥：

- [环境变量](#使用环境变量管理密钥)
- [HashiCorp Vault](#使用-vault-管理密钥)
- [GCP Secrets Manager](#使用-gcp-secrets-manager-管理密钥)

你可以在以下插件的 consumer 配置中通过指定格式的变量来使用 APISIX Secret 功能，比如 `key-auth` 插件。

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 protected]",
"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"
}
}'

```
2 changes: 1 addition & 1 deletion t/secret/gcp.t
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [[
Expand Down

0 comments on commit 8eabd06

Please sign in to comment.