このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring Cloud Vault 4.3.0 を使用してください！

サービスレジストリの設定

DiscoveryClient (Spring Cloud や Consul など) を使用して spring.cloud.vault.discovery.enabled=true (デフォルトは false) を設定することで Vault サーバーを見つけることができます。その結果、アプリには適切な検出構成を含む application.yml (または環境変数) が必要になります。利点は、検出サービスが固定ポイントである限り、Vault が座標を変更できることです。デフォルトのサービス ID は vault ですが、クライアントで spring.cloud.vault.discovery.serviceId を使用してこれを変更できます。

検出クライアントの実装はすべて、ある種のメタデータマップをサポートしています (たとえば、Eureka の場合は eureka.instance.metadataMap があります)。クライアントが正しく接続できるように、サービスのいくつかの追加プロパティをサービス登録メタデータで構成する必要がある場合があります。トランスポート層セキュリティの詳細を提供しないサービスレジストリは、https または http に設定される scheme メタデータエントリを提供する必要があります。スキームが設定されておらず、サービスが安全なサービスとして公開されていない場合、設定はデフォルトで spring.cloud.vault.scheme になりますが、設定されていない場合は https になります。

spring.cloud.vault.discovery:
    enabled: true
    service-id: my-vault-service

Vault クライアントのフェイルファスト

場合によっては、Vault サーバーに接続できない場合、サービスの起動に失敗することが望ましい場合があります。これが望ましい動作である場合は、ブートストラップ構成プロパティ spring.cloud.vault.fail-fast=true を設定すると、クライアントは例外で停止します。

spring.cloud.vault:
    fail-fast: true

Vault エンタープライズ名前空間のサポート

Vault Enterprise では、ネームスペースを使用して、単一の Vault サーバー上で複数の Vault を分離できます。spring.cloud.vault.namespace= …  を設定して名前空間を構成すると、Vault RestTemplate または WebClient を使用する場合、すべての送信 HTTP リクエストで名前空間ヘッダー X-Vault-Namespace が有効になります。

この機能は Vault Community エディションではサポートされておらず、Vault の動作には影響しないことに注意してください。

spring.cloud.vault:
    namespace: my-namespace

関連事項: Vault エンタープライズ: 名前空間 (英語)

Vault クライアント SSL 構成

SSL は、さまざまなプロパティを設定することで宣言的に構成できます。javax.net.ssl.trustStore を設定して JVM 全体の SSL 設定を構成するか、spring.cloud.vault.ssl.trust-store を設定して Spring Cloud Vault Config のみの SSL 設定を設定できます。

spring.cloud.vault:
    ssl:
        trust-store: classpath:keystore.jks
        trust-store-password: changeit
        trust-store-type: JKS
        enabled-protocols: TLSv1.2,TLSv1.3
        enabled-cipher-suites: TLS_AES_128_GCM_SHA256

  • trust-store はトラストストアのリソースを設定します。SSL で保護された Vault 通信は、指定されたトラストストアを使用して Vault SSL 証明書を検証します。

  • trust-store-password はトラストストアのパスワードを設定します

  • trust-store-type はトラストストアの型を設定します。サポートされる値は、PEM を含む、サポートされているすべての KeyStore 型です。

  • enabled-protocols は、有効な SSL/TLS プロトコルのリストを設定します (3.0.2 以降)。

  • enabled-cipher-suites は、有効な SSL/TLS 暗号スイートのリストを設定します (3.0.2 以降)。

spring.cloud.vault.ssl.* の構成は、Apache Http コンポーネントまたは OkHttp クライアントのいずれかがクラスパス上にある場合にのみ適用できることに注意してください。

リースのライフサイクル管理 (更新と取り消し)

すべてのシークレットを使用して、Vault はリース (期間、更新可能性などの情報を含むメタデータ) を作成します。

Vault は、データが指定された期間、つまり Time To Live (TTL) の間有効であることを約束します。リースの有効期限が切れると、Vault はデータを取り消すことができ、シークレットの利用者はそれが有効であるかどうかを確信できなくなります。

Spring Cloud Vault は、ログイントークンとシークレットの作成を超えてリースのライフサイクルを維持します。ただし、リースに関連付けられたログイントークンとシークレットは、リースが期限切れになる直前に、ターミナルの期限が切れるまで更新されるようにスケジュールされています。アプリケーションをシャットダウンすると、取得したログイントークンと更新可能なリースが無効になります。

シークレットサービスとデータベースバックエンド (MongoDB や MySQL など) は通常、更新可能なリースを生成するため、生成された資格情報はアプリケーションのシャットダウン時に無効になります。

静的トークンは更新も取り消しもされません。

リースの更新と取り消しはデフォルトで有効になっていますが、spring.cloud.vault.config.lifecycle.enabled を false に設定することで無効にできます。リースが期限切れになり、Spring Cloud Vault が Vault にアクセスできなくなったり、生成された資格情報を使用するサービスにアクセスできなくなり、アプリケーションのシャットダウン後も有効な資格情報がアクティブのままになるため、これは推奨されません。

spring.cloud.vault:
    config.lifecycle:
    	enabled: true
    	min-renewal: 10s
    	expiry-threshold: 1m
    	lease-endpoints: Legacy

  • enabled は、シークレットに関連付けられたリースを更新するかどうか、および期限切れのシークレットをローテーションするかどうかを制御します。デフォルトで有効になっています。

  • min-renewal は、リースを更新する前に少なくとも必要な期間を設定します。この設定により、更新が頻繁に行われるのを防ぎます。

  • expiry-threshold は有効期限のしきい値を設定します。リースは、有効期限が切れる前に、設定された期間が経過すると更新されます。

  • lease-endpoints は、更新および取り消し用のエンドポイントを設定します。0.8 より前の Vault バージョンのレガシー、およびそれ以降の SysLeases バージョン。

  • lease-strategy は、リース更新時のエラー処理を制御するために LeaseStrategy (DropOnError、RetainOnError、RetainOnIoError) を設定します。

関連事項: Vault ドキュメント: リース、更新、取り消し (英語)

セッショントークンのライフサイクル管理 (更新、再ログイン、取り消し)

Vault セッショントークン ( LoginToken とも呼ばれる) は、TTL と最大 TTL があり、期限切れになる可能性があるという点で、リースに非常によく似ています。ログイントークンの有効期限が切れると、それを使用して Vault と対話することはできなくなります。Spring Vault には、命令型およびリアクティブ型の使用のために SessionManager API が付属しています。

Spring Cloud Vault は、デフォルトでセッショントークンのライフサイクルを維持します。セッショントークンは遅延して取得されるため、実際のログインは Vault の最初のセッションバインド使用まで延期されます。Spring Cloud Vault はセッショントークンを取得すると、有効期限が切れるまで保持します。次回セッションにバインドされたアクティビティが使用されるとき、Spring Cloud Vault は Vault に再ログインし、新しいセッショントークンを取得します。アプリケーションのシャットダウン時に、Spring Cloud Vault はトークンがまだアクティブである場合はそれを取り消し、セッションを終了します。

セッションライフサイクルはデフォルトで有効になっており、spring.cloud.vault.session.lifecycle.enabled を false に設定することで無効にできます。セッショントークンが期限切れになり、Spring Cloud Vault が Vault にアクセスできなくなる可能性があるため、無効にすることはお勧めできません。

spring.cloud.vault:
    session.lifecycle:
        enabled: true
        refresh-before-expiry: 10s
        expiry-threshold: 20s

  • enabled は、セッショントークンを更新するためにセッションライフサイクル管理を有効にするかどうかを制御します。デフォルトで有効になっています。

  • refresh-before-expiry は、セッショントークンがリフレッシュされる時点を制御します。リフレッシュ時間は、トークンの有効期限から refresh-before-expiry を減算して計算されます。デフォルトは 5 seconds です。

  • expiry-threshold は有効期限のしきい値を設定します。しきい値は、セッショントークンが有効であると見なされる最小 TTL 期間を表します。TTL が短いトークンは期限切れとみなされ、使用されなくなります。トークンの有効期限が切れないようにするために、refresh-before-expiry より大きくする必要があります。デフォルトは 7 seconds です。

関連事項: Vault ドキュメント: トークンの更新 (英語)