Skip to content

Commit

Permalink
docs: add more secret information to the admin api (#11569)
Browse files Browse the repository at this point in the history 
* docs(admin): add more secret information to the admin api

* Update admin-api.md

* Update admin-api.md

* Update admin-api.md

* Update admin-api.md

* docs(admin): fix the style shell to json

* docs(admin): Table formatting

* fix(docs): ci lint problem

* docs(admin): remove example
  • Loading branch information
@HuanXin-Chen
HuanXin-Chen authored Sep 24, 2024
1 parent 2fcfbd8 commit a478de8
Show file tree
Hide file tree
Showing 2 changed files with 196 additions and 2 deletions.
98 changes: 97 additions & 1 deletion docs/en/latest/admin-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1459,7 +1459,7 @@ Secret resource request address: /apisix/admin/secrets/{secretmanager}/{id}
### Request Body Parameters
When `{secretmanager}` is `vault`:
#### When Secret Manager is Vault
| Parameter | Required | Type | Description | Example |
| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
Expand Down 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 Secret Manager is AWS
| Parameter | Required | Type | Description |
| ----------------- | -------- | ------ | --------------------------------------- |
| 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 |
Example Configuration:
```json
{
"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 Secret Manager 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:
```json
{
"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",
"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@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",
"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@apisix.iam.gserviceaccount.com","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
100 changes: 99 additions & 1 deletion docs/zh/latest/admin-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1469,7 +1469,7 @@ Secret 资源请求地址：/apisix/admin/secrets/{secretmanager}/{id}

### body 请求参数 {#secret-config-body-requset-parameters}

当 `{secretmanager}` 是 `vault` 时：
#### 当 Secret Manager 是 Vault 时

| 名称 | 必选项 | 类型 | 描述 | 例子 |
| ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
Expand Down 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"}}
```

#### 当 Secret Manager 是 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 地址 |

配置示例：

```json
{
"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"}
```

#### 当 Secret Manager 是 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` 验证。 |

配置示例：

```json
{
"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",
"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@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",
"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@apisix.iam.gserviceaccount.com","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 a478de8

Please sign in to comment.