documentation

Till recently our documentation had a mix of visual styles for diagrams - mixing icons from Cisco, AWS etc - I recently wanted to document the supported network topologies and realised I need a more unified visual style for the documentation.

For some time now I am using diagrams.net to generate diagrams for blog posts and such, this tool is ok for diagrams but what really sets it apart for me is that even when exporting a PNG file it can embed the diagram vector source in the resulting PNG image.

This means any image on the website can simply be loaded and edited as a vector in the diagram editor, this is huge for ease of maintenance of the website, docs etc.

After some googling I found the Affinity symbol set - a public domain icon set in SVG format. Using these I came up with set of on-brand colored icons for our various components you can see below.

See the full post for links to assets and libraries for diagrams.net.

Choria configuration, despite efforts with Puppet module and so, is still very challenging. Just knowing what settings are available has been a problem.

We tried to hide much of the complexity behind Puppet models but for people who don’t conform to the norm it’s been a challenge.

I eventually want to move to a new configuration format - perhaps HCL? - but this is a massive undertaking both for me and users. For now we’ve made some effort to give insights to all the known configuration settings on the CLI and in our documentation.

First we’ll publish a generated configuration reference in CONFIGURATION.md - for now it’s in the Git repository we’ll move it to the doc site eventually.

As of the upcoming version of Choria Server you’ll be able to query the CLI for any setting using regular expressions. The list will show descriptions, data types, validation rules, default values, deprecation hints and URLs to additional information.

And get a list:

$ choria tool config puppet -l
plugin.choria.puppetca_host
plugin.choria.puppetca_port
plugin.choria.puppetdb_host
plugin.choria.puppetdb_port
plugin.choria.puppetserver_host
plugin.choria.puppetserver_port

These references are extracted from the Go code - something that I never imagine is possible - read on for details on how that is done.