markusfalk/cd-config-server repository overview

⁠Continuous Delivery Configuration Server

This server provides a configuration API to be used within Continuous Delivery environments.

⁠Concept

The idea behind this software is to provide a global and public service for your apps to receive configuration values from. Configuration can be stored in a git repository that is seperated from the repositories in which your apps reside or synced to your file system. This makes it possible for apps and configurations to have independent lifecyles and both be treated like code.

This service allows for apps to be build once and then put through your continuous delivery pipeline without the need to rebuild them. They can load their configuration at runtime by telling the service what they need.

⁠How it works

⁠Application Configuration

A continuous delivery pipeline usually has mutlipe environments in which the app is tested or reviewed. The configuration repository contains one file per stage/environment of your pipeline.

These configuration files (*.json) contain all the values your app needs. If a pipeline has the four stages: development (local), test, staging, production, then you would create the following four files:

development.json
test.json
staging.json
production.json

It currently supports Github, Gitlab or the local file system as a source of your configuration files.

⁠Independent Lifecyles and Deployments

Here is where the magic happens and where this configuration server is different from others.

To make applications and configurations truly independent and to avoid lock-step releases with your configuration, we need to somehow tell the service which configuration release is compatible with what version of our applications.

For that reason each configuration file contains this one additional and obligatory entry:

{
  "compatibleWithAppVersion": "^2.0.0"
}

Here you can define a semantic version range that tells the configuration server if this tag/release of your configuration is comapitble with the application version that is requesting configuration.

Note however, that in case of a breaking change in your app relating to a new configuration entry this will again become a required release with your application. You can release your configuration first by specifing a breaking change. Older apps will not consume the new configuration and as soon as your new app is deployed, the configuration is already there.

⁠Naming Convention

⁠Configuration Repository Name

The application id will be used to find the configuration repository by appending -config.

Examples

⁠Matching Configuration Key

To match application version and configuration you must provide the compatibleWithAppVersion key in all of your configuration files.

{
  "compatibleWithAppVersion": "^1.0.0"
}

⚠️ Be aware that this is the version of the application that this specific configuration is compatible with not the version of the configuration itself. They vary because they now have different lifecycles.

⚠️ If the configuration has a breaking change, make sure to deploy the config first to avoid apps in production without propper configuration and be aware of the caching that is configured for configuration output.

In case of a none-breaking change in the configuration file, you would release a new version of the configuration that is still compatible with already deployed app causing for the config to have a new release but with no need to release a new app.

⁠Setup

⁠Prerequisits

• Configuration files hosted on filesystem, github or gitlab (including self hosted)
• This server is provided as a docker image
• Your applications need be versioned using semantic versioning

⁠Options

The server is provided as a docker image and can be started with the following options:

⁠Common

⁠When using Github

⁠When using Gitlab

⁠When using the file system

There is no additional configuration needed beyond the SOURCE but there needs to be a volume mounted to /app/dist/configfiles.

When this is done you can move your configuration files into that volume with the following structure:

- <appid> // identifies the app that is asking for configuration
  |- <configuration release version> // do not confuse with app version. This is the releases of your configuration
    |- <stage>.json // identifies the stage your app wants configuration for

Example:

- my-app
  |- 1.0.0
    |- development.json
    |- test.json
    |- production.json
- another-app
  |- 1.0.0
    |- development.json
    |- test.json
    |- production.json
  |- 1.1.0
    |- development.json
    |- test.json
    |- production.json
  |- 2.0.0
    |- development.json
    |- test.json
    |- production.json

⁠Caveats

If you are using this configuration server publicly you need to make sure that your configurations files do not contain any secrets.

⁠Migration Guide

• https://github.com/markusfalk/cd-config-server/blob/main/MIGRATIONS.md⁠

⁠Issues

• https://github.com/markusfalk/cd-config-server/issues⁠

⁠Changelog

• https://github.com/markusfalk/cd-config-server/blob/main/CHANGELOG.md⁠

⁠Questions?

If you have any questions reach out to me on twitter: https://twitter.com/markus_falk⁠