You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/11/29 05:45:01 UTC
[apisix] branch master updated: docs: add kms env doc (#8419)
This is an automated email from the ASF dual-hosted git repository.
sylviasu 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 2509ddc8e docs: add kms env doc (#8419)
2509ddc8e is described below
commit 2509ddc8e18e3428bbd51e4833fbd51c230b57bf
Author: soulbird <zh...@outlook.com>
AuthorDate: Tue Nov 29 13:44:56 2022 +0800
docs: add kms env doc (#8419)
* docs: add kms env doc
* update config.json
---
docs/en/latest/config.json | 3 +-
docs/en/latest/terminology/kms.md | 109 ++++++++++++++++++++++++++++++++++++++
docs/zh/latest/config.json | 3 +-
docs/zh/latest/terminology/kms.md | 109 ++++++++++++++++++++++++++++++++++++++
4 files changed, 222 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 26ded3ecd..99404960c 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/en/latest/terminology/kms.md b/docs/en/latest/terminology/kms.md
new file mode 100644
index 000000000..56754bf84
--- /dev/null
+++ b/docs/en/latest/terminology/kms.md
@@ -0,0 +1,109 @@
+---
+title: KMS
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 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 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, such as `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
+
+```shell
+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/config.json b/docs/zh/latest/config.json
index d6ebe8ca6..bb851457b 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
new file mode 100644
index 000000000..6ab4a8ca7
--- /dev/null
+++ b/docs/zh/latest/terminology/kms.md
@@ -0,0 +1,109 @@
+---
+title: KMS
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+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` 插件中引用环境变量
+
+```shell
+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 配置保存在环境变量中，而不是在配置插件时明文显示。