これらの機能をアプリケーションで使用するには、spring-cloud-config-client に依存する Spring Boot アプリケーションとしてビルドできます（たとえば、config-client またはサンプルアプリケーションのテストケースを参照してください）。依存関係を追加する最も便利な方法は、Spring Boot スターター org.springframework.cloud:spring-cloud-starter-config を使用することです。Maven ユーザー用の親 pom および BOM（spring-cloud-starter-parent）と、Gradle および Spring CLI ユーザー用の Spring IO バージョン管理プロパティファイルもあります。次の例は、一般的な Maven 構成を示しています。

これで、次の HTTP サーバーなどの標準 Spring Boot アプリケーションを作成できます。

この HTTP サーバーが実行されると、ポート 8888 でデフォルトのローカル構成サーバー（実行中の場合）から外部構成が取得されます。起動動作を変更するには、に示すように application.properties を使用して構成サーバーの場所を変更できます。次の例:

デフォルトでは、アプリケーション名が設定されていない場合、application が使用されます。名前を変更するには、次のプロパティを application.properties ファイルに追加できます。

次の例に示すように、構成サーバーのプロパティは、優先度の高いプロパティソースとして /env エンドポイントに表示されます。

configserver:<URL of remote repository>/<file name> と呼ばれるプロパティソースには、bar の値を持つ foo プロパティが含まれています。

構成サーバーの構成データをどこに保存する必要がありますか？ この動作を管理する戦略は EnvironmentRepository であり、Environment オブジェクトを提供します。この Environment は、Spring Environment （主な機能として propertySources を含む）からのドメインの浅いコピーです。Environment リソースは、次の 3 つの変数によってパラメーター化されます。

リポジトリの実装は通常、Spring Boot アプリケーションのように動作し、{application} パラメーターに等しい spring.config.name、{profiles} パラメーターに等しい spring.profiles.active から構成ファイルをロードします。プロファイルの優先順位ルールも通常の Spring Boot アプリケーションと同じです。アクティブなプロファイルがデフォルトよりも優先され、複数のプロファイルがある場合は、最後のプロファイルが優先されます（Map へのエントリの追加と同様）。

次のサンプルクライアントアプリケーションには、このブートストラップ構成があります。

（Spring Boot アプリケーションでは通常どおり、これらのプロパティは環境変数またはコマンドライン引数によって設定することもできます）。

リポジトリがファイルベースの場合、サーバーは application.yml （すべてのクライアント間で共有）と foo.yml （foo.yml が優先）から Environment を作成します。YAML ファイル内に Spring プロファイルを指すドキュメントが含まれている場合、（リストされているプロファイルの順序で）より高い優先順位で適用されます。プロファイル固有の YAML（またはプロパティ）ファイルがある場合、これらもデフォルトよりも高い優先順位で適用されます。優先順位が高いほど、Environment で前述した PropertySource に変換されます。(これらの同じルールは、スタンドアロンの Spring Boot アプリケーションにも適用されます。)

アプリケーションが見つからない場合にサーバーが HTTP 404 ステータスを返すように、spring.cloud.config.server.accept-empty を false に設定できます。デフォルトでは、このフラグは true に設定されます。

構成サーバーには、構成された EnvironmentRepository が機能しているかどうかを確認するヘルスインジケーターが付属しています。デフォルトでは、app という名前のアプリケーション、default プロファイル、EnvironmentRepository 実装によって提供されるデフォルトのラベルを EnvironmentRepository に要求します。

次の例に示すように、カスタムプロファイルおよびカスタムラベルとともにより多くのアプリケーションをチェックするようにヘルスインジケーターを構成できます。

management.health.config.enabled=false を設定すると、ヘルスインジケーターを無効にできます。

また、プロパティ spring.cloud.config.server.health.down-health-status を設定することにより、独自のカスタム down ステータスを提供できます (デフォルトでは "DOWN' に値が設定されます)。

Spring Security と Spring Boot は多くのセキュリティ構成をサポートしているため、（物理ネットワークセキュリティから OAuth2 ベアラートークンまで）自分にとって意味のある方法で ConfigServer を保護できます。

デフォルトの SpringBoot 構成 HTTP 基本セキュリティを使用するには、クラスパスに Spring Security を含めます（たとえば、spring-boot-starter-security を介して）。デフォルトは、user のユーザー名とランダムに生成されたパスワードです。ランダムパスワードは実際には役に立たないため、（spring.security.user.password を設定して）パスワードを構成し、暗号化することをお勧めします（その方法については以下を参照してください）。

リモートプロパティソースに暗号化されたコンテンツ（{cipher} で始まる値）が含まれている場合、HTTP 経由でクライアントに送信する前に復号化されます。この設定の主な利点は、プロパティ値が「静止」しているとき（たとえば、git リポジトリ内）にプレーンテキストである必要がないことです。値を復号化できない場合は、プロパティソースから削除され、同じキーが接頭辞として invalid と「該当なし」を意味する値（通常は <n/a>）が付いた追加のプロパティが追加されます。これは主に、暗号文がパスワードとして使用され、誤って漏洩するのを防ぐためです。

構成クライアントアプリケーション用にリモート構成リポジトリをセットアップする場合、次のような application.yml が含まれている可能性があります。

application.properties ファイルの暗号化された値は、引用符で囲むことはできません。それ以外の場合、値は復号化されません。次の例は、機能する値を示しています。

このプレーンテキストを共有 git リポジトリに安全にプッシュでき、シークレットパスワードは保護されたままになります。

サーバーは、/encrypt および /decrypt エンドポイントも公開します（これらが保護されており、認可されたエージェントによってのみアクセスされることを前提としています）。リモート構成ファイルを編集する場合、次の例に示すように、構成サーバーを使用して、/encrypt エンドポイントに POST することで値を暗号化できます。

次の例に示すように、逆の操作は /decrypt を介して利用することもできます（サーバーが対称鍵または完全鍵ペアで構成されている場合）。

暗号化された値を取得し、{cipher} プレフィックスを追加してから、YAML またはプロパティファイルに配置し、コミットしてリモート（安全でない可能性がある）ストアにプッシュします。

/encrypt エンドポイントと /decrypt エンドポイントはどちらも、/*/{application}/{profiles} の形式のパスを受け入れます。これを使用して、クライアントがメイン環境リソースを呼び出すときに、アプリケーションごと（名前）ごとおよびプロファイルごとに暗号化を制御できます。

次の例に示すように、spring コマンドラインクライアント（Spring Cloud CLI 拡張機能がインストールされている）を使用して、暗号化と復号化を行うこともできます。

次の例に示すように、ファイル内のキー（暗号化用の RSA 公開鍵など）を使用するには、キー値の前に "@" を付け、ファイルパスを指定します。

構成サーバーは、対称（共有）キーまたは非対称キー（RSA キーペア）を使用できます。非対称の選択はセキュリティの点で優れていますが、application.properties で構成する単一のプロパティ値であるため、対称キーを使用する方が便利な場合がよくあります。

対称鍵を構成するには、encrypt.key を秘密文字列に設定する必要があります（または、ENCRYPT_KEY 環境変数を使用してプレーンテキスト構成ファイルに入れないようにします）。

非対称キーを構成するには、キーストアを使用します（たとえば、JDK に付属の keytool ユーティリティによって作成されたもの）。キーストアのプロパティは encrypt.keyStore.* であり、* は次のようになります。

暗号化は公開鍵を使用して行われ、復号化には秘密鍵が必要です。原則として、暗号化のみを行う場合（および秘密鍵を使用してローカルで値を復号化する準備ができている場合）は、サーバーで公開鍵のみを構成できます。実際には、ローカルで復号化を実行したくない場合があります。これは、キー管理プロセスをサーバーに集中させるのではなく、すべてのクライアントに分散させるためです。一方、構成サーバーが比較的安全でなく、暗号化されたプロパティを必要とするクライアントがほんの一握りである場合は、便利なオプションになる可能性があります。

テスト用のキーストアを作成するには、次のようなコマンドを使用できます。

server.jks ファイルをクラスパス（たとえば）に配置してから、bootstrap.yml で、構成サーバー用に次の設定を作成します。

暗号化されたプロパティ値の {cipher} プレフィックスに加えて、構成サーバーは、（Base64 でエンコードされた）暗号文の開始前に 0 個以上の {name:value} プレフィックスを検索します。キーは TextEncryptorLocator に渡され、TextEncryptorLocator は、暗号の TextEncryptor を見つけるために必要なロジックを実行できます。キーストア（encrypt.keystore.location）を構成した場合、デフォルトのロケーターは、key プレフィックスによって提供されるエイリアスを持ち、次のような暗号文を持つキーを探します。

ロケーターは "testkey" という名前のキーを探します。シークレットは、プレフィックスに {secret:…​} 値を使用して提供することもできます。ただし、指定されていない場合、デフォルトではキーストアパスワードが使用されます（これは、キーストアを構築し、シークレットを指定しないときに取得するものです）。シークレットを提供する場合は、カスタム SecretLocator を使用してシークレットも暗号化する必要があります。

キーが数バイトの構成データの暗号化にのみ使用されている場合（つまり、他の場所では使用されていない場合）、暗号化の理由でキーのローテーションはほとんど必要ありません。ただし、場合によってはキーを変更する必要があります（たとえば、セキュリティ違反が発生した場合）。その場合、すべてのクライアントはソース構成ファイルを変更し（たとえば、git で）、すべての暗号で新しい {key:…​} プレフィックスを使用する必要があります。クライアントは、最初にキーエイリアスが ConfigServer キーストアで使用可能であることを確認する必要があることに注意してください。

サーバーで構成を行うのではなく、クライアントに構成をローカルで復号化させたい場合があります。その場合、キーを見つけるために encrypt.* 構成を提供すると、/encrypt エンドポイントと /decrypt エンドポイントを引き続き使用できますが、spring.cloud.config.server.encrypt.enabled=false を bootstrap.[yml|properties] に配置して、発信プロパティの復号化を明示的にオフにする必要があります。エンドポイントを気にしない場合は、キーまたは有効フラグのいずれも構成していなくても機能するはずです。

環境エンドポイントのデフォルトの JSON 形式は、Environment 抽象化に直接マップされるため、Spring アプリケーションでの使用に最適です。必要に応じて、リソースパスにサフィックス（".yml"、".yaml"、または ".properties" ）を追加することで、YAML または Java プロパティと同じデータを使用できます。これは、JSON エンドポイントの構造やそれらが提供する追加のメタデータを気にしないアプリケーションによる消費に役立ちます（たとえば、Spring を使用しないアプリケーションは、このアプローチの単純さから恩恵を受ける可能性があります）。

YAML およびプロパティ表現には追加のフラグ（resolvePlaceholders と呼ばれるブールクエリパラメーターとして提供）があり、可能な場合は、レンダリング前にソースドキュメント（標準の Spring ${…​} 形式）のプレースホルダーを解決する必要があることを通知します。これは、Spring プレースホルダーの規則について知らないコンシューマーにとって便利な機能です。

Environment 抽象化（または YAML またはプロパティ形式での Environment 抽象化の代替表現の 1 つ）を使用する代わりに、アプリケーションには、環境に合わせた汎用のプレーンテキスト構成ファイルが必要になる場合があります。構成サーバーは、/{application}/{profile}/{label}/{path} の追加エンドポイントを介してこれらを提供します。application、profile、label は通常の環境エンドポイントと同じ意味ですが、path はファイル名（log.xml など）へのパスです。このエンドポイントのソースファイルは、環境エンドポイントの場合と同じ方法で配置されます。プロパティと YAML ファイルに同じ検索パスが使用されます。ただし、一致するすべてのリソースを集約する代わりに、最初に一致したリソースのみが返されます。

リソースが検索された後、通常の形式（${…​}）のプレースホルダーは、指定されたアプリケーション名、プロファイル、ラベルに有効な Environment を使用して解決されます。このようにして、リソースエンドポイントは環境エンドポイントと緊密に統合されます。

現在、Spring Cloud Config は、git、SVN、ネイティブバックエンド、AWSS3 のプレーンテキストを提供できます。git、SVN、ネイティブバックエンドのサポートは同じです。AWSS3 の動作は少し異なります。次のセクションでは、それぞれがどのように機能するかを示します。

構成サーバーからバイナリファイルを提供するには、application/octet-stream の Accept ヘッダーを送信する必要があります。

構成サーバーは、スタンドアロンアプリケーションとして最適に実行されます。ただし、必要に応じて、別のアプリケーションに埋め込むことができます。これを行うには、@EnableConfigServer アノテーションを使用します。この場合、spring.cloud.config.server.bootstrap という名前のオプションのプロパティが役立ちます。これは、サーバーが独自のリモートリポジトリから自身を構成する必要があるかどうかを示すフラグです。デフォルトでは、起動が遅れる可能性があるため、フラグはオフになっています。ただし、別のアプリケーションに組み込む場合は、他のアプリケーションと同じ方法で初期化するのが理にかなっています。spring.cloud.config.server.bootstrap を true に設定する場合は、複合環境リポジトリ構成も使用する必要があります。たとえば

サーバーエンドポイントの場所を変更するには、（オプションで） spring.cloud.config.server.prefix （たとえば、/config）を設定して、プレフィックスでリソースを提供できます。プレフィックスは / で開始する必要がありますが、終了することはできません。これは、構成サーバーの @RequestMappings に適用されます（つまり、Spring Boot server.servletPath および server.contextPath プレフィックスの下）。

アプリケーションの構成を（構成サーバーからではなく）バックエンドリポジトリから直接読み取りたい場合は、基本的に、エンドポイントのない組み込み構成サーバーが必要です。@EnableConfigServer アノテーションを使用しないことでエンドポイントを完全にオフにすることができます（spring.cloud.config.server.bootstrap=true を設定）。

多くのソースコードリポジトリプロバイダー（Github、Gitlab、Gitea、Gitee、Gogs、Bitbucket など）は、Webhook を介してリポジトリの変更を通知します。プロバイダーのユーザーインターフェースを介して、関心のある URL および一連のイベントとして Webhook を構成できます。たとえば、Github (英語) は、コミットのリストと push に設定されたヘッダー（X-Github-Event）を含む JSON 本文を使用して Webhook への POST を使用します。spring-cloud-config-monitor ライブラリへの依存関係を追加し、構成サーバーで Spring Cloud Bus をアクティブ化すると、/monitor エンドポイントが有効になります。

Webhook がアクティブ化されると、構成サーバーは、変更された可能性があると思われるアプリケーションを対象とした RefreshRemoteApplicationEvent を送信します。変更の検出は戦略化できます。ただし、デフォルトでは、アプリケーション名に一致するファイルの変更を検索します（たとえば、foo.properties は foo アプリケーションを対象とし、application.properties はすべてのアプリケーションを対象とします）。動作をオーバーライドする場合に使用する戦略は PropertyPathNotificationExtractor です。これは、リクエストヘッダーと本文をパラメーターとして受け入れ、変更されたファイルパスのリストを返します。

デフォルトの構成は、Github、Gitlab、Gitea、Gitee、Gogs、Bitbucket でそのまま使用できます。Github、Gitlab、Gitee、Bitbucket からの JSON 通知に加えて、path={application} のパターンでフォームにエンコードされた本文パラメーターを使用して /monitor に POST することにより、変更通知をトリガーできます。そうすることで、{application} パターン（ワイルドカードを含めることができる）に一致するアプリケーションにブロードキャストします。

4.0.0 以降、Spring Cloud Config サーバーは Spring AOT 変換をサポートします。ただし、当面の間、GraalVM ネイティブイメージはサポートされていません。ネイティブイメージサポートの実装は graal#5134 [GitHub] (英語) によってブロックされており、おそらく修正するには https://github.com/graalvm/taming-build-time-initialization (英語) の作業を完了する必要があります。

Spring Boot 2.4 は、spring.config.import プロパティを介して構成データをインポートする新しい方法を導入しました。これが、ConfigServer にバインドするデフォルトの方法になりました。

オプションで構成サーバーに接続するには、application.properties で以下を設定します。

これにより、デフォルトの "http://localhost:8888" の場所にある構成サーバーに接続されます。optional: プレフィックスを削除すると、構成サーバーに接続できない場合、構成クライアントが失敗します。構成サーバーの場所を変更するには、spring.cloud.config.uri を設定するか、spring.config.import=optional:configserver:http://myhost:8888 などの spring.config.import ステートメントに URL を追加します。import プロパティの場所は、uri プロパティよりも優先されます。

Spring Boot Config Data は、2 段階のプロセスで構成を解決します。まず、default プロファイルを使用してすべての構成をロードします。これにより、Spring Boot は追加のプロファイルをアクティブ化する可能性のあるすべての構成を収集できるようになります。アクティブ化されたプロファイルをすべて収集した後、アクティブなプロファイルの追加構成をロードします。このため、設定を取得するために Spring Cloud Config サーバーに対して複数のリクエストが行われる場合があります。これは正常であり、spring.config.import の使用時に Spring Boot が構成をロードする方法の副作用です。Spring Cloud Config の以前のバージョンでは、リクエストは 1 つだけ行われていましたが、これは、構成サーバーからの構成からプロファイルをアクティブ化できないことを意味していました。「デフォルト」プロファイルのみを使用した追加リクエストにより、これが可能になります。

構成サーバーに接続する従来のブートストラップ方法を使用するには、プロパティまたは spring-cloud-starter-bootstrap スターターを介してブートストラップを有効にする必要があります。プロパティは spring.cloud.bootstrap.enabled=true です。システムプロパティまたは環境変数として設定する必要があります。ブートストラップが有効になると、クラスパスに Spring Cloud Config クライアントがあるアプリケーションは、次のように構成サーバーに接続します。構成クライアントが起動すると、構成サーバーにバインドし（spring.cloud.config.uri ブートストラップ構成プロパティを介して）、リモートプロパティソースを使用して Spring Environment を初期化します。

この動作の最終的な結果として、構成サーバーを使用するすべてのクライアントアプリケーションには、サーバーアドレスが spring.cloud.config.uri （デフォルトは "http://localhost:8888"）に設定された bootstrap.yml （または環境変数）が必要です。

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

アプリケーションの起動時に構成サーバーが時々利用不能になることが予想される場合は、失敗後も構成サーバーを試行し続けるようにすることができます。まず、spring.cloud.config.fail-fast=true を設定する必要があります。次に、spring-retry と spring-boot-starter-aop をクラスパスに追加する必要があります。デフォルトの動作では、初期バックオフ間隔 1000 ミリ秒と後続のバックオフの指数乗数 1.1 で 6 回再試行します。spring.cloud.config.retry.* 構成プロパティを設定することで、これらのプロパティ (およびその他) を構成できます。ランダム指数バックオフポリシーを使用するには、spring.cloud.config.retry.useRandomPolicy を true に設定します。

再試行は Spring Boot spring.config.import ステートメントで機能し、通常のプロパティが機能します。ただし、import ステートメントが application-prod.properties などのプロファイルにある場合は、再試行を構成する別の方法が必要です。構成は、インポートステートメントの URL パラメーターとして配置する必要があります。

これにより、spring.cloud.config.fail-fast=true (上記のプレフィックスが欠落していることに注意してください) と、使用可能なすべての spring.cloud.config.retry.* 構成プロパティが設定されます。

Config Service は、/{application}/{profile}/{label} からのプロパティソースを提供します。クライアントアプリのデフォルトのバインディングは次のとおりです。

spring.cloud.config.* （* は name、profile、label）を設定することにより、これらすべてをオーバーライドできます。label は、以前のバージョンの構成にロールバックできます。デフォルトの ConfigServer 実装では、git ラベル、ブランチ名、コミット ID にすることができます。ラベルは、コンマ区切りのリストとして提供することもできます。その場合、リスト内の項目は、成功するまで 1 つずつ試行されます。この動作は、機能ブランチで作業するときに役立ちます。たとえば、構成ラベルをブランチに合わせて、オプションにしたい場合があります（その場合は、spring.cloud.config.label=myfeature,develop を使用します）。

構成サーバーの複数のインスタンスがデプロイされていて、1 つ以上のインスタンスが利用できないか、(Git サーバーがダウンしている場合などに) 時々リクエストを受け入れることができないと予想される場合に、高可用性を確保するには、複数の URL を指定することができます ( spring.cloud.config.uri プロパティのコンマ区切りのリスト) またはすべてのインスタンスを Eureka のようなサービスレジストリに登録します (Discovery-First Bootstrap モードを使用している場合)。

spring.cloud.config.uri にリストされている URL は、リストされている順序で試行されます。デフォルトでは、構成クライアントは、高可用性を確保する試みが成功するまで、各 URL からプロパティを取得しようとします。

ただし、構成サーバーが実行されていないとき (つまり、アプリケーションが終了したとき) または接続タイムアウトが発生したときにのみ高可用性を確保したい場合は、spring.cloud.config.multiple-uri-strategy を connection-timeout-only に設定します。( spring.cloud.config.multiple-uri-strategy のデフォルト値は always です) 例: 構成サーバーが 500 (内部的サーバーエラー) レスポンスを返した場合、または構成クライアントが構成サーバーから 401 を受信した場合 (不正な資格情報またはその他の原因による)、構成クライアントは他の URL からプロパティを取得しようとしないでください。400 エラー (場合によっては 404 を除く) は、可用性の課題ではなく、ユーザーの課題を示します。構成サーバーが Git サーバーを使用するように設定されていて、Git サーバーへの呼び出しが失敗した場合、404 エラーが発生する可能性があることに注意してください。

spring.cloud.config.uri ではなく、1 つの spring.config.import キーで複数の場所を指定できます。ロケーションは定義された順序で処理され、後のインポートが優先されます。ただし、spring.cloud.config.fail-fast が true の場合、最初の構成サーバー呼び出しが何らかの理由で失敗すると、構成クライアントは失敗します。fail-fast が false の場合、失敗の理由に関係なく、1 つの呼び出しが成功するまですべての URL を試行します。(spring.config.import で URL を指定する場合、spring.cloud.config.multiple-uri-strategy は適用されません。)

構成サーバーで HTTP 基本セキュリティを使用している場合、現在、spring.cloud.config.uri プロパティで指定した各 URL に資格情報を埋め込んだ場合にのみ、ConfigServer ごとの認証資格情報をサポートできます。他の種類のセキュリティメカニズムを使用している場合、（現在）ConfigServer ごとの認証と認可をサポートすることはできません。

タイムアウトしきい値を構成する場合:

サーバーで HTTP 基本セキュリティを使用する場合、クライアントはパスワード（およびデフォルトでない場合はユーザー名）を知っている必要があります。次の例に示すように、ユーザー名とパスワードは、構成サーバーの URI を介して、または個別のユーザー名とパスワードのプロパティを介して指定できます。

次の例は、同じ情報を渡す別の方法を示しています。

spring.cloud.config.password および spring.cloud.config.username 値は、URI で提供されるすべてのものをオーバーライドします。

アプリを Cloud Foundry にデプロイする場合、パスワードを提供する最善の方法は、サービス資格情報を使用することです（URI など、構成ファイルに含める必要がないため）。次の例は、ローカルで、configserver という名前の Cloud Foundry 上のユーザー提供サービスに対して機能します。

構成サーバーでクライアント側の TLS 証明書が必要な場合は、次の例に示すように、プロパティを介してクライアント側の TLS 証明書とトラストストアを構成できます。

構成クライアント側 TLS を有効にするには、spring.cloud.config.tls.enabled が true である必要があります。spring.cloud.config.tls.trust-store を省略すると、JVM のデフォルトのトラストストアが使用されます。spring.cloud.config.tls.key-store-type および spring.cloud.config.tls.trust-store-type のデフォルト値は PKCS12 です。パスワードのプロパティを省略すると、空のパスワードが想定されます。

別の形式のセキュリティを使用する場合は、RestTemplate を ConfigServicePropertySourceLocator に提供する必要がある場合があります（たとえば、ブートストラップコンテキストでそれを取得して挿入することによって）。

Vault は、次の例に示すように、Vault に格納されている値にキーをネストする機能をサポートしています。

echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -

このコマンドは、JSON オブジェクトを Vault に書き込みます。Spring でこれらの値にアクセスするには、次の例に示すように、従来の dot（.）アノテーションを使用します。

上記のコードは、name 変数の値を appAsecret に設定します。

4.0.0 以降、Spring Cloud Config クライアントは Spring AOT 変換と GraalVM ネイティブイメージをサポートします。

以下に、このプロジェクトで宣言されたすべての指標のリストを示します。

以下に、このプロジェクトで宣言されたすべてのスパンのリストを示します。