HashiCorp Vault CLI

Vault

---

请注意：我们高度重视 Vault 的安全性和用户对我们的信任。如果您认为发现了 Vault 的安全问题，请通过 [email protected] 联系我们，以负责任的方式披露。

---

• 网站：developer.hashicorp.com/vault
• 公告列表：Google Groups
• 讨论论坛：Discuss
• 文档：https://developer.hashicorp.com/vault/docs
• 教程：https://developer.hashicorp.com/vault/tutorials
• 认证考试：https://developer.hashicorp.com/certifications/security-automation
• 文档源代码：https://github.com/hashicorp/web-unified-docs

Vault 是一款用于安全访问机密信息的工具。机密信息是指您希望严格控制访问权限的任何内容，例如 API 密钥、密码、证书等。Vault 为各种机密信息提供统一的接口，同时实施严格的访问控制并记录详细的审计日志。

现代系统需要访问大量机密信息：数据库凭据、外部服务的 API 密钥、面向服务架构通信所用的凭据等。了解谁在访问哪些机密信息已经非常困难，而且因平台而异。若要再加上密钥轮换、安全存储和详细审计日志，若没有定制解决方案几乎是不可能的。这正是 Vault 的用武之地。

Vault 的主要功能包括：

• 安全存储机密信息：Vault 可以存储任意键值对。Vault 会在将数据写入持久化存储之前对其加密，因此仅获取原始存储的访问权限并不足以访问您的机密信息。Vault 可以将数据写入磁盘、Consul 等。

• 动态机密信息：Vault 可以按需为某些系统生成机密信息，例如 AWS 或 SQL 数据库。例如，当应用程序需要访问 S3 存储桶时，它会向 Vault 请求凭据，Vault 随即会按需生成具有有效权限的 AWS 密钥对。创建这些动态机密信息后，Vault 还会在租约到期时自动撤销它们。

• 数据加密：Vault 可以加密和解密数据，而无需存储数据。这使安全团队能够定义加密参数，也让开发人员可以将加密后的数据存储在 SQL 数据库等位置，而不必自行设计加密方法。

• 租约与续期：Vault 会为每个机密信息关联一个租约。租约到期时，Vault 会自动撤销该机密信息。客户端可以通过内置的续期 API 续租。

• 撤销：Vault 内置了撤销机密信息的支持。Vault 不仅可以撤销单个机密信息，还可以撤销一组机密信息，例如特定用户读取的所有机密信息，或某一特定类型的所有机密信息。撤销有助于轮换密钥，并在发生入侵时锁定系统。

文档、入门指南和认证考试

文档可在 Vault 网站上查看。

如果你刚接触 Vault，想开始使用安全自动化，请参阅 HashiCorp 学习平台上的入门指南。你还可以查看其他指南，继续学习。

如需查看如何在不同编程语言编写的应用中与 Vault 交互的示例，请参阅 vault-examples 仓库。此外，还提供了开箱即用的示例应用。

通过认证考试，展示你对 Vault 的了解。访问认证页面，了解考试信息，并在 HashiCorp 学习平台上查找学习资料。

开发 Vault

如果你希望参与 Vault 本身或其任何内置系统的开发，首先需要在计算机上安装 Go。

进行本地开发前，请先确保 Go 已正确安装，包括设置 GOPATH，然后将 GOBIN 变量设为 $GOPATH/bin。 确保 $GOPATH/bin 位于你的路径中，因为某些发行版会附带旧版本的构建工具。

接下来，克隆此仓库。Vault 使用 Go Modules，因此建议将仓库克隆到 GOPATH 之外。 然后，你可以通过引导环境来下载所需的构建工具：

$ make bootstrap
...

要编译 Vault 的开发版本，请运行 make 或 make dev。这会将 Vault 二进制文件放入 bin 和 $GOPATH/bin 文件夹：

$ make dev
...
$ bin/vault
...

要编译带 UI 的 Vault 开发版本，请运行 make static-dist dev-ui。这会将 Vault 二进制文件放入 bin 和 $GOPATH/bin 文件夹：

$ make static-dist dev-ui
...
$ bin/vault
...

要运行测试，请输入 make test。注意：这需要安装 Docker。如果命令以退出状态 0 结束，则一切正常！

$ make test
...

如果你正在开发特定的软件包，可以通过指定 TEST 变量，仅运行该软件包的测试。以下示例中，只会运行 vault 软件包的测试。

$ make test TEST=./vault
...

故障排除

如果遇到类似 could not read Username for 'https://github.com' 的错误，你可能需要按如下方式调整 git 配置：

$ git config --global --add url."[email protected]:".insteadOf "https://github.com/"

导入 Vault

此仓库发布了两个可供其他项目导入的库：github.com/hashicorp/vault/api 和 github.com/hashicorp/vault/sdk。

请注意，此仓库还包含 Vault（这款产品）；与大多数 Go 项目一样，Vault 使用 Go 模块管理依赖项。实现方式是通过 go.mod 文件。实际上，该文件的存在也意味着理论上可以将 Vault 作为依赖项导入其他项目。有些其他项目一直这样做，以利用为测试 Vault 本身而开发的测试工具。这并不是使用 Vault 项目受支持的方式，而且一直都不受支持。对于无法将 github.com/hashicorp/vault 导入你的项目而导致的问题，我们不太可能进行修复。

另请参阅下文的“基于 Docker 的测试”章节。

验收测试

Vault 提供了全面的验收测试， 覆盖了密钥和身份验证方法的大多数功能。

如果你正在开发密钥或身份验证方法的功能，并想验证它是否正常运行（以及是否 没有破坏其他功能），我们建议运行验收测试。

**警告：**验收测试会创建／销毁／修改真实资源，在某些情况下可能会产生实际费用。 如果存在 Bug，后端出错在技术上可能会导致遗留数据。因此， 请自行承担风险运行验收测试。我们至少建议你在专用于所测试后端的 私有账户中运行这些测试。

要运行验收测试，请执行 make testacc：

$ make testacc TEST=./builtin/logical/consul
...

必须设置 TEST 变量，并指定后端所在的文件夹。建议设置 TESTARGS 变量， 以筛选要测试的特定资源，因为一次测试所有资源有时会耗费很长时间。

验收测试通常需要设置其他环境变量，例如访问密钥。测试本身应该会尽早报错并告知 需要设置哪些变量，因此这里不再记录。

如需了解有关 Vault Enterprise 功能的更多信息，请访问 Vault Enterprise 网站。

基于 Docker 的测试

我们创建了一种受 NewTestCluster 启发的实验性新测试机制。 以下是使用示例：

import (
  "testing"
  "github.com/hashicorp/vault/sdk/helper/testcluster/docker"
)

func Test_Something_With_Docker(t *testing.T) {
  opts := &docker.DockerClusterOptions{
    ImageRepo: "hashicorp/vault", // or "hashicorp/vault-enterprise"
    ImageTag:    "latest",
  }
  cluster := docker.NewTestDockerCluster(t, opts)
  
  client := cluster.Nodes()[0].APIClient()
  _, err := client.Logical().Read("sys/storage/raft/configuration")
  if err != nil {
    t.Fatal(err)
  }
}

Enterprise 版本的示例：

import (
  "testing"
  "github.com/hashicorp/vault/sdk/helper/testcluster/docker"
)

func Test_Something_With_Docker(t *testing.T) {
  opts := &docker.DockerClusterOptions{
    ImageRepo: "hashicorp/vault-enterprise",
    ImageTag:  "latest",
	VaultLicense: licenseString, // not a path, the actual license bytes
  }
  cluster := docker.NewTestDockerCluster(t, opts)
}

下面是一个更贴近实际的示例，展示了我们如何使用它。DefaultOptions 使用 hashicorp/vault:latest 作为仓库和标签，但也会检查环境变量 VAULT_BINARY。 如果该变量已设置，就会将其引用的本地文件复制到容器中。这在测试本地更改时很有用。

你可以设置环境变量 VAULT_LICENSE_CI，而不是设置 VaultLicense 选项， 这样比将许可证提交到版本控制中更好。

你也可以选择设置 COMMIT_SHA，它会附加到我们构建的镜像名称中，方便调试。

func Test_Custom_Build_With_Docker(t *testing.T) {
  opts := docker.DefaultOptions(t)
  cluster := docker.NewTestDockerCluster(t, opts)
}

github.com/hashicorp/vault/sdk/helper/testcluster 包中提供了各种辅助工具。例如， 下面这些测试会创建两个由 3 个节点组成的集群，并分别使用 PR 或 DR 复制将它们连接起来；如果复制状态在传入的 context 过期前未变为健康状态， 测试就会失败。

同样，按此处编写的方式运行这些测试，需要本地有 Vault Enterprise 二进制文件， 并将环境变量 VAULT_BINARY 设置为指向该文件，同时还要设置 VAULT_LICENSE_CI。

func TestStandardPerfReplication_Docker(t *testing.T) {
  opts := docker.DefaultOptions(t)
  r, err := docker.NewReplicationSetDocker(t, opts)
  if err != nil {
      t.Fatal(err)
  }
  defer r.Cleanup()

  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()
  err = r.StandardPerfReplication(ctx)
  if err != nil {
    t.Fatal(err)
  }
}

func TestStandardDRReplication_Docker(t *testing.T) {
  opts := docker.DefaultOptions(t)
  r, err := docker.NewReplicationSetDocker(t, opts)
  if err != nil {
    t.Fatal(err)
  }
  defer r.Cleanup()

  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()
  err = r.StandardDRReplication(ctx)
  if err != nil {
    t.Fatal(err)
  }
}

最后，下面是使用自定义二进制文件运行现有 OSS Docker 测试的示例：

$ GOOS=linux make dev
$ VAULT_BINARY=$(pwd)/bin/vault go test -run 'TestRaft_Configuration_Docker' ./vault/external_tests/raft/raft_binary
ok      github.com/hashicorp/vault/vault/external_tests/raft/raft_binary        20.960s