インポート
spring.config.import は、設定ファイルの中から、またはコマンドラインから、追加の設定を読みます。大きな設定を複数のファイルに分割したり、運用担当者が用意するもの (ローカルの上書き、マウントされたシークレット、設定サーバー上のファイル) を追加したりするのに使います。
使う理由
すべてを一つの application.yml に入れると、読みにくくなっていきます。インポートを使えば、関心ごとにファイルを分けつつ (db.yml、themes/ocean.yml)、アプリケーションからは一つのキーの集まりとして見えます。また、設定をその環境に結び付けます。ファイルとしてマウントされた Kubernetes のシークレットや、あるマシンにだけ存在する上書きファイルなどです。
例
# lib/resources/application.yml
spring:
config:
import:
- resources:db.yml # パッケージに含まれる。必須
- optional:file:./local.yml # プログラムの隣。なくてもよい
- optional:configtree:/run/secrets/ # Kubernetes や Docker のシークレット
shop:
title: NEON Books
# lib/resources/application.properties: 同じ内容
spring.config.import=resources:db.yml,optional:file:./local.yml,optional:configtree:/run/secrets/
shop.title=NEON Books
# lib/resources/db.yml
db:
url: postgres://localhost/shop
pool-size: 5
/run/secrets/db/password → db.password=<the file's content>
ロケーションの形式
同じ形式が spring.config.import、spring.config.location、spring.config.additional-location で使えます。
| 形式 | 読まれるもの | 備考 |
|---|---|---|
resources:db.yml |
lib/resources/ のファイル。ジェネレーターが埋め込む |
VM、AOT、Flutter、Web のどのビルドでも動く |
resources:config/ |
lib/resources/ のディレクトリ: その中の application* ファイル (または spring.config.name のもの) |
その中でファイルが見つかったときだけ、見つかったとみなされる |
file:./local.yml |
ファイルシステムのファイル | Web では使えない |
file:./config/ |
ディレクトリ: その application* ファイル |
/ で終わらなければならない |
file:./config/*/ |
各サブディレクトリ。アルファベット順 | * は一つで、最後のディレクトリとして。file:./config/*/app.yml は各サブディレクトリのそのファイルを読む |
local.yml |
単なるパス: file: と同じくファイル。インポートでは、インポート元のファイルからの相対パス |
resources: のファイルは、この方法で隣の resources: のファイルをインポートする |
optional:... |
上記のいずれか。なくてもよい | ロケーション全体の前に付ける |
file:./conf[.yml] |
既知の拡張子のないファイルを YAML として読む | ヒントは大文字小文字を区別せずに照合される |
file:./legacy.properties[encoding=iso-8859-1] |
そのエンコーディングの .properties ファイル |
UTF-8、ISO-8859-1、US-ASCII (Java の名前と別名)。YAML は常に UTF-8 |
file:./legacy.conf[.properties][encoding=latin1] |
両方のヒント。順序は問わない | |
configtree:/run/secrets/ |
設定ツリー: 各ファイルが一つのプロパティ | 設定ツリー を参照 |
configtree:/run/*/ |
各サブディレクトリを設定ツリーとして | |
https://cfg.example.com/shop.yml |
HTTP または HTTPS 経由のファイル | 非同期の起動のみ。HTTP を参照 |
package:shop_defaults/defaults.yml |
プログラムのパッケージ設定を通した、Dart パッケージのファイル | Web でも AOT の実行ファイルでも使えない |
asset:config/shop.yml |
Flutter のアセット | spring_boot_starter_flutter が必要。非同期に読まれる |
x;y |
グループ: 複数からなる一つのロケーション | 最初のエントリーが optional: なら任意。どれかのエントリーが何かを見つければ、見つかったとみなされる |
既知の拡張子 (.properties、.yml、.yaml) のないロケーションは、/ で終わる (ディレクトリ) か、拡張子のヒントを持たなければなりません。他の形式には、ConfigDataEnvironment(loaders:) に渡す独自の PropertySourceLoader が必要です。
優先順位
- インポートされたファイルは、それをインポートしたファイルを上書きします。
- インポートされたファイルはそれ自身の
-{profile}版を持ち、それはインポート元のファイルのプロファイルのファイルより優先されます。application.ymlがdb.ymlをインポートすると、db-dev.ymlはapplication-dev.ymlより優先されます。 - 相対ロケーションは、インポート元のファイルからの相対です。
- コマンドライン (
--spring.config.import=...) やSPRING_CONFIG_IMPORTで指定したインポートは、すべてのロケーションより上のグループになります。 - ファイルは一度だけ読まれるため、インポートの循環は害になりません。複数の場所で指定されたファイルは、優先される場所で数えられます。リストの後の項目、
additional-locationより前のコマンドラインのインポート、ロケーションより前のadditional-locationです。その場所に書かれたエンコーディングのヒントが適用されます。
インポートのプレースホルダー
インポートの ${...} は、インポート元のドキュメントのインポートが読まれるときに、コマンドライン、環境変数、それまでに読まれたドキュメントに対して解決されます。
spring:
config:
import: optional:file:${SHOP_CONFIG_DIR:/etc/shop}/shop.yml
プレースホルダーを解決できない optional: のインポートはスキップされます。必須のものは起動を失敗させます。
プロファイルのファイルでのインポート
プロファイルのファイル (application-prod.yml) や、プロファイルに限定されたドキュメントの中のインポートは、そのプロファイルでだけ読まれ、他のインポートと同じく必須です。必須のファイルがないと起動が失敗します。ある環境にだけ存在するファイルに使います。
# lib/resources/application-prod.yml
spring:
config:
import: configtree:/run/secrets/
設定ツリー
Kubernetes はシークレットや ConfigMap をファイルのディレクトリとしてマウントし、Docker もシークレットで同じことをします。configtree: のロケーションはそうしたディレクトリを読みます。その下の各ファイルが、パスを名前とし、ファイルの内容を値とする一つのプロパティになります。
/run/secrets/
db/
password "s3cret\n" → db.password=s3cret
mail.api-key "abc" → mail.api-key=abc
- ロケーションは
optional:のものでも/で終わらなければならず、そうでなければ起動が失敗します。 - 各値から末尾の改行が一つ取り除かれます。
- 名前が
..で始まるエントリー (Kubernetes の内部リンク) はスキップされます。 - ディレクトリがない必須のツリーは起動を失敗させます。ワイルドカードでは、サブディレクトリのないものが失敗させます。
- 値は文字列で、他のプロパティと同じようにバインドされ、変換されます。
- 読まれるのはファイルシステムのディレクトリだけなので、Web では使えません。
HTTP 経由で
dart run bin/main.dart --spring.config.import=optional:https://config.neon.books/shop.yml
- ファイルは
GETリクエストで取得されます。400 以上のステータスは読み込みを失敗させます。 optional:の HTTP ロケーションは、まずHEADリクエストで確認されます (サーバーがHEADを拒否すればGET)。404 や接続エラーではスキップされます。- 読み込みは非同期なので、アプリケーションは
runApplicationAsync(またはSpringApplication.runAsync。Flutter アプリはこちらを使います) で起動しなければなりません。同期的なrunApplicationはthe resource can only be read asynchronously; use processAndApply()で失敗します。 - 読み込みには
dart:ioが必要なので、Flutter の Web アプリでは動きません。 - ヘッダー、クレデンシャル、リトライは送られません。トークンが必要なサーバーや Vault には、
EnvironmentPostProcessor(下記) や独自のProtocolResolverで値を自分で追加してください。
独自の種類のロケーション
組み込みの形式でまかなえないものは、2 つの拡張ポイントでカバーします。
ProtocolResolver はリソースローダーにプレフィックスを教えます。そうすると、設定のインポート、@PropertySource、@Value のリソースがそれを受け入れます。
// ツールやテストのために、マップから配信される memory:shop.yml。
final application = SpringApplication(
[appBeans],
resourceLoader: DefaultResourceLoader(
protocolResolvers: [
InMemoryProtocolResolver('memory:', {'shop.yml': 'shop:\n title: Test\n'}),
],
),
);
// spring.config.import=memory:shop.yml
EnvironmentPostProcessor は、どの Bean も存在する前に Environment を変更します。サーバーから設定を取得したり、プロパティソースを追加したり、プロファイルを有効にしたり、インポートを追加したりできます。EnvironmentPostProcessor.configDataOrder より前に順序付けられたものは、ファイルが読まれる前に実行されます。
// 運用担当者が ./secrets/ にマウントするシークレットのファイルをインポートする。
class LocalSecrets implements EnvironmentPostProcessor, Ordered {
@override
int get order => EnvironmentPostProcessor.configDataOrder - 1;
@override
void postProcessEnvironment(
ConfigurableEnvironment environment,
SpringApplication application,
) {
environment.propertySources.addLast(
MapPropertySource('secrets', {
'spring.config.import': 'optional:file:./secrets/',
}),
);
}
}
final application = SpringApplication(
[appBeans],
environmentPostProcessors: [LocalSecrets()],
);
対応していないもの
env:のインポート。- 設定ロケーションでの
resources*:とクラスパスのワイルドカード。 - XML のプロパティファイル (
x.xmlは起動を失敗させます。optional:のものはスキップされます)。 - Spring Cloud Config、Consul、Vault のクライアント:
configserver:やvault:のロケーションはありません。HTTP のインポートかEnvironmentPostProcessorを使ってください。
Spring (Java) との対応
キーもルールも Spring Boot の spring.config.import と同じです。ただし:
;のグループの各エントリーはそれぞれのプレフィックスで読まれるため、x.yml;configtree:/run/secrets/はツリーを読みます。Spring Boot はグループ全体のリゾルバーを最初のエントリーから選びます。- ワイルドカードのロケーションで見つかったファイル内の相対インポートは、そのファイルからの相対です。Spring Boot はワイルドカードのパターンを基準に解決します。
- ファイルである
configtree:のロケーションはないものとみなされるため、optional:ならスキップされます。Spring Boot は失敗します。 - インポートのプレースホルダーは、最初のパスではなく、インポートが読まれるときに解決されます。