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をインストールする必要があります。

ローカル開発を始める前に、GOPATHの設定を含め、Go が正しくインストールされていることを確認してください。その後、$GOPATH/bin を指すように GOBIN 変数を設定します。 一部のディストリビューションには古いバージョンのビルドツールが同梱されているため、$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 config を調整する必要があるかもしれません。

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

Vault のインポート

このリポジトリでは、ほかのプロジェクトからインポートできるライブラリを 2 つ公開しています。 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 には、シークレットおよび認証メソッドのほとんどの機能を対象とする、包括的な受け入れテストがあります。

シークレットまたは認証メソッドの機能に取り組んでいて、正常に動作していること（および、ほかの機能に影響していないこと）を確認したい場合は、受け入れテストの実行をおすすめします。

警告： 受け入れテストでは 実際のリソース が作成・破棄・変更されるため、場合によっては実際の費用が発生することがあります。バグがあると、バックエンドにデータが残ってしまう可能性も技術的にはあります。そのため、受け入れテストはご自身の責任で実行してください。少なくとも、テスト対象のバックエンド専用のプライベートアカウントで実行することをおすすめします。

受け入れテストを実行するには、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 も確認します。この変数が設定されている場合、参照先のローカルファイルをコンテナにコピーします。これは、ローカルでの変更をテストする際に便利です。

VaultLicense オプションを設定する代わりに、VAULT_LICENSE_CI 環境変数を設定できます。ライセンスをバージョン管理にコミットするよりも適切です。

任意で 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 パッケージには、さまざまなヘルパーがあります。たとえば、以下のテストでは、それぞれ PR レプリケーションまたは DR レプリケーションを使用して、3 ノードのクラスターを 2 つ作成して接続し、指定されたコンテキストの期限までにレプリケーションの状態が正常にならなかった場合は失敗します。

繰り返しになりますが、以下の例では、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