Imports

spring.config.import reads more configuration from inside a config file, or from the command line. Use it to split a large configuration into several files, or to add what an operator provides: local overrides, mounted secrets, a file on a config server.

Why

One application.yml for everything grows hard to read. Imports let each concern have its own file (db.yml, themes/ocean.yml) while the application still sees one set of keys. They also connect the configuration to its environment: a Kubernetes secret mounted as files, or an override file that exists only on one machine.

Example

# lib/resources/application.yml
spring:
  config:
    import:
      - resources:db.yml                 # packaged, required
      - optional:file:./local.yml        # next to the program, may be missing
      - optional:configtree:/run/secrets/  # Kubernetes or Docker secrets
shop:
  title: NEON Books
# lib/resources/application.properties: the same
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>

Location forms

The same forms work in spring.config.import, spring.config.location and spring.config.additional-location.

Form What is read Notes
resources:db.yml A file of lib/resources/, embedded by the generator Works in every build: VM, AOT, Flutter, web
resources:config/ A directory of lib/resources/: the application* files in it (or those of spring.config.name) Counts as found only when a file is found in it
file:./local.yml A file of the file system Not on the web
file:./config/ A directory: its application* files Must end with /
file:./config/*/ Each subdirectory, in alphabetical order One *, as the last directory; file:./config/*/app.yml reads that file in each
local.yml A plain path: a file, as with file:. In an import, relative to the importing file A resources: file imports resources: siblings this way
optional:... Any of the above; missing is fine Put before the whole location
file:./conf[.yml] A file without a known extension, read as YAML The hint is matched without case
file:./legacy.properties[encoding=iso-8859-1] A .properties file in that encoding UTF-8, ISO-8859-1, US-ASCII (Java's names and aliases). YAML is always UTF-8
file:./legacy.conf[.properties][encoding=latin1] Both hints, in any order
configtree:/run/secrets/ A config tree: each file is one property See Config trees
configtree:/run/*/ Each subdirectory as a config tree
https://cfg.example.com/shop.yml A file over HTTP or HTTPS Asynchronous start only; see HTTP
package:shop_defaults/defaults.yml A file of a Dart package, through the program's package config Not on the web nor in AOT executables
asset:config/shop.yml A Flutter asset With spring_boot_starter_flutter; read asynchronously
x;y A group: one location made of several Optional when its first entry is optional:; found when any entry finds something

A location without a known extension (.properties, .yml, .yaml) must end with / (a directory) or carry an extension hint. Other formats need a PropertySourceLoader of your own, given to ConfigDataEnvironment(loaders:).

Precedence

Placeholders in imports

${...} in an import is resolved against the command line, the environment and the documents read so far, when the importing document's imports are read:

spring:
  config:
    import: optional:file:${SHOP_CONFIG_DIR:/etc/shop}/shop.yml

An optional: import whose placeholder cannot be resolved is skipped. A required one fails the start.

Imports in profile files

An import in a profile file (application-prod.yml) or in a document limited to a profile is read only with that profile, and it is as required as any other: a missing required file fails the start. Use it for files that exist only in one environment:

# lib/resources/application-prod.yml
spring:
  config:
    import: configtree:/run/secrets/

Config trees

Kubernetes mounts secrets and config maps as directories of files, and Docker does the same with secrets. A configtree: location reads such a directory: every file below it is one property named by its path, whose value is the file's content.

/run/secrets/
  db/
    password        "s3cret\n"   โ†’ db.password=s3cret
  mail.api-key      "abc"        โ†’ mail.api-key=abc

Over HTTP

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

Your own kind of location

Two extension points cover what the built-in forms do not.

A ProtocolResolver teaches the resource loader a prefix. Config imports, @PropertySource and @Value resources then accept it:

// memory:shop.yml served from a map, for a tool or a test.
final application = SpringApplication(
  [appBeans],
  resourceLoader: DefaultResourceLoader(
    protocolResolvers: [
      InMemoryProtocolResolver('memory:', {'shop.yml': 'shop:\n  title: Test\n'}),
    ],
  ),
);
// spring.config.import=memory:shop.yml

An EnvironmentPostProcessor changes the environment before any bean exists: it can fetch settings from a server, add a property source, activate profiles or add imports. One ordered before EnvironmentPostProcessor.configDataOrder runs before the files are read:

// Imports the secret files the operators mount in ./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()],
);

Not supported

In Spring (Java)

The same key and the same rules as Spring Boot's spring.config.import, except:

See also