Skip to content

Commit

Permalink
docs(admin): add more secret information to the admin api
Browse files Browse the repository at this point in the history
  • Loading branch information
@HuanXin-Chen
HuanXin-Chen committed Sep 11, 2024
1 parent 3387916 commit 63a39f1
Show file tree
Hide file tree
Showing 2 changed files with 194 additions and 0 deletions.
96 changes: 96 additions & 0 deletions docs/en/latest/admin-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1497,6 +1497,102 @@ HTTP/1.1 200 OK
{"key":"\/apisix\/secrets\/vault\/test2","value":{"id":"vault\/test2","token":"apisix","prefix":"apisix","update_time":1669625828,"create_time":1669625828,"uri":"http:\/\/xxx\/get"}}
```
When `{secretmanager}` is `aws`:
| Parameter | Required | Type | Description | Example |
| --- | --- | --- | --- | --- |
| access_key_id | True | string | AWS Access Key ID | |
| secret_access_key | True | string | AWS Secret Access Key | |
| session_token | False | string | Temporary access credential information | |
| region | False | string | AWS Region | |
| endpoint_url | False | URI | AWS Secret Manager URL | https://secretsmanagerus-east-1.amazonaws.com |
Example Configuration:
```shell
{
"endpoint_url": "http://127.0.0.1:4566",
"region": "us-east-1",
"access_key_id": "access",
"secret_access_key": "secret",
"session_token": "token"
}
```
Example API usage:
```shell
curl -i http://127.0.0.1:9180/apisix/admin/secrets/aws/test3 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"endpoint_url": "http://127.0.0.1:4566",
"region": "us-east-1",
"access_key_id": "access",
"secret_access_key": "secret",
"session_token": "token"
}'
```
```shell
HTTP/1.1 200 OK
...
{"value":{"create_time":1726069970,"endpoint_url":"http://127.0.0.1:4566","region":"us-east-1","access_key_id":"access","secret_access_key":"secret","id":"aws/test3","update_time":1726069970,"session_token":"token"},"key":"/apisix/secrets/aws/test3"}
```
When `{secretmanager}` is `gcp`:
| Parameter | Required | Type | Description | Example |
| --- | --- | --- | --- | --- |
| auth_config | True | object | Either `auth_config` or `auth_file` must be provided. | |
| auth_config.client_email | True | string | Email address of the Google Cloud service account. | |
| auth_config.private_key | True | string | Private key of the Google Cloud service account. | |
| auth_config.project_id | True | string | Project ID in the Google Cloud service account. | |
| auth_config.token_uri | False | string | Token URI of the Google Cloud service account. | [https://oauth2.googleapis.com/token](https://oauth2.googleapis.com/token) |
| auth_config.entries_uri | False | string | The API access endpoint for the Google Secrets Manager. | [https://secretmanager.googleapis.com/v1](https://secretmanager.googleapis.com/v1) |
| auth_config.scope | False | string | Access scopes of the Google Cloud service account. See [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes) | [https://www.googleapis.com/auth/cloud-platform](https://www.googleapis.com/auth/cloud-platform) |
| auth_file | True | string | Path to the Google Cloud service account authentication JSON file. Either `auth_config` or `auth_file` must be provided. | |
| ssl_verify | False | boolean | When set to `true`, enables SSL verification as mentioned in [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | true |
Example Configuration:
```shell
{
"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",
"scope": ["https://www.googleapis.com/auth/cloud-platform"]
}
}
```
Example API usage:
```shell
curl -i http://127.0.0.1:9180/apisix/admin/secrets/gcp/test4 \
-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",
"scope": ["https://www.googleapis.com/auth/cloud-platform"]
}
}'
```
```shell
HTTP/1.1 200 OK
...
{"value":{"id":"gcp/test4","ssl_verify":true,"auth_config":{"token_uri":"https://oauth2.googleapis.com/token","scope":["https://www.googleapis.com/auth/cloud-platform"],"entries_uri":"https://secretmanager.googleapis.com/v1","client_email":"[email protected]","private_key":"private_key","project_id":"apisix-project"},"create_time":1726070161,"update_time":1726070161},"key":"/apisix/secrets/gcp/test4"}
```
### Response Parameters
Currently, the response is returned from etcd.
Expand Down
98 changes: 98 additions & 0 deletions docs/zh/latest/admin-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1508,6 +1508,104 @@ HTTP/1.1 200 OK
{"key":"\/apisix\/secrets\/vault\/test2","value":{"id":"vault\/test2","token":"apisix","prefix":"apisix","update_time":1669625828,"create_time":1669625828,"uri":"http:\/\/xxx\/get"}}
```

当 `{secretmanager}` 是 `aws` 时：

| 名称 | 必选项 | 默认值 | 描述 |
| --- | --- | --- | --- |
| access_key_id | 是 | | AWS 访问密钥 ID |
| secret_access_key | 是 | | AWS 访问密钥 |
| session_token | 否 | | 临时访问凭证信息 |
| region | 否 | us-east-1 | AWS 区域 |
| endpoint_url | 否 | https://secretsmanager.{region}.amazonaws.com | AWS Secret Manager 地址 |

配置示例：

```shell
{
"endpoint_url": "http://127.0.0.1:4566",
"region": "us-east-1",
"access_key_id": "access",
"secret_access_key": "secret",
"session_token": "token"
}
```

使用示例：

```shell
curl -i http://127.0.0.1:9180/apisix/admin/secrets/aws/test3 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"endpoint_url": "http://127.0.0.1:4566",
"region": "us-east-1",
"access_key_id": "access",
"secret_access_key": "secret",
"session_token": "token"
}'
```

```shell
HTTP/1.1 200 OK
...
{"value":{"create_time":1726069970,"endpoint_url":"http://127.0.0.1:4566","region":"us-east-1","access_key_id":"access","secret_access_key":"secret","id":"aws/test3","update_time":1726069970,"session_token":"token"},"key":"/apisix/secrets/aws/test3"}
```

当 `{secretmanager}` 是 `gcp` 时：

| 名称 | 必选项 | 默认值 | 描述 |
| ----------------------- | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| 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.scope | 否 | 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` 验证。 |

配置示例：

```shell
{
"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",
"scope": ["https://www.googleapis.com/auth/cloud-platform"]
}
}
```

使用示例：

```shell
curl -i http://127.0.0.1:9180/apisix/admin/secrets/gcp/test4 \
-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",
"scope": ["https://www.googleapis.com/auth/cloud-platform"]
}
}'
```

```shell
HTTP/1.1 200 OK
...
{"value":{"id":"gcp/test4","ssl_verify":true,"auth_config":{"token_uri":"https://oauth2.googleapis.com/token","scope":["https://www.googleapis.com/auth/cloud-platform"],"entries_uri":"https://secretmanager.googleapis.com/v1","client_email":"[email protected]","private_key":"private_key","project_id":"apisix-project"},"create_time":1726070161,"update_time":1726070161},"key":"/apisix/secrets/gcp/test4"}
```

### 应答参数 {#secret-config-response-parameters}

当前的响应是从 etcd 返回的。

0 comments on commit 63a39f1

Please sign in to comment.