跳到主要内容

在 HashiCorp Vault 中管理密钥

HashiCorp Vault 是一个用于跨不同环境和应用程序管理密钥和加密的集中式平台。它为存储和访问（例如 API 密钥、密码、证书等）提供了统一的密钥管理。

APISIX 支持在配置文件中将敏感数据存储为密钥，例如 admin_key、etcd username、password。

本指南将向你展示如何配置 HashiCorp Vault 作为密钥管理器，然后将 APISIX admin_key 存储在 Vault 中，并在 APISIX 配置文件中引用该密钥。

与 Vault 集成

前置条件​

配置 Vault 服务器​

在 Docker 中以开发模式启动一个名为 apisix-quickstart-vault 的 Vault 实例，令牌为 apisix-quickstart-vault-token。暴露的端口映射到主机上的 8200：

docker run -d --cap-add=IPC_LOCK \
    -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' \
    -e 'VAULT_ADDR=http://127.0.0.1:8200' \
    -e 'VAULT_DEV_ROOT_TOKEN_ID=apisix-quickstart-vault-token' \
    -e 'VAULT_TOKEN=apisix-quickstart-vault-token' \
    --network=apisix-quickstart-net \
    --name apisix-quickstart-vault \
    -p 8200:8200 vault:1.13.0

APISIX 需要访问 Vault 并检索密钥的权限。你应该使用 HashiCorp 配置语言 (HCL) 创建一个策略文件，以为 APISIX 生成 Vault 访问令牌。

在 Vault 实例中创建一个名为 apisix-policy.hcl 的 Vault 策略文件，以授予 APISIX 对路径 secret/ 的读取权限。你可以将密钥放在路径 secret/ 下，以允许 APISIX 读取它们：

docker exec apisix-quickstart-vault /bin/sh -c "echo '
path \"secret/data/*\" {
    capabilities = [\"read\"]
}
' > /etc/apisix-policy.hcl"

将策略文件应用到 Vault 实例：

docker exec apisix-quickstart-vault vault policy write apisix-policy /etc/apisix-policy.hcl

接下来，生成附加到新定义策略的访问令牌，以便 APISIX 访问 Vault：

docker exec apisix-quickstart-vault vault token create -policy="apisix-policy"

每次执行上述命令都会生成一个不同的令牌。如果成功，输出应类似于以下内容：

Key                  Value
---                  -----
token                hvs.CAESIHUznrV4wgcifUia0FROd6iprK7NjipAiHBYwiZDQP9TGh4KHGh2cy5ndHc5dzBPbXd5Y1pzblZXd2ZuQXA3ZHI
token_accessor       YY4iCj2lICDNd50ZJDsBjvZK
token_duration       768h
token_renewable      true
token_policies       ["apisix-policy" "default"]
identity_policies    []
policies             ["apisix-policy" "default"]

复制令牌的值并创建一个名为 apisix-vault-token 的文件以将其存储在 APISIX 实例中：

docker exec apisix-quickstart /bin/sh -c "echo '
hvs.CAESIHUznrV4wgcifUia0FROd6iprK7NjipAiHBYwiZDQP9TGh4KHGh2cy5ndHc5dzBPbXd5Y1pzblZXd2ZuQXA3ZHI
' > /usr/local/apisix/conf/apisix-vault-token"

Vault Agent 在下一步中使用令牌 apisix-vault-token 向 Vault 进行身份验证。

配置 Vault Agent​

Vault Agent 是一个客户端守护程序，它与你的应用程序一起运行，并自动执行 Vault 身份验证和令牌续订。它充当 Vault API 的代理并将 Vault 密钥呈现为文件。

APISIX 中的敏感配置可以存储在 Vault 中，然后 Vault Agent 读取它们并将它们注入到 APISIX 配置文件中，例如 admin_key。

下载 Vault 二进制文件并将其复制到 APISIX 实例中：

wget https://releases.hashicorp.com/vault/1.13.0/vault_1.13.0_linux_amd64.zip
unzip vault_1.13.0_linux_amd64.zip
docker cp vault apisix-quickstart:/usr/local/bin/

在 APISIX 实例中创建一个名为 vault-agent-apisix.hcl 的文件，以配置 Vault Agent 如何访问服务器并呈现密钥。

docker exec apisix-quickstart /bin/sh -c "echo '
pid_file = \"./pidfile\"

vault {
  address = \"http://apisix-quickstart-vault:8200\"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method {
    type   = \"token_file\"
    config = {
      token_file_path = \"/usr/local/apisix/conf/apisix-vault-token\"
    }
  }
}

listener \"tcp\" {
  address = \"127.0.0.1:8100\"
  tls_disable = true
}

template {
  source      = \"/usr/local/apisix/conf/config.ctmpl\"
  destination = \"/usr/local/apisix/conf/config.yaml\"
}
' > /usr/local/apisix/conf/vault-agent-apisix.hcl"

❶ Vault 地址

❷ 用于身份验证的令牌

❸ Vault Agent 守护程序监听属性

❹ 用于渲染的模板文件

❺ 渲染后的 APISIX 配置文件

Vault Agent 启动后，根据模板文件 config.ctmpl 将密钥注入到 APISIX 配置文件 config.yaml 中。这两个文件都存储在 APISIX 默认配置路径 /usr/local/apisix/conf/ 中。

存储密钥​

创建一个密钥 adminKey=apisix-quickstart-key 并将其存储在 Vault 的路径 secret/apisix/ 中：

docker exec apisix-quickstart-vault vault kv put secret/apisix adminKey=apisix-quickstart-key

预期的响应类似于以下内容：

=== Secret Path ===
secret/data/apisix

======= Metadata =======
Key                Value
---                -----
created_time       2023-03-15T11:42:17.123175125Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

使用密钥​

在 APISIX 实例中创建一个名为 config.ctmpl 的 APISIX 模板配置文件。使用 Consul Template 语法 填充 admin_key，该语法将在运行时替换为 secret/apisix/adminKey。

docker exec apisix-quickstart /bin/sh -c "echo '
deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  admin:
    allow_admin:
      - 0.0.0.0/0
    admin_key:
      -
        name: admin
        key: {{ with secret \"secret/apisix\"}} {{ .Data.data.adminKey }} {{ end }}
        role: admin
plugin_attr:
  prometheus:
    export_addr:
      ip: 0.0.0.0
      port: 9091
' > /usr/local/apisix/conf/config.ctmpl"

以下命令使用上面创建的配置文件 vault-agent-apisix.hcl 在 APISIX 实例中启动 Vault Agent 守护程序。Agent 将检索密钥 admin_key 并将其注入到 APISIX 配置文件 config.yaml 中。

docker exec -d apisix-quickstart vault agent -config=/usr/local/apisix/conf/vault-agent-apisix.hcl

重新加载 APISIX 容器以使配置更改生效：

docker exec apisix-quickstart apisix reload

验证​

要验证新的 admin_key 是否生效：

  1. 使用正确的 admin_key 请求 Admin API：
curl -i "http://localhost:9180/apisix/admin/routes" -H 'X-API-KEY: apisix-quickstart-key'

预期的响应类似于以下内容：

HTTP/1.1 200 OK
...
  1. 使用错误的 admin_key 请求 Admin API：
curl -i "http://localhost:9180/apisix/admin/routes" -H 'X-API-KEY: wrong-key'

预期的响应类似于以下内容：

HTTP/1.1 401 Unauthorized
...

下一步​

APISIX 支持将 Vault 作为后端来管理其他类型的密钥，例如 JWT 令牌和证书。

请参阅本章中的其他指南（即将推出），以了解有关将 Vault 与 APISIX 集成以进行身份验证和证书管理的更多信息。