Git バックエンド

EnvironmentRepository のデフォルトの実装では、Git バックエンドを使用します。これは、アップグレードや物理環境の管理、および変更の監査に非常に便利です。リポジトリの場所を変更するには、構成サーバー（たとえば、application.yml）で spring.cloud.config.server.git.uri 構成プロパティを設定できます。file: プレフィックスを付けて設定すると、サーバーがなくてもすばやく簡単に開始できるように、ローカルリポジトリから機能するはずです。ただし、その場合、サーバーはクローンを作成せずにローカルリポジトリで直接動作します（構成サーバーが「リモート」リポジトリに変更を加えることはないため、サーバーが裸でなくても問題ありません）。構成サーバーをスケールアップして高可用性を実現するには、サーバーのすべてのインスタンスが同じリポジトリを指すようにする必要があります。これにより、共有ファイルシステムのみが機能します。その場合でも、共有ファイルシステムリポジトリに ssh: プロトコルを使用することをお勧めします。これにより、サーバーはそれを複製し、ローカルの作業コピーをキャッシュとして使用できます。

このリポジトリ実装は、HTTP リソースの {label} パラメーターを git ラベル（コミット ID、ブランチ名、タグ）にマップします。git ブランチまたはタグ名にスラッシュ（/）が含まれている場合は、代わりに HTTP URL のラベルを特別な文字列 ({special-string}) で指定する必要があります（他の URL パスとのあいまいさを避けるため）。例: ラベルが foo/bar の場合、スラッシュを置き換えると、次のラベルになります: foo({special-string})bar。特別な文字列 ({special-string}) を含めることは、{application} パラメーターにも適用できます。curl などのコマンドラインクライアントを使用する場合は、URL の括弧に注意してください。シェルから一重引用符（''）でエスケープする必要があります。

SSL 証明書の検証をスキップする

構成サーバーによる Git サーバーの SSL 証明書の検証は、git.skipSslValidation プロパティを true （デフォルトは false）に設定することで無効にできます。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          skipSslValidation: true

接続タイムアウトの設定

構成サーバーが HTTP または SSH 接続を取得するために待機する時間を秒単位で構成できます。git.timeout プロパティを使用します (デフォルトは 5 です)。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          timeout: 4

GitURI のプレースホルダー

Spring Cloud Config サーバーは、{application} および {profile} （および必要に応じて {label} ですが、ラベルは git ラベルとして適用されることに注意してください）のプレースホルダーを持つ git リポジトリ URL をサポートします。次のような構造を使用して、「アプリケーションごとに 1 つのリポジトリ」ポリシーをサポートできます。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/myorg/\{application}

同様のパターンを使用して、{profile} を使用して、「プロファイルごとに 1 つのリポジトリ」ポリシーをサポートすることもできます。

さらに、{application} パラメーター内で特別な文字列 "({special-string})" を使用すると、次の例に示すように、複数の組織のサポートを有効にすることができます。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/\{application}

ここで、{application} は、リクエスト時に次の形式で提供されます: organization({special-string})application。

パターンマッチングと複数のリポジトリ

Spring Cloud Config には、アプリケーションとプロファイル名のパターンマッチングを使用した、より複雑な要件のサポートも含まれています。パターン形式は、次の例に示すように、ワイルドカードを使用した {application}/{profile} 名のコンマ区切りリストです（ワイルドカードで始まるパターンは引用符で囲む必要がある場合があることに注意してください）。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            simple: https://github.com/simple/config-repo
            special:
              pattern: special*/dev*,*special*/dev*
              uri: https://github.com/special/config-repo
            local:
              pattern: local*
              uri: file:/home/configsvc/config-repo

{application}/{profile} がどのパターンとも一致しない場合、spring.cloud.config.server.git.uri で定義されているデフォルトの URI を使用します。上記の例では、「単純な」リポジトリの場合、パターンは simple/* です（すべてのプロファイルで simple という名前の 1 つのアプリケーションにのみ一致します）。「ローカル」リポジトリは、すべてのプロファイルで local で始まるすべてのアプリケーション名と一致します（/* サフィックスは、プロファイルマッチャーがないパターンに自動的に追加されます）。

「単純な」例で使用されている「ワンライナー」ショートカットは、設定するプロパティが URI のみである場合にのみ使用できます。他の何か（資格情報、パターンなど）を設定する必要がある場合は、完全なフォームを使用する必要があります。

リポジトリの pattern プロパティは実際には配列であるため、YAML 配列（またはプロパティファイルの [0]、[1] などのサフィックス）を使用して複数のパターンにバインドできます。次の例に示すように、複数のプロファイルを使用してアプリを実行する場合は、これを行う必要がある場合があります。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            development:
              pattern:
                - '*/development'
                - '*/staging'
              uri: https://github.com/development/config-repo
            staging:
              pattern:
                - '*/qa'
                - '*/production'
              uri: https://github.com/staging/config-repo
Spring Cloud は、* で終わらないプロファイルを含むパターンは、このパターンで始まるプロファイルのリストと実際に一致させたいことを意味すると推測します（したがって、*/staging は ["*/staging", "*/staging,*"] のショートカットなどです）。これは、たとえば、「開発」プロファイルでアプリケーションをローカルで実行する必要がある場合や、「クラウド」プロファイルでリモートで実行する必要がある場合によく見られます。

すべてのリポジトリは、オプションで構成ファイルをサブディレクトリに保存することもでき、それらのディレクトリを検索するパターンは search-paths として指定できます。次の例は、最上位の構成ファイルを示しています。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          search-paths:
            - foo
            - bar*

前の例では、サーバーはトップレベルと foo/ サブディレクトリ、および名前が bar で始まるサブディレクトリで構成ファイルを検索します。

デフォルトでは、サーバーは、構成が最初にリクエストされたときにリモートリポジトリのクローンを作成します。次のトップレベルの例に示すように、起動時にリポジトリのクローンを作成するようにサーバーを構成できます。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          repos:
            team-a:
                pattern: team-a-*
                cloneOnStart: true
                uri: https://git/team-a/config-repo.git
            team-b:
                pattern: team-b-*
                cloneOnStart: false
                uri: https://git/team-b/config-repo.git
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git

前の例では、サーバーは、リクエストを受け入れる前に、起動時に team-a の config-repo のクローンを作成します。他のすべてのリポジトリは、リポジトリからの構成がリクエストされるまで複製されません。

構成サーバーの起動時にクローンを作成するようにリポジトリを設定すると、構成サーバーの起動中に、誤って構成された構成ソース（無効なリポジトリ URI など）をすばやく特定できます。構成ソースに対して cloneOnStart が有効になっていない場合、構成サーバーは、構成が誤っているか無効な構成ソースで正常に起動し、アプリケーションがその構成ソースから構成をリクエストするまでエラーを検出しない場合があります。

認証

リモートリポジトリで HTTP 基本認証を使用するには、次の例に示すように、username プロパティと password プロパティを別々に（URL ではなく）追加します。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          username: trolley
          password: strongpassword

HTTPS とユーザー資格情報を使用しない場合、デフォルトのディレクトリ（~/.ssh）にキーを格納し、URI が [email protected] (英語) :configuration/cloud-configuration などの SSH の場所を指すときに、SSH もすぐに機能するはずです。Git サーバーのエントリが ~/.ssh/known_hosts ファイルに存在し、ssh-rsa 形式であることが重要です。他の形式（ecdsa-sha2-nistp256 など）はサポートされていません。予期しない事態を避けるために、Git サーバーの known_hosts ファイルにエントリが 1 つだけ存在し、それが構成サーバーに指定した URL と一致することを確認する必要があります。URL でホスト名を使用する場合は、known_hosts ファイルに（IP ではなく）正確にホスト名を含める必要があります。リポジトリには JGit を使用してアクセスするため、そこにあるドキュメントはすべて適用可能です。HTTPS プロキシ設定は、~/.git/config で設定するか、（他の JVM プロセスの場合と同じように）システムプロパティ（-Dhttps.proxyHost および -Dhttps.proxyPort）で設定できます。

~/.git ディレクトリがどこにあるかわからない場合は、git config --global を使用して設定を操作します（たとえば、git config --global http.sslVerify false）。

JGit には、PEM 形式の RSA キーが必要です。以下は、corect 形式でキーを生成する ssh-keygen（openssh から）コマンドの例です。

ssh-keygen -m PEM -t rsa -b 4096 -f ~/config_server_deploy_key.rsa

警告: SSH キーを使用する場合、予想される ssh 秘密鍵は -----BEGIN RSA PRIVATE KEY----- で始まる必要があります。キーが -----BEGIN OPENSSH PRIVATE KEY----- で始まる場合、spring-cloud-config サーバーの起動時に RSA キーはロードされません。エラーは次のようになります。

- Error in object 'spring.cloud.config.server.git': codes [PrivateKeyIsValid.spring.cloud.config.server.git,PrivateKeyIsValid]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [spring.cloud.config.server.git.,]; arguments []; default message []]; default message [Property 'spring.cloud.config.server.git.privateKey' is not a valid private key]

上記のエラーを修正するには、RSA キーを PEM 形式に変換する必要があります。適切な形式で新しいキーを生成するために、openssh を使用した例を上に示します。

AWS CodeCommit による認証

Spring Cloud Config サーバーは AWS CodeCommit [Amazon] 認証もサポートしています。AWS CodeCommit は、コマンドラインから Git を使用するときに認証ヘルパーを使用します。このヘルパーは JGit ライブラリでは使用されないため、GitURI が AWS CodeCommit パターンと一致する場合、AWSCodeCommit 用の JGit CredentialProvider が作成されます。AWS CodeCommit URI は次のパターンに従います。

https://git-codecommit.${AWS_REGION}.amazonaws.com/v1/repos/${repo}

AWS CodeCommit URI でユーザー名とパスワードを指定する場合、リポジトリへのアクセスを提供する AWS accessKeyId および secretAccessKey [Amazon] である必要があります。ユーザー名とパスワードを指定しない場合は、デフォルトのクレデンシャルプロバイダーチェーン [Amazon] を使用して accessKeyId と secretAccessKey が取得されます。

GitURI が CodeCommit URI パターン（前に表示）と一致する場合は、ユーザー名とパスワード、またはデフォルトの認証情報プロバイダーチェーンでサポートされている場所の 1 つで有効な AWS 認証情報を提供する必要があります。AWSEC2 インスタンスは EC2 インスタンスの IAM ロール [Amazon] を使用できます。

software.amazon.awssdk:auth jar はオプションの依存関係です。software.amazon.awssdk:auth jar がクラスパスにない場合、git サーバーの URI に関係なく、AWS CodeCommit 認証情報プロバイダーは作成されません。

Google クラウドソースによる認証

Spring Cloud Config サーバーは、Google クラウドソース リポジトリに対する認証もサポートしています。

Git URI が http または https プロトコルを使用し、ドメイン名が source.developers.google.com の場合は、Google クラウドソース資格情報プロバイダーが使用されます。Google クラウドソースリポジトリ URI の形式は source.developers.google.com/p/${GCP_PROJECT}/r/${REPO} (英語) です。リポジトリの URI を取得するには、Google クラウドソース UI で クローンをクリックし、手動で生成された資格情報 を選択します。資格情報は生成せず、表示された URI をコピーするだけです。

Google クラウドソース認証情報プロバイダーは、Google クラウドプラットフォームアプリケーションのデフォルト認証情報を使用します。システムのアプリケーションのデフォルト資格情報を作成する方法については、Google クラウド SDK ドキュメント を参照してください。このアプローチは、開発環境のユーザーアカウントと運用環境のサービスアカウントで機能します。

com.google.auth:google-auth-library-oauth2-http はオプションの依存関係です。google-auth-library-oauth2-http jar がクラスパス上にない場合、git サーバー URI に関係なく、Google クラウドソース資格情報プロバイダーは作成されません。

プロパティを使用した GitSSH 構成

デフォルトでは、Spring Cloud Config サーバーが使用する JGit ライブラリは、SSH URI を使用して Git リポジトリに接続するときに、~/.ssh/known_hosts や /etc/ssh/ssh_config などの SSH 構成ファイルを使用します。Cloud Foundry などのクラウド環境では、ローカルファイルシステムが一時的であるか、簡単にアクセスできない場合があります。このような場合、SSH 構成は Java プロパティを使用して設定できます。プロパティベースの SSH 構成をアクティブ化するには、次の例に示すように、spring.cloud.config.server.git.ignoreLocalSshSettings プロパティを true に設定する必要があります。

  spring:
    cloud:
      config:
        server:
          git:
            uri: [email protected] (英語)  :team/repo1.git
            ignoreLocalSshSettings: true
            hostKey: someHostKey
            hostKeyAlgorithm: ssh-rsa
            privateKey: |
                         -----BEGIN RSA PRIVATE KEY-----
                         MIIEpgIBAAKCAQEAx4UbaDzY5xjW6hc9jwN0mX33XpTDVW9WqHp5AKaRbtAC3DqX
                         IXFMPgw3K45jxRb93f8tv9vL3rD9CUG1Gv4FM+o7ds7FRES5RTjv2RT/JVNJCoqF
                         ol8+ngLqRZCyBtQN7zYByWMRirPGoDUqdPYrj2yq+ObBBNhg5N+hOwKjjpzdj2Ud
                         1l7R+wxIqmJo1IYyy16xS8WsjyQuyC0lL456qkd5BDZ0Ag8j2X9H9D5220Ln7s9i
                         oezTipXipS7p7Jekf3Ywx6abJwOmB0rX79dV4qiNcGgzATnG1PkXxqt76VhcGa0W
                         DDVHEEYGbSQ6hIGSh0I7BQun0aLRZojfE3gqHQIDAQABAoIBAQCZmGrk8BK6tXCd
                         fY6yTiKxFzwb38IQP0ojIUWNrq0+9Xt+NsypviLHkXfXXCKKU4zUHeIGVRq5MN9b
                         BO56/RrcQHHOoJdUWuOV2qMqJvPUtC0CpGkD+valhfD75MxoXU7s3FK7yjxy3rsG
                         EmfA6tHV8/4a5umo5TqSd2YTm5B19AhRqiuUVI1wTB41DjULUGiMYrnYrhzQlVvj
                         5MjnKTlYu3V8PoYDfv1GmxPPh6vlpafXEeEYN8VB97e5x3DGHjZ5UrurAmTLTdO8
                         +AahyoKsIY612TkkQthJlt7FJAwnCGMgY6podzzvzICLFmmTXYiZ/28I4BX/mOSe
                         pZVnfRixAoGBAO6Uiwt40/PKs53mCEWngslSCsh9oGAaLTf/XdvMns5VmuyyAyKG
                         ti8Ol5wqBMi4GIUzjbgUvSUt+IowIrG3f5tN85wpjQ1UGVcpTnl5Qo9xaS1PFScQ
                         xrtWZ9eNj2TsIAMp/svJsyGG3OibxfnuAIpSXNQiJPwRlW3irzpGgVx/AoGBANYW
                         dnhshUcEHMJi3aXwR12OTDnaLoanVGLwLnkqLSYUZA7ZegpKq90UAuBdcEfgdpyi
                         PhKpeaeIiAaNnFo8m9aoTKr+7I6/uMTlwrVnfrsVTZv3orxjwQV20YIBCVRKD1uX
                         VhE0ozPZxwwKSPAFocpyWpGHGreGF1AIYBE9UBtjAoGBAI8bfPgJpyFyMiGBjO6z
                         FwlJc/xlFqDusrcHL7abW5qq0L4v3R+FrJw3ZYufzLTVcKfdj6GelwJJO+8wBm+R
                         gTKYJItEhT48duLIfTDyIpHGVm9+I1MGhh5zKuCqIhxIYr9jHloBB7kRm0rPvYY4
                         VAykcNgyDvtAVODP+4m6JvhjAoGBALbtTqErKN47V0+JJpapLnF0KxGrqeGIjIRV
                         cYA6V4WYGr7NeIfesecfOC356PyhgPfpcVyEztwlvwTKb3RzIT1TZN8fH4YBr6Ee
                         KTbTjefRFhVUjQqnucAvfGi29f+9oE3Ei9f7wA+H35ocF6JvTYUsHNMIO/3gZ38N
                         CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
                         q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
                         69pcVH/4rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
                         -----END RSA PRIVATE KEY-----

次の表に、SSH 構成プロパティを示します。

表 1: SSH 構成プロパティ
プロパティ名 コメント

ignoreLocalSshSettings

true の場合、ファイルベースの SSH 構成ではなくプロパティベースを使用します。リポジトリ定義内ではなく、spring.cloud.config.server.git.ignoreLocalSshSettings として設定する必要があります。

privateKey

有効な SSH 秘密鍵。ignoreLocalSshSettings が true で、GitURI が SSH 形式の場合に設定する必要があります。

hostKey

有効な SSH ホストキー。hostKeyAlgorithm も設定されている場合は、設定する必要があります。

hostKeyAlgorithm

ssh-dss, ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521 の 1 つ。hostKey も設定されている場合は、設定する必要があります。

strictHostKeyChecking

true または false。false の場合、ホストキーのエラーを無視します。

knownHostsFile

カスタム .known_hosts ファイルの場所。

preferredAuthentications

サーバー認証方式の順序を上書きします。これにより、サーバーが publickey メソッドの前にキーボード対話型認証を使用している場合にログインプロンプトを回避できるようになります。

Git 検索パスのプレースホルダー

Spring Cloud Config サーバーは、次の例に示すように、{application} および {profile} （および必要に応じて {label}）のプレースホルダーを使用した検索パスもサポートします。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          search-paths: '\{application}'

上記のリストにより、リポジトリでディレクトリと同じ名前のファイル（およびトップレベル）が検索されます。ワイルドカードは、プレースホルダーを使用した検索パスでも有効です（一致するディレクトリはすべて検索に含まれます）。

Git リポジトリを強制的にプル

前述のように、Spring Cloud Config サーバーがリモートリポジトリからローカルコピーを更新できないように、ローカルコピーがダーティ（OS プロセスによるフォルダーコンテンツの変更など）になった場合に備えて、Spring Cloud Config サーバーはリモート git リポジトリのクローンを作成します。

この課題を解決するために、次の例に示すように、ローカルコピーがダーティの場合に Spring Cloud Config サーバーがリモートリポジトリから強制的にプルするようにする force-pull プロパティがあります。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          force-pull: true

複数のリポジトリを構成している場合は、次の例に示すように、リポジトリごとに force-pull プロパティを構成できます。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          force-pull: true
          repos:
            team-a:
                pattern: team-a-*
                uri: https://git/team-a/config-repo.git
                force-pull: true
            team-b:
                pattern: team-b-*
                uri: https://git/team-b/config-repo.git
                force-pull: true
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git
force-pull プロパティのデフォルト値は false です。

Git リポジトリで追跡されていないブランチを削除する

Spring Cloud Config サーバーはブランチをローカルリポジトリにチェックアウトした後（ラベルによるプロパティのフェッチなど）にリモート git リポジトリのクローンを持っているため、このブランチは永久に、または次のサーバーの再起動（新しいローカルリポジトリを作成する）まで保持されます。そのため、リモートブランチが削除されても、そのローカルコピーは引き続きフェッチできる場合があります。また、Spring Cloud Config サーバークライアントサービスが --spring.cloud.config.label=deletedRemoteBranch,master で開始する場合、プロパティは deletedRemoteBranch ローカルブランチからフェッチされますが、master からはフェッチされません。

ローカルリポジトリブランチをクリーンで最大リモートに保つために、deleteUntrackedBranches プロパティを設定できます。これにより、Spring Cloud Config サーバーは追跡されていないブランチをローカルリポジトリから強制的に削除します。例:

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          deleteUntrackedBranches: true
deleteUntrackedBranches プロパティのデフォルト値は false です。

Git リフレッシュレート

spring.cloud.config.server.git.refreshRate を使用すると、構成サーバーが Git バックエンドからリフレッシュされた構成データを取得する頻度を制御できます。このプロパティの値は秒単位で指定します。デフォルトでは値は 0 で、構成サーバーはリクエストされるたびに Git リポジトリからリフレッシュされた構成を取得します。値が負の数の場合、リフレッシュは行われません。

デフォルトのラベル

Git に使用されるデフォルトのラベルは main です。spring.cloud.config.server.git.defaultLabel を設定せず、main という名前のブランチが存在しない場合、構成サーバーはデフォルトで master という名前のブランチもチェックアウトしようとします。フォールバックブランチ動作を無効にする場合は、spring.cloud.config.server.git.tryMasterBranch を false に設定できます。

コンテナー内で Git を使用して構成サーバーを実行する

次のようなコンテナーで 構成サーバーを実行しているときに java.io.IOException が発生する場合:

2022-01-03 20:04:02,892 [tributeWriter-2] ERROR org.eclipse.jgit.util.FS$FileStoreAttributes.saveToConfig - Cannot save config file 'FileBasedConfig[/.config/jgit/config]'
java.io.IOException: Creating directories for /.config/jgit failed

次のいずれかを実行する必要があります。

  1. コンテナー内に書き込み可能なホームディレクトリをユーザーに提供します。

  2. コンテナー内の環境変数 XDG_CONFIG_HOME を、Java プロセスが書き込み権限を持つディレクトリを指すように設定します。