163 lines
5.2 KiB
Markdown
163 lines
5.2 KiB
Markdown
# JinjaTurtle
|
|
|
|
<div align="center">
|
|
<img src="https://git.mig5.net/mig5/jinjaturtle/raw/branch/main/jinjaturtle.svg" alt="JinjaTurtle logo" width="240" />
|
|
</div>
|
|
|
|
JinjaTurtle is a command-line tool to help you generate Jinja2 templates and
|
|
Ansible inventory from a native configuration file (or files) of a piece of
|
|
software.
|
|
|
|
## How it works
|
|
|
|
* The config file(s) is/are examined
|
|
* Parameter key names are generated based on the parameter names in the
|
|
config file. In keeping with Ansible best practices, you pass a prefix
|
|
for the key names, which should typically match the name of your Ansible
|
|
role.
|
|
* A Jinja2 file is generated from the file with those parameter key names
|
|
injected as the `{{ variable }}` names.
|
|
* An Ansible inventory YAML file is generated with those key names and the
|
|
*values* taken from the original config file as the default vars.
|
|
|
|
By default, the Jinja2 template and the Ansible inventory are printed to
|
|
stdout. However, it is possible to output the results to new files.
|
|
|
|
## What sort of config files can it handle?
|
|
|
|
TOML, YAML, INI, JSON and XML-style config files should be okay. There are always
|
|
going to be some edge cases in very complex files that are difficult to work
|
|
with, though, so you may still find that you need to tweak the results.
|
|
|
|
For XML and YAML files, JinjaTurtle will attempt to generate 'for' loops
|
|
and lists in the Ansible yaml if the config file looks homogenous enough to
|
|
support it. However, if it lacks the confidence in this, it will fall back to
|
|
using scalar-style flattened attributes.
|
|
|
|
You may need or wish to tidy up the config to suit your needs.
|
|
|
|
The goal here is really to *speed up* converting files into Ansible/Jinja2,
|
|
but not necessarily to make it perfect.
|
|
|
|
## Can I convert multiple files at once?
|
|
|
|
Certainly! Pass the folder name instead of a specific file name, and JinjaTurtle
|
|
will convert any files it understands in that folder, storing all the various
|
|
vars in the destination defaults yaml file, and converting each file into a
|
|
Jinja2 template per file type.
|
|
|
|
If all the files had the same 'type', there'll be one Jinja2 template.
|
|
|
|
You can also pass `--recursive` to recurse into subfolders.
|
|
|
|
Note: when using 'folder' mode and multiple files of the same type, their vars
|
|
will be listed under an 'items' parent key in the yaml, each with an `id` key.
|
|
You'll then want to use a `loop` in Ansible later, e.g:
|
|
|
|
```yaml
|
|
- name: Render configs
|
|
template:
|
|
src: config.j2
|
|
dest: "/somewhere/{{ item.id }}"
|
|
loop: "{{ myrole_items }}"
|
|
```
|
|
|
|
## How to install it
|
|
|
|
### Ubuntu/Debian apt repository
|
|
|
|
```bash
|
|
sudo mkdir -p /usr/share/keyrings
|
|
curl -fsSL https://mig5.net/static/mig5.asc | sudo gpg --dearmor -o /usr/share/keyrings/mig5.gpg
|
|
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/mig5.gpg] https://apt.mig5.net $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/mig5.list
|
|
sudo apt update
|
|
sudo apt install jinjaturtle
|
|
```
|
|
|
|
### Fedora
|
|
|
|
```bash
|
|
sudo rpm --import https://mig5.net/static/mig5.asc
|
|
|
|
sudo tee /etc/yum.repos.d/mig5.repo > /dev/null << 'EOF'
|
|
[mig5]
|
|
name=mig5 Repository
|
|
baseurl=https://rpm.mig5.net/$releasever/rpm/$basearch
|
|
enabled=1
|
|
gpgcheck=1
|
|
repo_gpgcheck=1
|
|
gpgkey=https://mig5.net/static/mig5.asc
|
|
EOF
|
|
|
|
sudo dnf upgrade --refresh
|
|
sudo dnf install jinjaturtle
|
|
```
|
|
|
|
### From PyPi
|
|
|
|
```
|
|
pip install jinjaturtle
|
|
```
|
|
|
|
### From this git repository
|
|
|
|
Clone the repo and then run inside the clone:
|
|
|
|
```
|
|
poetry install
|
|
```
|
|
|
|
### AppImage
|
|
|
|
Download the AppImage from the Releases and make it executable, and put it
|
|
on your `$PATH`.
|
|
|
|
## How to run it
|
|
|
|
Say you have a `php.ini` file and you are in a directory structure like an
|
|
Ansible role (with subfolders `defaults` and `templates`):
|
|
|
|
```shell
|
|
jinjaturtle php.ini \
|
|
--role-name php \
|
|
--defaults-output defaults/main.yml \
|
|
--template-output templates/php.ini.j2
|
|
```
|
|
|
|
## Full usage info
|
|
|
|
```
|
|
usage: jinjaturtle [-h] -r ROLE_NAME [-f {json,ini,toml,yaml,xml,postfix,systemd}] [-d DEFAULTS_OUTPUT] [-t TEMPLATE_OUTPUT] config
|
|
|
|
Convert a config file into Ansible inventory and a Jinja2 template.
|
|
|
|
positional arguments:
|
|
config Path to the source configuration file.
|
|
|
|
options:
|
|
-h, --help show this help message and exit
|
|
-r, --role-name ROLE_NAME
|
|
Ansible role name, used as variable prefix (e.g. cometbft).
|
|
-f, --format {ini,json,toml,xml}
|
|
Force config format instead of auto-detecting from filename.
|
|
-d, --defaults-output DEFAULTS_OUTPUT
|
|
Path to write defaults/main.yml. If omitted, default vars are printed to stdout.
|
|
-t, --template-output TEMPLATE_OUTPUT
|
|
Path to write the Jinja2 config template. If omitted, template is printed to stdout.
|
|
```
|
|
|
|
## Additional supported formats
|
|
|
|
JinjaTurtle can also template some common "bespoke" config formats:
|
|
|
|
- **Postfix main.cf** (`main.cf`) → `--format postfix`
|
|
- **systemd unit files** (`*.service`, `*.socket`, etc.) → `--format systemd`
|
|
|
|
For ambiguous extensions like `*.conf`, JinjaTurtle uses lightweight content sniffing; you can always force a specific handler via `--format`.
|
|
|
|
|
|
## Found a bug, have a suggestion?
|
|
|
|
You can e-mail me (see the pyproject.toml for details) or contact me on the Fediverse:
|
|
|
|
https://goto.mig5.net/@mig5
|