Config Ninja 🥷

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

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

Features

• ✅ Integration with AWS AppConfig for managing server configuration files
• ✅ Extensible design supports backends for new providers and formats
• ✅ jinja2 templating for arbitrary configuration file formats
• ✅ Execute poethepoet tasks after updating files

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):

pipx install 'config-ninja[all]'

With uv

uv tool 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

Multiple instances of the service can also be installed to reference different settings files. For example, the following command will create the service named etc-config--ninja-alternate.service:

sudo config-ninja self install --config /etc/config-ninja/alternate.yaml

How It Works

To demonstrate how the mechanics work (using the local backend):

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.

Navigation

config_ninja.cli

Commands and CLI documentation.

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.contrib.secretsmanager

Integrate with the AWS SecretsManager service.

config_ninja.hooks

Execute poethepoet tasks as callback hooks for backend updates.

config_ninja.settings

For settings and configuration.

config_ninja.systemd

Integration with systemd.