config-ninja

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

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.