From ba25df127b05a018f7929739f37170b40a1ac01e Mon Sep 17 00:00:00 2001 From: soulbird Date: Tue, 29 Nov 2022 11:49:33 +0800 Subject: [PATCH 1/4] docs: add kms env doc --- docs/en/latest/terminology/kms.md | 111 ++++++++++++++++++++++++++++++ docs/zh/latest/terminology/kms.md | 111 ++++++++++++++++++++++++++++++ 2 files changed, 222 insertions(+) create mode 100644 docs/en/latest/terminology/kms.md create mode 100644 docs/zh/latest/terminology/kms.md diff --git a/docs/en/latest/terminology/kms.md b/docs/en/latest/terminology/kms.md new file mode 100644 index 000000000000..2e9517230149 --- /dev/null +++ b/docs/en/latest/terminology/kms.md @@ -0,0 +1,111 @@ +--- +title: KMS +--- + + + +## Description + +Secrets refer to any sensitive information required during the running process of APISIX, which may be part of the core configuration (such as the etcd's password) or some sensitive information in the plugin. Common types of Secrets in APISIX include: + +- username, the password for some components (etcd, Redis, Kafka, etc.) +- the private key of the certificate +- API key +- Sensitive plugin configuration fields, typically used for authentication, hashing, signing, or encryption + +KMS allows users to store Secrets through some secrets management services (vault, etc.) in APISIX, and read them according to the key when using them, so as to ensure that **Secrets do not exist in plain text throughout the platform**. + +APISIX currently supports storing keys in environment variables. + +You use KMS functions by specifying format variables in the consumer configuration of the following plugins: + +- key-auth + +::: note + +If a configuration item is: `key: "$ENV://ABC"`, when the actual value corresponding to $ENV://ABC is not retrieved in KMS, the value of the key will be "$ENV://ABC" instead of `nil`. + +::: + +## Use environment variables to manage keys + +Using environment variables to manage keys means that you can save key information in environment variables, and refer to environment variables through variables in a specific format when configuring plugins. APISIX supports referencing system environment variables and environment variables configured through the Nginx `env` directive. + +### Usage + +``` +$ENV://$env_name/$sub_key +``` + +- env_name: environment variable name +- sub_key: get the value of a property when the value of the environment variable is a JSON string + + If the value of the environment variable is of type string, such as: + +``` +export JACK_AUTH_KEY=abc +``` + +It can be referenced as follows: + +``` +$ENV://JACK_AUTH_KEY +``` + +If the value of the environment variable is a JSON string like: + +``` +export JACK={"auth-key":"abc","openid-key": "def"} +``` + +It can be referenced as follows: + +``` +# Get the auth-key of the environment variable JACK +$ENV://JACK/auth-key + +# Get the openid-key of the environment variable JACK +$ENV://JACK/openid-key +``` + +### Example: use in key-auth plugin + +Step 1: Create environment variables before the APISIX instance starts + +``` +export JACK_AUTH_KEY=abc +``` + +Step 2: Reference the environment variable in the key-auth plugin + +```bash +curl http://127.0.0.1:9180/apisix/admin/consumers \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "username": "jack", + "plugins": { + "key-auth": { + "key": "$ENV://JACK_AUTH_KEY" + } + } +}' +``` + +Through the above steps, the `key` configuration in the `key-auth` plugin can be saved in the environment variable instead of being displayed in plain text when configuring the plugin. diff --git a/docs/zh/latest/terminology/kms.md b/docs/zh/latest/terminology/kms.md new file mode 100644 index 000000000000..605d245c290e --- /dev/null +++ b/docs/zh/latest/terminology/kms.md @@ -0,0 +1,111 @@ +--- +title: KMS +--- + + + +## 描述 + +Secrets 是指 APISIX 运行过程中所需的任何敏感信息，它可能是核心配置的一部分（如 etcd 的密码），也可能是插件中的一些敏感信息。 APISIX 中常见的 Secrets 类型包括： + +- 一些组件（etcd、Redis、kafka 等）的用户名、密码 +- 证书的私钥 +- API 密钥 +- 敏感的插件配置字段，通常用于身份验证、hash、签名或加密 + +KMS 允许用户在 APISIX 中通过一些密钥管理服务（vault 等） 来存储 Secrets，在使用的时候根据 key 进行读取，确保 Secrets 在整个平台中不以明文的形式存在。 + +APISIX 目前支持将密钥存储在环境变量中 + +你可以在以下插件的 consumer 配置中通过指定格式的变量来使用 KMS 功能： + +- key-auth + +::: note + +如果某个配置项为: `key: "$ENV://ABC"`，当 KMS 中没有检索到 $ENV://ABC 对应的真实值，那么 key 的值将是 "$ENV://ABC" 而不是 `nil`。 + +::: + +## 使用环境变量管理密钥 + +使用环境变量来管理密钥意味着你可以将密钥信息保存在环境变量中，在配置插件时通过特定格式的变量来引用环境变量。APISIX 支持引用系统环境变量和通过 Nginx `env` 指令配置的环境变量。 + +### 引用方式 + +``` +$ENV://$env_name/$sub_key +``` + +- env_name: 环境变量名称 +- sub_key: 当环境变量的值是 json 字符串时， 获取某个属性的值 + +如果环境变量的值是字符串类型，如： + +``` +export JACK_AUTH_KEY=abc +``` + +则可以通过如下方式引用： + +``` +$ENV://JACK_AUTH_KEY +``` + +如果环境变量的值是一个 JSON 字符串，例如： + +``` +export JACK={"auth-key":"abc","openid-key": "def"} +``` + +则可以通过如下方式引用： + +``` +# 获取环境变量 JACK 的 auth-key +$ENV://JACK/auth-key + +# 获取环境变量 JACK 的 openid-key +$ENV://JACK/openid-key +``` + +### 示例：在 key-auth 插件中使用 + +第一步：APISIX 实例启动前创建环境变量 + +``` +export JACK_AUTH_KEY=abc +``` + +第二步：在 key-auth 插件中引用环境变量 + +``` +curl http://127.0.0.1:9180/apisix/admin/consumers \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "username": "jack", + "plugins": { + "key-auth": { + "key": "$ENV://JACK_AUTH_KEY" + } + } +}' +``` + +通过以上步骤，可以将 key-auth 插件中的 key 配置保存在环境变量中，而不是在配置插件时明文显示。 From 1607bb979c6293219392b24f09c6fa563272346f Mon Sep 17 00:00:00 2001 From: soulbird Date: Tue, 29 Nov 2022 11:54:12 +0800 Subject: [PATCH 2/4] update config.json --- docs/en/latest/config.json | 3 ++- docs/zh/latest/config.json | 3 ++- docs/zh/latest/terminology/kms.md | 6 +++--- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index 26ded3ecd706..99404960cb5d 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -38,7 +38,8 @@ "terminology/router", "terminology/script", "terminology/service", - "terminology/upstream" + "terminology/upstream", + "terminology/kms" ] }, { diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json index d6ebe8ca61f2..bb851457b461 100644 --- a/docs/zh/latest/config.json +++ b/docs/zh/latest/config.json @@ -37,7 +37,8 @@ "terminology/router", "terminology/script", "terminology/service", - "terminology/upstream" + "terminology/upstream", + "terminology/kms" ] }, { diff --git a/docs/zh/latest/terminology/kms.md b/docs/zh/latest/terminology/kms.md index 605d245c290e..c9ed216a5cd7 100644 --- a/docs/zh/latest/terminology/kms.md +++ b/docs/zh/latest/terminology/kms.md @@ -23,14 +23,14 @@ title: KMS ## 描述 -Secrets 是指 APISIX 运行过程中所需的任何敏感信息，它可能是核心配置的一部分（如 etcd 的密码），也可能是插件中的一些敏感信息。 APISIX 中常见的 Secrets 类型包括： +Secrets 是指 APISIX 运行过程中所需的任何敏感信息，它可能是核心配置的一部分（如 etcd 的密码），也可能是插件中的一些敏感信息。APISIX 中常见的 Secrets 类型包括： - 一些组件（etcd、Redis、kafka 等）的用户名、密码 - 证书的私钥 - API 密钥 - 敏感的插件配置字段，通常用于身份验证、hash、签名或加密 -KMS 允许用户在 APISIX 中通过一些密钥管理服务（vault 等） 来存储 Secrets，在使用的时候根据 key 进行读取，确保 Secrets 在整个平台中不以明文的形式存在。 +KMS 允许用户在 APISIX 中通过一些密钥管理服务（vault 等）来存储 Secrets，在使用的时候根据 key 进行读取，确保 Secrets 在整个平台中不以明文的形式存在。 APISIX 目前支持将密钥存储在环境变量中 @@ -40,7 +40,7 @@ APISIX 目前支持将密钥存储在环境变量中 ::: note -如果某个配置项为: `key: "$ENV://ABC"`，当 KMS 中没有检索到 $ENV://ABC 对应的真实值，那么 key 的值将是 "$ENV://ABC" 而不是 `nil`。 +如果某个配置项为：`key: "$ENV://ABC"`，当 KMS 中没有检索到 $ENV://ABC 对应的真实值，那么 key 的值将是 "$ENV://ABC" 而不是 `nil`。 ::: From e266534815276b9adb82c293cce4c78ad53aca8e Mon Sep 17 00:00:00 2001 From: soulbird Date: Tue, 29 Nov 2022 13:22:45 +0800 Subject: [PATCH 3/4] update doc --- docs/en/latest/terminology/kms.md | 8 +++----- docs/zh/latest/terminology/kms.md | 18 ++++++++---------- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/en/latest/terminology/kms.md b/docs/en/latest/terminology/kms.md index 2e9517230149..5109c67cde8d 100644 --- a/docs/en/latest/terminology/kms.md +++ b/docs/en/latest/terminology/kms.md @@ -30,13 +30,11 @@ Secrets refer to any sensitive information required during the running process o - API key - Sensitive plugin configuration fields, typically used for authentication, hashing, signing, or encryption -KMS allows users to store Secrets through some secrets management services (vault, etc.) in APISIX, and read them according to the key when using them, so as to ensure that **Secrets do not exist in plain text throughout the platform**. +KMS allows users to store Secrets through some secrets management services (Vault, etc.) in APISIX, and read them according to the key when using them to ensure that **Secrets do not exist in plain text throughout the platform**. APISIX currently supports storing keys in environment variables. -You use KMS functions by specifying format variables in the consumer configuration of the following plugins: - -- key-auth +You use KMS functions by specifying format variables in the consumer configuration of the following plugins, such as `key-auth`. ::: note @@ -93,7 +91,7 @@ Step 1: Create environment variables before the APISIX instance starts export JACK_AUTH_KEY=abc ``` -Step 2: Reference the environment variable in the key-auth plugin +Step 2: Reference the environment variable in the `key-auth` plugin ```bash curl http://127.0.0.1:9180/apisix/admin/consumers \ diff --git a/docs/zh/latest/terminology/kms.md b/docs/zh/latest/terminology/kms.md index c9ed216a5cd7..6ab4a8ca76c9 100644 --- a/docs/zh/latest/terminology/kms.md +++ b/docs/zh/latest/terminology/kms.md @@ -25,18 +25,16 @@ title: KMS Secrets 是指 APISIX 运行过程中所需的任何敏感信息，它可能是核心配置的一部分（如 etcd 的密码），也可能是插件中的一些敏感信息。APISIX 中常见的 Secrets 类型包括： -- 一些组件（etcd、Redis、kafka 等）的用户名、密码 +- 一些组件（etcd、Redis、Kafka 等）的用户名、密码 - 证书的私钥 - API 密钥 - 敏感的插件配置字段，通常用于身份验证、hash、签名或加密 -KMS 允许用户在 APISIX 中通过一些密钥管理服务（vault 等）来存储 Secrets，在使用的时候根据 key 进行读取，确保 Secrets 在整个平台中不以明文的形式存在。 +KMS 允许用户在 APISIX 中通过一些密钥管理服务（Vault 等）来存储 Secrets，在使用的时候根据 key 进行读取，确保 Secrets 在整个平台中不以明文的形式存在。 -APISIX 目前支持将密钥存储在环境变量中 +APISIX 目前支持将密钥存储在环境变量中。 -你可以在以下插件的 consumer 配置中通过指定格式的变量来使用 KMS 功能： - -- key-auth +你可以在以下插件的 consumer 配置中通过指定格式的变量来使用 KMS 功能，比如 `key-auth` 插件。 ::: note @@ -55,7 +53,7 @@ $ENV://$env_name/$sub_key ``` - env_name: 环境变量名称 -- sub_key: 当环境变量的值是 json 字符串时， 获取某个属性的值 +- sub_key: 当环境变量的值是 JSON 字符串时，获取某个属性的值 如果环境变量的值是字符串类型，如： @@ -93,9 +91,9 @@ $ENV://JACK/openid-key export JACK_AUTH_KEY=abc ``` -第二步：在 key-auth 插件中引用环境变量 +第二步：在 `key-auth` 插件中引用环境变量 -``` +```shell curl http://127.0.0.1:9180/apisix/admin/consumers \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { @@ -108,4 +106,4 @@ curl http://127.0.0.1:9180/apisix/admin/consumers \ }' ``` -通过以上步骤，可以将 key-auth 插件中的 key 配置保存在环境变量中，而不是在配置插件时明文显示。 +通过以上步骤，可以将 `key-auth` 插件中的 key 配置保存在环境变量中，而不是在配置插件时明文显示。 From 2956add860798e93e60529ff6283cea623fd5e81 Mon Sep 17 00:00:00 2001 From: soulbird Date: Tue, 29 Nov 2022 13:26:18 +0800 Subject: [PATCH 4/4] update doc --- docs/en/latest/terminology/kms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/latest/terminology/kms.md b/docs/en/latest/terminology/kms.md index 5109c67cde8d..56754bf84511 100644 --- a/docs/en/latest/terminology/kms.md +++ b/docs/en/latest/terminology/kms.md @@ -93,7 +93,7 @@ export JACK_AUTH_KEY=abc Step 2: Reference the environment variable in the `key-auth` plugin -```bash +```shell curl http://127.0.0.1:9180/apisix/admin/consumers \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' {