インポート

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 が必要です。

優先順位

インポートのプレースホルダー

インポートの ${...} は、インポート元のドキュメントのインポートが読まれるときに、コマンドライン、環境変数、それまでに読まれたドキュメントに対して解決されます。

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

HTTP 経由で

dart run bin/main.dart --spring.config.import=optional:https://config.neon.books/shop.yml

独自の種類のロケーション

組み込みの形式でまかなえないものは、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()],
);

対応していないもの

Spring (Java) との対応

キーもルールも Spring Boot の spring.config.import と同じです。ただし:

関連項目