Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add more secret information to the admin api #11569

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
+196 −2
Open

docs: add more secret information to the admin api #11569

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
63a39f1
docs(admin): add more secret information to the admin api
HuanXin-Chen Sep 11, 2024
9317c61
Update admin-api.md
HuanXin-Chen Sep 12, 2024
619780b
Update admin-api.md
HuanXin-Chen Sep 12, 2024
4d81740
Update admin-api.md
HuanXin-Chen Sep 12, 2024
1348982
Update admin-api.md
HuanXin-Chen Sep 12, 2024
13e1f9a
docs(admin): fix the style shell to json
HuanXin-Chen Sep 17, 2024
9396f39
Merge branch 'docs-secret' of https://github.com/HuanXin-Chen/apisix …
HuanXin-Chen Sep 17, 2024
cf68141
docs(admin): Table formatting
HuanXin-Chen Sep 17, 2024
8eb656d
fix(docs): ci lint problem
HuanXin-Chen Sep 17, 2024
349b256
docs(admin): remove example
HuanXin-Chen Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 97 additions & 1 deletion docs/en/latest/admin-api.md
View file
Open in desktop
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 | 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://secretsmanager.{region}.amazonaws.com |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example column seems redundant. I would suggest using the following table instead:

Suggested change
| 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://secretsmanager.{region}.amazonaws.com |
| 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 (e.g: https://secretsmanager.{region}.amazonaws.com) |

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is no need to remove the example field, as the vault document also contains this field, and docs consistency should be maintained.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure, fine by me. I wanted it to be removed because it's a very wide almost empty column taking screen real estate away from other columns :D

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


Example Configuration:

```shell
shreemaan-abhishek marked this conversation as resolved.
Show resolved Hide resolved
{
"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 |
shreemaan-abhishek marked this conversation as resolved.
Show resolved Hide resolved

Example Configuration:

```shell
shreemaan-abhishek marked this conversation as resolved.
Show resolved Hide resolved
{
"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
Open in desktop
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 地址 |

配置示例：

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

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

配置示例：

```shell
{
"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 返回的。
Loading