Package: konverter
Konverter - YAML templating for responsible usersKonverter is a YAML templating tool that uses Jinjaexpressionandtemplatesand supports inline-encrypted variables.Features:generic YAML templating (notspecific to e.g. Kubernetes)works on theYAML structure; text templating only available for valuessupport for simpleinline-encrypted variables... more to come (see "planned features")The project is still at anearly stage, so I'm happy about any contribution!MotivationI created this tool mainly to scratch my own itch. I needed a simple way to store encrypted values along my Kubernetes manifests, but found that e.g.Kustomizemakes thisextra hard.In that regard Konverter follows the Python philosophy: "We are allconsenting adults". So yes, you can do potentially dangerous things with it.Also, the way Kustomize works bypatching and transformingYAML, as well as the concept ofSecretandConfigMapgenerators, didn't feel natural to me.To each his own :)InstallationThe easiest way to install Konverter is viapipx:$pipxinstallkonverterOr just with plain pip:$pipinstallkonverterUsageKonverter is configured via a YAML file (of course). In this config file, you define your templates and the context (variables) used to render those templates. If you want to render your templates with a different context (e.g. templating Kubernetes manifests for staging, production, ...) you need a separate config file.Here's a simple example of a config file:templates:-manifest.yamlcontext:-vars/common.yaml-vars/prod.yamlThe templates are rendered using thekonvertercommand by passing it the config file:$konverterproduction.yaml
...The rendered templates will be written tostdoutas a multi-document YAML. This allows for easy composition with other tools likekubectl:$konverterproduction.yaml|kubectlapply-f-TemplatesUnder thetemplateskey, you can configure a list of files or directories. In the case of a directory, Konverter will recursively include all*.y[a]mlfiles.Konverter usesYAML tagsto declare expressions (!k/expr) and templates (!k/template):foo:!k/exprfoo.barFOO:!k/exprfoo.bar|uppernot_defined:!k/exprmissing_variable|default('default value')config:!k/template|-Hello {{ name }}{% for item in list_of_values %}Hello {{ item }}{% endfor %}ExpressionsExpressions are mainly useful for injecting data from the context and performing simple transformations:# Example contextvalue:from:context:barfooother:foobar# Use !k/expr to inject the values in a templatefoo:bar:!k/exprvalue.from.contextfoo:!k/exprvalue.from.other|upperWhen using the!k/exprtag, the value can be any validJinja2 expression. In addition to the standard Jinjafilters,testsandglobal functionsthe following filters are currently available:to_json: dump an object as aJSON stringb64encode: encode value using Base64Missing a filter? Let me know or feel free to contribute!TemplatesThe!k/templatetag supports the fullJinja2 template syntax(currently with some exceptions, like template inheritance), but the output will always be a string value. Inline templates are most useful for customizing config files.ContextThecontextkey in the config contains a list of files or directories that Konverter uses for loading variable definitions. Those variables serve as the context (hence the name) when rendering templates. In the case of multiple context files containing the same top-level key, the entry from the last listed file wins (in the future we might support merging those contexts).This is how a simple context file might look likedeployment:name:foobarserver_name:foobar.example.comannotations:version:1.0environment:productionEncrypted valuesIn addition there can be inline-encrypted values:credentials:user:rootpassword:!k/vaultgAAAAABeKd7EEt-jCYJSLS_ze6oO401yRDCthJFkuR4ptIFNnSElTccUnOVSQ1rSCDbIdljB59SRWjy2rDq7174stq3FFzyE_w==Konverter usesFernet symmetric encryptionwith secret keys. To use encrypted values we have to create key first:$konverter-vaultkeygenThis will create a key file.konverter-vaultin the current directory containing the key.Make sure to never commit this file to version control!By default, Konverter will look for the vault key in the same directory as the config file when rendering templates. See the section "advanced configuration" on how to use a different path.The following command will decrypt any encrypted values in the given file and launch your$EDITOR:$konverter-vaulteditvars/secret.yamlValues that should be encrypted are marked with the!k/encryptYAML tag:credentials:user:rootpassword:!k/encryptsecret-passwordAfter closing the editor Konverter will encrypt the values:credentials:user:rootpassword:!k/vaultgAAAAABeKd7EEt-jCYJSLS_ze6oO401yRDCthJFkuR4ptIFNnSElTccUnOVSQ1rSCDbIdljB59SRWjy2rDq7174stq3FFzyE_w==Instead of editing the file via thekonverter-vault editcommand you can also encrypt/decrypt the files separately:$konverter-vaultencryptvars/secret.yaml
...
$konverter-vaultdecryptvars/secret.yamlIn case the decrypted content should be passed to another tool that expects
YAML or JSON, thekonverter-vault showcommand can come in handy:$konverter-vaultshow--format=jsonvars/secret.yaml{"credentials":{"user":"root","password":"secret-password"}}It will decrypt the given file and remove all!k/(encrypt|vault)YAML tags.
Supported output formats areyaml(default),jsonorterraform.Theterraformoutput format is usefull for usingkonverter-vaultas anexternal data source in
Terraformdata"external""konverter"{program=["konverter-vault", "show", "--format=terraform", "vars/secrets.yaml"]}Unfortunately the "external program
protocol"
only allows string values (no lists or objects). Allfloat,intandboolvalues will be converted to strings. Other types will cause an error when
using this output format.Advanced configurationThe above config file could be rewritten in a more verbose format:templates:-manifest.yamlproviders:default:key_path:.konverter-vaultcontext:-provider:defaultpath:vars/common.yaml-provider:defaultpath:vars/prod.yamlIn case we want to change the location of the vault key, we can simply override the default provider:...providers:default:key_path:~/.my-vault-key...Planned featuresbetter error handlingimprove test coverageimporting templates from a filesupport for other context providersFeel free to create an issue or a pull-request if you are missing something!