Vault 命令行
Vault 提供了一个命令行工具,该工具包含常用功能和格式输出。 Vault 命令行是一个单一的静态二进制文件。它是一个对 HTTP API 的简单封装。每个命令行的命令在其内部都能直接映射到 HTTP API。
每个命令都表示为一个命令或子命令。本文档对应于最新版本的 Vault(本文写作时为 1.9.2)。如果读者运行的是旧版本,命令的行为可能会有所不同。运行 vault -h
或 vault <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
)以及多个参数(password
和policies
)被设置了,那么命令看起来就是这样的:
$ 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 中最常见的四种操作是 read
、write
、delete
和 list
。这些操作适用于 Vault 中的大多数路径。一些路径将包含机密,其他路径可能包含配置。不管包含的是什么,向 Vault 读写数据的主要接口是相似的。
为了演示基本的读写操作,将使用内置的 Key Value 机密引擎。这个引擎是自动挂载的,没有外部依赖。请注意,kv
使用不同的命令进行读写:分别为 kv get
和 kv put
。
早先的 Key Value 引擎使用 read
和 write
命令。更先进的 Key Value Version 2 引擎引入了新的 kv get
和 kv 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)的输出格式。合法格式有:table
、json
或 yaml
。
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