Configuration layers

A deplo.io application can be customized by multiple options. These options can be given at various configuration layers. All of the set configurations are merged in a specific order to create the final configuration for your application. The following sections will give an overview about the configuration system.

Available configuration layers

The following sources of configuration are available (ordered by precedence):

• application configuration
• git configuration via YAML file
• project configuration
• organization configuration
• global default configuration

The final configuration will be created by merging the configuration layers from top to bottom. Options set at a higher configuration layer overwrite those defined on a lower one. The final configuration will be attached to the latest release of the deplo.io application.

Application configuration

The configuration which is set on the deplo.io application itself is called "application configuration". It has the highest precedence, which means that all options are overwriting the corresponding options set on a lower configuration layer. You can view the configuration by using nctl:

$> nctl get app go -o yaml
kind: Application
apiVersion: apps.nine.ch/v1alpha1
metadata:
  name: go
spec:
  forProvider:
    ...
    config:
      size: mini
      env:
      - name: MYDATABASE
        value: test
      port: null
      replicas: null
    ...

The application configuration can be seen at the yaml key spec.forProvider.config. In the aboves example an application size of "mini" is set. Additionally an environment variable was defined. As the "port" option is set to null it can still be defined on lower configuration levels. Same goes for the "replicas" value.

You can do changes to the application configuration by using our CLI application nctl (nctl update app) or use the web UI available at https://cockpit.nine.ch.

Git configuration via yaml file

The configuration can also be defined in a file named .deploio.yaml which you can store along with the application code in git. Our build system will check for the existence of such a file and read the contents of it.

size: micro
port: 5678
replicas: 1
env:
  - name: RESPONSE_TEXT
    value: "Hello from a Go deplo.io app!"

As already pointed out before, the settings specified directly in the application configuration take precedence over this file.

An always up-to-date list of fields that can be used in the .deploio.yaml file is available in our API docs.

Project configuration

Projects are a way to logically separate resources into different units. Besides resources like on-demand databases or Kubernetes clusters, projects can also contain deplo.io applications. Additonally every project can have exactly one deplo.io configuration which will apply to every application created in that project. This is called the "project configuration". You can create it by using nctl create config.

$ nctl create config --env=RAILS_ENV=dev -p acme-dev

This creates a configuration in the project acme-dev which defines an environment variable RAILS_ENV with the value "dev". All created applications in the project acme-dev will now have an environment variable RAILS_ENV being set. The value of it can still be overwritten at higher configuration source layers.

Organization configuration

Every organization has a default project which has the same name as the organization itself. This project can not be removed. A deplo.io configuration created in the default project is called "organization configuration" as it will be used by all deplo.io applications, no matter in which project they are created. Creating a configuration at the organization level is very similar to creating one for a project. Just set the project name to the name of your organization.

$ nctl create config --size=mini -p acme

The above example defines a deplo.io configuration for the organization acme which defines an application size of "mini". This setting will be used by all deplo.io applications (no matter in which project they are defined), except the size got overwritten at higher configuration layers.

Global default configuration

For every configuration field there is a global default value which will be used if no other configuration layer defined a value for it. You can see those global default values in our API definitions. They are stored in the variable DefaultConfig.

How merging works

Single value options like "size" or "port" will be directly overwritten by higher configuration source layers. So a project configuration which specifies a size of "mini" for all applications in that project can directly be overwritten by specifying a size of "micro" in the application configuration (or via the yaml config file).

Environment variables are merged in a different way. Variables defined in higher configuration source layers will be added to the ones defined in lower configuration source layers. If the same environment variable is defined on multiple layers, the definition of the higher layer will overwrite the one from the lower layer. It is currently not possible to remove environment variables defined at a lower configuration layer.

Viewing the merged configuration

If you want to see the final merged configuration, you can do so by getting the latest release for your deplo.io application.

$ nctl get app go -o yaml

kind: Application
apiVersion: apps.nine.ch/v1alpha1
metadata:
  name: go
  ...
status:
  atProvider:
    latestRelease: finer-penance-sd78n
    ...

You can see the latest release at the yaml key status.atProvider.latestRelease.

Now we can get the configuration for that release by using nctl again.

$ nctl get release finer-penance-sd78n -o yaml

kind: Release
apiVersion: apps.nine.ch/v1alpha1
metadata:
  name: finer-penance-sd78n
  ...
spec:
  forProvider:
    configuration:
      size:
        size: mini
        origin: application
      env:
      - value:
          name: RESPONSE_TEXT
          value: Hello from a Go deplo.io app!
        origin: git
      - value:
          name: MYDATABASE
          value: test
        origin: application
      port:
        value: 5678
        origin: git
      replicas:
        value: 1
        origin: git
      enableBasicAuth:
        value: false
        origin: default
      ...

You can see the final merged configuration at the yaml key spec.forProvider.configuration. For every field in the configuration you can see the originating configuration layer of it (field origin). In the above example the environment variable RESPONSE_TEXT was defined in the .deploio.yaml file colocated to the application source code, while the environment variable MYDATABASE was directly defined in the application configuration. Basic authentication was not configured specifically, so the global default value of false was used.