Skip to main content

Use special ninja powers to manage system configurations 🥷

Project description

Config Ninja 🥷

Ruff 🎨 poe (push) pylint codecov pre-commit.ci status Checked with mypy docs: pdoc readthedocs PyPI version Downloads

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

config_ninja-1.5.1.tar.gz (36.4 kB view details)

Uploaded Source

Built Distribution

config_ninja-1.5.1-py3-none-any.whl (31.5 kB view details)

Uploaded Python 3

File details

Details for the file config_ninja-1.5.1.tar.gz.

File metadata

  • Download URL: config_ninja-1.5.1.tar.gz
  • Upload date:
  • Size: 36.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for config_ninja-1.5.1.tar.gz
Algorithm Hash digest
SHA256 2fd186e028f384275f418667c4f0f8e0c3f5e52d801dfc768ad1633afc876110
MD5 c0910e99447201d4d3bf827d9b267dc9
BLAKE2b-256 bfc895d76d33e9c58b83d7e5880efb2a3e551d99bfefb4a0015aab8778464820

See more details on using hashes here.

File details

Details for the file config_ninja-1.5.1-py3-none-any.whl.

File metadata

  • Download URL: config_ninja-1.5.1-py3-none-any.whl
  • Upload date:
  • Size: 31.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for config_ninja-1.5.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e3cbda7311e422d9cbbfaf26735e5c33ef92aeb4f65005236bbdb149e83c2e67
MD5 baa7d6aea97fb0bf85abb989cc6ed41d
BLAKE2b-256 50038923e53d9369bc5d1b220e7107f17446f13432f3083fdf99349a774a29ba

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page