Vault 命令行

Vault 提供了一个命令行工具,该工具包含常用功能和格式输出。 Vault 命令行是一个单一的静态二进制文件。它是一个对 HTTP API 的简单封装。每个命令行的命令在其内部都能直接映射到 HTTP API。

每个命令都表示为一个命令或子命令。本文档对应于最新版本的 Vault(本文写作时为 1.9.2)。如果读者运行的是旧版本,命令的行为可能会有所不同。运行 vault -hvault <command> -h 以查看与当前使用的版本相对应的帮助输出。

运行以下命令获得帮助信息:

$ vault -h

运行以下命令获得子命令的帮助信息:

$ vault <subcommand> -h

命令结构

Vault 有许多命令和子命令选项可用:HTTP 选项、输出选项和各命令特有的选项。

Vault 命令行的命令中,命令在前,路径和参数(如果有)在后:

$ vault <command> [options] [path] [args]
  • options —— 设置额外配置的标识
  • args —— 传递给 API 的参数

提示:可以运行 vault path-help <path>命令来查询可用参数。

例子

这个例子里使用 write 命令在 userpass 身份验证方法中创建一个新用户 (bob)。它通过 -address 标志指定使用的 Vault 服务器地址,然后 (auth/userpass/users/bob)指定了写入的路径, 最后是其参数 (password="long-password")。

$ vault write -address="http://127.0.0.1:8200" auth/userpass/users/bob password="long-password"

如果指定了多个选项(-address-namespace)以及多个参数(passwordpolicies)被设置了,那么命令看起来就是这样的:

$ vault write -address="http://127.0.0.1:8200" -namespace="my-organization" \
        auth/userpass/users/bob password="long-password" policies="admin"

选项(标志)位于命令(或子命令)之后,路径之前;路径后是用来设置发往 API 请求的参数。

返回码

Vault 命令行的设计目标是要保持一致性以及遵守社区的约定与习惯,除非文档中有另外的说明。

  • 发生在本机的错误(例如标志不正确、验证失败或参数数量错误)返回退出代码 1。
  • 所有远程错误(例如 API 故障、TLS 错误 或 API 参数不正确)都会返回退出状态 2

某些命令会在合理的情况下不遵守上面的约定。相关文档中会记录这种特殊情况。

自动补全(Autocompletion)

Vault 命令可以对标志、子命令和参数(如果支持的话)的选项进行自动补全。

启用自动补全:

$ vault -autocomplete-install

启用后需要重启 shell 会话才能生效。

开始键入 Vault 命令时,按 <tab> 键以显示可用自动补全的列表。输入 -<tab> 以显示可用自动补全的标识。

如果设置了 VAULT_* 环境变量,自动补全将自动查询 Vault 服务器并返回有用的参数建议。

读写数据

Vault 中最常见的四种操作是 readwritedeletelist。这些操作适用于 Vault 中的大多数路径。一些路径将包含机密,其他路径可能包含配置。不管包含的是什么,向 Vault 读写数据的主要接口是相似的。

为了演示基本的读写操作,将使用内置的 Key Value 机密引擎。这个引擎是自动挂载的,没有外部依赖。请注意,kv 使用不同的命令进行读写:分别为 kv getkv put

早先的 Key Value 引擎使用 readwrite 命令。更先进的 Key Value Version 2 引擎引入了新的 kv getkv put 命令。

写入数据

使用 vault kv put 命令向 Vault 写入数据:

$ vault kv put secret/password value=itsasecret

某些机密引擎可以使用任意键/值对,另一些则有严格限制。 Vault 内置的帮助将在适当的情况下指导用户了解这些限制。

stdin

Vault 中的某些命令可以使用 - 作为值从标准输入读取数据。如果参数是个 - ,Vault 希望从 stdin 读取 JSON 对象:

$ echo -n '{"value":"itsasecret"}' | vault kv put secret/password -

除了读取完整的 JSON 对象,Vault 也可以从 stdin 读取一个值:

$ echo -n "itsasecret" | vault kv put secret/password value=-

文件

有些命令可以从磁盘上的文件中读取数据。用法与刚才读取 stdin 的差不多。如果参数值以@开头,Vault 会将它作为文件来读取:

$ vault kv put secret/password @data.json

或者可以将文件内容作为参数值:

$ vault kv put secret/password value=@data.txt

请注意,如果参数以 @key=value 格式提供,Vault 会将其视为一个键为 @key 的键值对,而不是名为 key=value 的文件。这也意味着 Vault 不支持包含 = 的文件名。

读取数据

数据被保存后,可以通过 vault kv get 命令读取:

$ vault kv get secret/password
Key                 Value
---                 -----
refresh_interval    768h0m0s
value               itsasecret

令牌助手(Token Helper)

默认情况下,Vault 命令行使用“令牌助手”在通过身份验证后缓存令牌。这在概念上类似于网站如何将您的会话信息通过 Cookie 安全地存储在浏览器中。令牌助手是可定制的,甚至可以构建自己的令牌助手。

默认情况下令牌助手将令牌存储在 ~/.vault-token 中。随时可以通过删除该文件来“注销”Vault。

环境变量

命令行会读取以下环境变量作为默认配置使用。这可以减轻重复输入标志的工作量。命令中设置的标志总是优先于环境变量。

VAULT_TOKEN

Vault 身份验证令牌。在概念上类似于网站上的会话令牌,VAULT_TOKEN 环境变量保存令牌的内容。

VAULT_ADDR

用 URL 和端口号组成的 Vault 服务器地址,例如:https://127.0.0.1:8200/

VAULT_CACERT

一个本机磁盘上的 PEM 编码的 CA 证书文件路径。该文件被用以验证 Vault 服务器的 SSL 证书。本环境变量优先级高于 VAULT_CAPATH

VAULT_CAPATH

一个本机磁盘上包含有一组 PEM 编码的 CA 证书文件的文件夹路径。这些证书被用以验证 Vault 服务器的 SSL 证书

VAULT_CLIENT_CERT

一个本机磁盘上的 PEM 编码的客户端证书文件路径。该文件被用以与 Vault 服务器进行 TLS 通信。

VAULT_CLIENT_KEY

一个本机磁盘上的未加密、PEM 编码的私钥文件路径,对应上面的客户端证书。

VAULT_CLIENT_TIMEOUT

控制超时时间的变量。默认值为 60 秒。

VAULT_CLUSTER_ADDR

在高可用性模式下,其他集群成员用于连接到本节点的地址。

VAULT_FORMAT

设置 Vault 命令(read/status/write)的输出格式。合法格式有:tablejsonyaml

VAULT_MAX_RETRIES

当遇到 5xx 错误码时最大重试次数。默认值为 2,也就是会尝试 3 次。将该值设置为 0 即可关闭重试。

VAULT_REDIRECT_ADDR

在高可用性模式下将客户端重定向到此节点时使用的地址。

VAULT_SKIP_VERIFY

在与 Vault 服务器进行通信之前不对服务器端提供的证书进行验证。该配置将违反 Vault 的安全模型,不建议使用。

VAULT_TLS_SERVER_NAME

通过 TLS 连接时用作 SNI 主机的名称。

VAULT_CLI_NO_COLOR

如果设置该变量,Vault 的输出将不包含 ANSI 颜色转义序列字符。

VAULT_RATE_LIMIT

该环境变量将限制 vault 命令向 Vault 服务发送请求的速率。

该环境变量的格式为 rate[:burst](其中 [] 中的项目是可选的)。如果没有设定,则突发值默认为 rate。速率和突发(burst)都按“每秒操作数”计算。如果未设定本环境变量,则速率和突发将不受限制,即默认情况下速率限制处于关闭状态。

注意:每次调用 vault 命令行的速率都受到限制。由于每次调用 vault CLI 通常只会发出几个请求,因此在使用 Go Vault 客户端 API 时,该环境变量最有用。

VAULT_NAMESPACE

命令所使用的命名空间。设置此项不是必需的,但允许使用相对路径。

VAULT_HTTP_PROXY

用于访问 Vault 的 HTTP 代理地址。当设定该变量时,会覆盖在环境中找到的任何其他代理。格式应为 http://server:port

命令行标志

不同的子命令有不同的标志可用。某些标志(例如用于设置 HTTP 和输出选项的标志)是全局可用的,而其他标志则只能用于特定的子命令。有关可用标志的完整列表,请运行:

$ vault <subcommand> -h

results matching ""

    No results matching ""