This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new a478de8a5 docs: add more secret information to the admin api (#11569)
a478de8a5 is described below
commit a478de8a586671bc7dd0dcf89d8db18d9913ab7c
Author: HuanXin-Chen <[email protected]>
AuthorDate: Tue Sep 24 16:19:38 2024 +0800
docs: add more secret information to the admin api (#11569)
* 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
---
docs/en/latest/admin-api.md | 98 ++++++++++++++++++++++++++++++++++++++++++-
docs/zh/latest/admin-api.md | 100 +++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 196 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index d928e7a69..b6f03cbd5 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -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 |
| ----------- | -------- | ----------- |
------------------------------------------------------------------------------------------------------------------
| ------------------------------------------------ |
@@ -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 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.
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 5cefb428b..19d97d780 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -1469,7 +1469,7 @@ Secret 资源请求地址：/apisix/admin/secrets/{secretmanager}/{id}
### body 请求参数 {#secret-config-body-requset-parameters}
-当 `{secretmanager}` 是 `vault` 时：
+#### 当 Secret Manager 是 Vault 时
| 名称 | 必选项 | 类型 | 描述
| 例子
|
| ----------- | -------- | ----------- |
------------------------------------------------------------------------------------------------------------------
| ------------------------------------------------ |
@@ -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 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 返回的。
