Vault バックエンド

Spring Cloud Config サーバーは、バックエンドとして Vault (英語) もサポートします。

Vault は、秘密に安全にアクセスするためのツールです。シークレットとは、API キー、パスワード、証明書、その他の機密情報など、アクセスを厳密に制御したいものです。Vault は、厳密なアクセス制御を提供し、詳細な監査ログを記録しながら、あらゆる秘密への統一されたインターフェースを提供します。

Vault の詳細については、Vault クイックスタートガイド (英語) を参照してください。

構成サーバーが Vault バックエンドを使用できるようにするには、構成サーバーを vault プロファイルで実行できます。例: 構成サーバーの application.properties に、spring.profiles.active=vault を追加できます。

デフォルトでは、Spring Cloud Config サーバーはトークンベースの認証を使用して Vault から構成をフェッチします。Vault は、AppRole、LDAP、JWT、CloudFoundry、KubernetesAuth などの追加の認証方法もサポートしています。TOKEN または X-Config-Token ヘッダー以外の認証方法を使用するには、ConfigServer が認証をそのライブラリに委譲できるようにクラスパスに Spring Vault コアが必要です。以下の依存関係を ConfigServer アプリに追加してください。

Maven (pom.xml)

<dependencies>
	<dependency>
		<groupId>org.springframework.vault</groupId>
		<artifactId>spring-vault-core</artifactId>
	</dependency>
</dependencies>

Gradle (build.gradle)

dependencies {
    implementation "org.springframework.vault:spring-vault-core"
}

デフォルトでは、構成サーバーは Vault サーバーが 127.0.0.1:8200 (英語) で実行されていることを前提としています。また、バックエンドの名前が secret であり、キーが application であると想定しています。これらのデフォルトはすべて、構成サーバーの application.properties で構成できます。次の表に、構成可能な Vault プロパティを示します。

名前 デフォルト値

host

127.0.0.1

port

8200

scheme

http

backend

秘密

defaultKey

アプリケーション

defaultLabel

主要 (enableLabel が true に設定されている場合にのみ使用されます)

enableLabel

false

profileSeparator

,

kvVersion

1

skipSslValidation

false

timeout

5

namespace

null

上記の表のすべてのプロパティには、接頭辞 spring.cloud.config.server.vault を付けるか、複合構成の正しい Vault セクションに配置する必要があります。

構成可能なすべてのプロパティは、org.springframework.cloud.config.server.environment.VaultEnvironmentProperties にあります。

Vault 0.10.0 は、以前のバージョンとは異なる API を公開するバージョン管理された Key-Value バックエンド（k/v バックエンドバージョン 2）を導入しました。現在、マウントパスと実際のコンテキストパスの間に data/ が必要であり、秘密を data オブジェクトにラップしています。spring.cloud.config.server.vault.kv-version=2 を設定すると、これが考慮されます。

オプションで、Vault Enterprise X-Vault-Namespace ヘッダーのサポートがあります。Vault に送信するには、namespace プロパティを設定します。

構成サーバーが実行されている状態で、サーバーに HTTP リクエストを送信して、Vault バックエンドから値を取得できます。そのためには、Vault サーバーのトークンが必要です。

まず、次の例に示すように、Vault にいくつかのデータを配置します。

$ vault kv put secret/application foo=bar baz=bam
$ vault kv put secret/myapp foo=myappsbar

次に、次の例に示すように、構成サーバーに HTTP リクエストを送信して、値を取得します。

$ curl -X "GET" "http://localhost:8888/myapp/default" -H "X-Config-Token: yourtoken"

次のようなレスポンスが表示されます。

{
   "name":"myapp",
   "profiles":[
      "default"
   ],
   "label":null,
   "version":null,
   "state":null,
   "propertySources":[
      {
         "name":"vault:myapp",
         "source":{
            "foo":"myappsbar"
         }
      },
      {
         "name":"vault:application",
         "source":{
            "baz":"bam",
            "foo":"bar"
         }
      }
   ]
}

クライアントが ConfigServer に Vault と通信させるために必要な認証を提供するデフォルトの方法は、X-Config-Token ヘッダーを設定することです。ただし、Spring Cloud Vault と同じ構成プロパティを設定することにより、代わりにヘッダーを省略してサーバーで認証を構成できます。設定するプロパティは spring.cloud.config.server.vault.authentication です。サポートされている認証方法の 1 つに設定する必要があります。spring.cloud.vault についてドキュメント化されているものと同じプロパティ名を使用し、代わりに spring.cloud.config.server.vault プレフィックスを使用して、使用する認証方法に固有の他のプロパティを設定する必要がある場合もあります。詳細については、Spring Cloud Vault リファレンスガイド (英語) を参照してください。

X-Config-Token ヘッダーを省略し、server プロパティを使用して認証を設定する場合、構成サーバーアプリケーションは、追加の認証オプションを有効にするために Spring Vault への追加の依存関係を必要とします。その依存関係を追加する方法については、Spring Vault リファレンスガイドを参照してください。

複数のプロパティソース

Vault を使用する場合、アプリケーションに複数のプロパティソースを提供できます。例: Vault の次のパスにデータを書き込んだと仮定します。

secret/myApp,dev
secret/myApp
secret/application,dev
secret/application

secret/application に書き込まれたプロパティは、ConfigServer を使用するすべてのアプリケーションで使用できます。myApp という名前のアプリケーションでは、secret/myApp および secret/application に書き込まれたすべてのプロパティを使用できます。myApp で dev プロファイルが有効になっている場合、上記のすべてのパスに書き込まれたプロパティが使用可能になり、リストの最初のパスのプロパティが他のパスよりも優先されます。

ラベルによる検索を有効にする

デフォルトでは、Vault バックエンドはシークレットの検索時にラベルを使用しません。これを変更するには、enableLabel 機能フラグを true に設定し、オプションで defaultLabel を設定します。defaultLabel が指定されていない場合は、main が使用されます。

enableLabel 機能フラグがオンの場合、Vault のシークレットのパスには常に 3 つのセグメント (アプリケーション名、プロファイル、ラベル) すべてが含まれている必要があります。機能フラグが有効になっている前のセクションの例は次のようになります。

secret/myApp,dev,myLabel
secret/myApp,default,myLabel       # default profile
secret/application,dev,myLabel     # default application name
secret/application,default,myLabel # default application name and default profile.

プロパティソースの Vault シークレットの解読

Spring Cloud Config サーバーは、特別なプレースホルダープレフィックス {vault} を利用して、Vault からのプロパティの復号化をサポートします。この機能により、実行時に Vault から直接、機密構成プロパティを動的に解決できます。

設定手順

Vault との統合のためのすべての構成設定は、application.yml または application.properties に配置する必要があります。以下は、Vault プロファイルをアクティブ化し、Vault サーバーに接続し、{vault} プレフィックスを使用してプロパティをフォーマットするために必要な特定の構成です。

Vault プロファイルを有効にする

Spring Cloud Config サーバーの Vault プロファイルをアクティブ化します。

spring:
  profiles:
    active: vault

Vault 構成

必要な認証詳細を使用して、Vault サーバーへの接続を設定します。

spring:
  cloud:
    config:
      server:
        vault:
          host: vault.example.com
          port: 8200
          scheme: https
          backend: secret
          defaultKey: application
          kvVersion: 2
          authentication: TOKEN
          token: ${VAULT_TOKEN}
          skipSslValidation: true

これらの設定では、Vault サーバーのアドレス、認証方法、Vault へのアクセスに必要なトークンを指定します。

プロパティの書式設定

シークレットを取得するための Vault パスとキーを指定するには、{vault} プレフィックスを持つプロパティを定義します。

some:
  sensitive:
    value: '{vault}:path/to/secret#key'

この形式は、秘密が保存されている Vault 内の場所 (path/to/secret) と、取得する特定の秘密鍵 (key) に直接マップされます。

エラー処理

構成サーバーが復号化プロセス中に不正なパス、アクセスの課題、キーの欠落などの課題に遭遇した場合、影響を受けるプロパティの先頭に invalid. が付けられ、その値は <n/a> に設定されます。このアプローチは、先頭に {cipher} が付けられたプロパティの処理に似ていますが、Vault との統合に特化しており、復号化が失敗したときに明確なフィードバックを提供します。