Config Ninja 🥷

Similar to confd, manage your system configuration files by populating Jinja2 templates with data from a remote provider.

Installation

config-ninja is installed using the official installer or with pip / pipx. After installation, you can enable config-ninja as a systemd service.

Official Installer

The recommended way to install config-ninja is with the official installer:

curl -sSL https://config-ninja.github.io/config-ninja/install.py | python3 -

To view available installation options, run the installer with the --help flag:

curl -sSL https://config-ninja.github.io/config-ninja/install.py | python3 - --help

usage: install [-h] [--version VERSION] [--pre] [--uninstall] [--force] [--path PATH] [--backends BACKENDS]

Installs the latest (or given) version of config-ninja

options:
  -h, --help           show this help message and exit
  --version VERSION    install named version
  --pre                allow pre-release versions to be installed
  --uninstall          uninstall config-ninja
  --force              respond 'yes' to confirmation prompts; overwrite existing installations
  --path PATH          install config-ninja to this directory
  --backends BACKENDS  comma-separated list of package extras to install, or 'none' to install no backends

With pip / pipx

Alternatively, use pip / pipx to install [all available backends] (or choose a specific one):

pip install 'config-ninja[all]'

Enable the systemd Service

After installing config-ninja, enable it as a systemd service for the current user:

# omit '--user' to install the agent at the system level
config-ninja self install --user

How It Works

To demonstrate how the mechanics work locally:

1. create a settings file for config-ninja:

   cat <<EOF >config-ninja-settings.yaml
   CONFIG_NINJA_OBJECTS:
     example-0:
       dest:
         format: json
         path: ./.local/settings.json
       source:
         backend: local
         format: toml
         init:
           kwargs:
             path: ./.local/config.toml
   EOF
   

2. run config-ninja in monitor mode:

   config-ninja apply --poll
   

3. in a separate shell, create the config.toml:

   cat <<EOF >./.local/config.toml
   [example-0]
   a = "first value"
   b = "second value
   EOF
   

4. Inspect the settings.json file created by config-ninja:

   cat ./.local/settings.json
   

   {
     "example-0": {
       "a": "first value",
       "b": "second value"
     }
   }
   

5. Make changes to the data in config.toml, and config-ninja will update settings.json accordingly:

   cat <<EOF >>./.local/config.toml
   [example-1]
   c = "third value"
   d = "fourth value
   EOF
   cat ./.local/settings.json
   

   {
     "example-0": {
       "a": "first value",
       "b": "second value"
     },
     "example-1": {
       "c": "third value",
       "d": "fourth value"
     }
   }
   

   Chances are, you'll want to update the config-ninja-settings.yaml file to use a remote backend (instead of local). See config_ninja.contrib for a list of supported config providers.

Configuration Architecture

The config-ninja agent monitors the backend source for changes. When the source data is changed, the agent updates the local configuration file with the new data:

sequenceDiagram
    loop polling
       config-ninja->>backend: query for changes
    end

    backend->>+config-ninja: [backend changed] fetch config
    config-ninja->>-filesystem: write updated configuration file

Navigation

config_ninja.contrib

For supported backends.

config_ninja.contrib.appconfig

Integrate with the AWS AppConfig service.

config_ninja.contrib.local

Use a local file as the backend.

config_ninja.cli

Commands and CLI documentation.

config_ninja.settings

For settings and configuration.

config_ninja.systemd

Integration with systemd.