Your configs suck? Try a real programming language. [see within blog graph]

In this section, I'm mostly referring to JSON/YAML/TOML/ini files, which are the most common config formats I encounter.

I'll refer to such configs as plain configs. Not sure if there is a better name for it, please let me know!

An incomplete list of my frustrations:

• JSON doesn't have comments, by design 🤯

• bits of configs can't be reused

  For example, while YAML, in theory, supports reusing/including bits of the config (they call it anchors), some software like Github Actions doesn't support it

  Usually, you just don't have any means of reusing parts of your config and have to copy-paste.

  • .gitconfig uses a custom syntax for merging the configs

• can't contain any logic

  This is considered as a positive by many, but I would argue that when you can't define temporary variables, helper functions, substitute strings or concatenate lists, it's a bit fucked up.

  The workarounds (if present) are usually pretty horrible and impose cognitive overhead. Programming language constructs are reinvented from scratch:

  • variables and string interpolation
    • Ansible uses Jinja templates (!) for variable manipulations.

    • Github Actions use a custom syntax for that

      In addition, they've got their own set of functions to manipulate the variables. Have fun learning a new language you never wanted to!

  • scoping

    I.e. there are several custom scopes for env directive in Github Actions.

  • control flow
    • for loop: build matrices and 'excludes' always give me a headache
    • if statement: e.g. when in CircleCI

  "This is not structured data. This is programming masquerading as configuration."

• can't be validated

  You can validate the config syntax itself (i.e. check JSON for correctness), but if you want more sophisticated semantic checks, you need to spend extra effort.

  This is kind of a consequence of not having logic in the config files. Typically you'll have to write a supplementary program to check your configs and remember to call it before passing to a program.

  Very few programs bother with that. Usually, your program crashes because of something that would be trivial to catch with any simple type system.

• YAML simply stands out with its implicit conversions and portability issues (e.g. "The NOrway Problem")

  There are enough rants about it, so I'll just leave a link to a good one: "YAML: probably not so great after all".

Summary: we spend time learning useless syntax and reinventing programming constructs, instead of productive work.

So what happens when people encounter these problems? Often they end up using a 'real' (i.e. general purpose, Turing complete) programming language anyway:

• you write a program to filter out custom comment syntax
• you write a program to merge configs or use a templating engine

• you write a program that 'evaluates' the config

  Often, you end up reimplementing an interpreter for a simple functional language in the process.

• you write a program to validate the config

  For the most part, it's boilerplate for type checking. You're not only working on a solved problem but in addition, end up with mediocre error messages as a result.

All this stuff is unpleasant and distracts you from your main objective.

Perhaps you can see where I'm coming with this.

The idea is to write your config in your target programming language. I'll have Python in mind here, but the same idea can be applied to any dynamic enough language (e.g. Javascript/Ruby).

Then, you simply import/evaluate your config file and voila – you're done. That's it.

• Toy example:

  config.py

  from typing import NamedTuple
  
  class Person(NamedTuple):
      name: str
      age: int
  
  PEOPLE = [
      Person('Ann'  , 22),
      Person('Roger', 15),
      Person('Judy' , 49),
  ]
  

  Using the config:

  from pathlib import Path
  
  config = {}
  exec(Path('config.py').read_text(), config)
  people = config['PEOPLE']
  
  print(people)
  

  [Person(name='Ann', age=22), Person(name='Roger', age=15), Person(name='Judy', age=49)]
  

I find it pretty neat. Let's see how it helps us with the problems I described:

• comments: duh

• includes: trivial, use imports

  You can even import the very package you're configuring. So you can define a DSL for configuration, which will be imported and used in the config file.

• logic

  You have your language's syntax and libraries available to use. For example, something like pathlib alone can save you massive amounts of config duplication.

  Of course, one could go crazy and make it incomprehensible. But personally I'd rather accept potential for abusing the power of the language rather than being restricted.

• validation

  You can keep validation logic right in the config, so it would be checked at the time of loading. Mature static analysis tools (i.e. JS flow/eslint/pylint/mypy) can be used to aid you.

Some ways I've found to minimize the frustration while using plain configs:

• write as little in config files as possible

  This typically applies to CI pipeline configs (i.e. Gitlab/Circle/Github Actions) or Dockerfiles.

  Often such configs are bloated with shell commands, which makes it impossible to run locally without copying line by line. And yeah, there are ways to debug, but they have a pretty slow feedback loop.

  • use tools that are better suited to set up local virtual environments, like tox-dev/tox

  • prefer helper shell scripts and call them from your pipeline

    It is a bit frustrating since it introduces indirection and scatters code around. But, as an upside, you can lint (e.g. shellcheck) your pipeline scripts, and make it easier to run locally.

    Sometimes you can get away if your pipeline is short, so use your own judgment.

  Let the CI only handle setting up a VM/container for you, caching the dependencies, and publishing artifacts.

• generate the config instead of writing manually

  The downside is that the generated config may diverge if edited manually.

  You can add the warning comment that the config is autogenerated with the link to the generator, and make the config file read-only to discourage manual editing.

  In addition, if you're running CI, you can make the consistency check a part of the pipeline itself.

• (commandline) flags are great for configuration

  Overall, I agree, but there are still cases when using flags isn't feasible.

  It's also prone to leaking secrets (keys/tokens/passwords) – both in your shell history and via ps.

• Xmonad: config is the executable

  Interesting approach, but not always feasible, e.g. you might not have the compiler installed.

• Mage: a tool for writing makefiles in Go
• Dhall wiki: Programmable configuration files
• Why are we templating YAML? (HN)

Updates from the comments (thanks everyone!):

• The evolution of an extension language: a history of Lua: apparently Lua has started as a config language

• Cue: A language for defining, generating, and validating data

  I've really struggled to find a code example on the website, so here you go.

• The configuration complexity clock: a case for hard-coding

A followup question, which I don't have an answer for: why is it that way? I'm sure Ansible/CircleCI or Github Actions are developed by talented engineers who have considered pros and cons of using YAML. Do the pros really outweigh the cons?

Open to all feedback, and feel free to share your config pain and how are you solving it!

Updates:

• [2020-04-11] Added P.S. section

Thanks everyone for the discussions and comments!

There were some polar opinions involved, so I'd like to clarify the most common objections here:

• "Programs as a config are a security nightmare"

  I admit that I have a programmer's mindset (as opposed to sysadmin's), and very likely underestimate the security risks.

  But again, I agree that executable configs are not always a good idea. You can still have the best of both worlds by providing a DSL for generating a plain config and consuming the plain config.

• "If your config is a program, it might end up arbitrarily complex and incomprehensible"

  Sure, but again, it largely depends on the discipline. You can also make a plain config incomprehensible and hard to modify.

  The best compromise here is probably configuration languages like Dhall.

• "What happens in 20 years, when there is no <insert programming language> around"

  That's a good point, but languages don't disappear in an eye blink. There will be plenty of time to adapt. In addition, if your software and config are written in the same language, the software will need to be rewritten anyway, which is a bigger problem.

  Also even plain config formats come and go. 20 years ago XML was common for configuration; how many times you've seen it lately? Does your programming language even include XML parser in the standard library?

• "If your config is so complex you need a DSL, your design has gone wrong and your software sucks"

  Frankly, I've found many of such comments as very opinionated and not constructive, but I'll try to respond.

  Software comes in very different shapes and while having the simplest configuration possible is desirable (ideally, none!), sometimes it would change the very nature of the thing you're trying to develop. Sure, you can stop calling it 'software' and start calling a 'library' at this point, but I don't feel it changes the point of the discussion.

  Perhaps, my constructive takeaways from this argument would be:

  • think how flexible your configuration might have to be, and whether you need to give up on plain configs early

    A good example of this would be some mail filtering systems, that started simple and ended as Turing complete.

  • in the rapid development phase, resort to having a flexible config

    When/if your software matures, think about supporting plain configs or/and using a special configuration language.