Version: Next

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 配置保存在环境变量中，而不是在配置插件时明文显示。