Configs

Configs allow services to adapt their behaviour without the need to rebuild a Docker image.

Services can only access configs when explicitly granted by a configs attribute within the services top-level element.

Configs are project-scoped, which means that they can be accessed by the different services deployed within the same project. It also means that you could overwrite configs if you reuse the config names within a specific project.

Use configs

As with volumes, configs are mounted as files into a service's container's filesystem. The location of the mount point within the container defaults to /<config-name> inside the containers.

Getting a config into a container is a two-step process. First, define the config using the top-level configs element in your Compose file. Next, update your service definitions to reference the configs they require with the configs attribute. Levv grants access to configs on a per-service basis.

`configs` top-level element

The top-level configs declaration defines or references configuration data that is granted to services in your Compose application. The source of the config is either file, environment or external.

file: The config is created with the contents of the file at the specified path.
environment: The config content is created with the value of an environment variable.
content: The content is created with the inlined value.
external: If set to true, external specifies that this config has already been created. Levv does not attempt to create it, and if it does not exist, an error occurs.
name: The name of the config object in the container engine to look up. This field can be used to reference configs. The name is used as is and will be scoped with the project name.

`configs` attribute within the `services` top-level element

Configs allow services to adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the configs attribute. Two different syntax variants are supported.

Levv reports an error if config doesn't exist on the platform or isn't defined in the configs top-level element in the Compose file.

There are two syntaxes defined for configs. To remain compliant to this specification, an implementation must support both syntaxes. Implementations must allow use of both short and long syntaxes within the same document.

You can grant a service access to multiple configs, and you can mix long and short syntax.

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to /< config_name>.

The following example uses the short syntax to grant the redis service access to the my_config and my_other_config configs. The value of my_config is set to the contents of the file ./my_config.txt, and my_other_config is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true

Long syntax

The long syntax provides more granularity in how the config is created within the service's task containers.

source: The name of the config as it exists in the platform.
target: The path and name of the file to be mounted in the service's task containers. Defaults to /<source> if not specified.
mode: The permissions for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable (0444). Writable bit is ignored. The executable bit can be set.

The following example sets the name of my_config to redis_config within the container, and sets the mode to 0440 ( group-readable). The redis service does not have access to the my_other_config config.

services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true

Examples

Example 1

http_config is created when the application is deployed, by registering the content of the httpd.conf as the configuration data.

configs:
  http_config:
    file: ./httpd.conf

Alternatively, http_config can be declared as external. Levv looks up http_config to expose the configuration data to relevant services.

configs:
  http_config:
    external: true

Example 2

app_config is created when the application is deployed, by registering the inlined content as the configuration data. This comes with the benefits Levv will infer variables when creating the config, which allows to adjust content according to service configuration:

configs:
  app_config:
    content: |
      debug=${DEBUG}
      spring.application.admin.enabled=${DEBUG}
      spring.application.name=${COMPOSE_PROJECT_NAME}

Example 3

External configs lookup can also use a distinct key by specifying a name.

The following example modifies the previous one to look up a config using the parameter HTTP_CONFIG_KEY. The actual lookup key will is set at deployment time by the interpolation of variables, but exposed to containers as hard-coded ID http_config.

configs:
  http_config:
    external: true
    name: "${HTTP_CONFIG_KEY}"

If external is set to true, all other attributes apart from name are irrelevant. If Levv detects any other attribute, it rejects the Compose file as invalid.

Single-service config injection

In the following example, the frontend service is given access to the my_config config. In the container, /my_config is set to the contents of the file ./my_config.txt.

services:
  myapp:
    image: myapp:latest
    configs:
      - my_config
configs:
  my_config:
    file: ./my_config.txt