Wandering Thoughts archives

YAML in practice can be looser than I expected

Both the Prometheus and the Grafana Loki ecosystems are mostly configured with a large amount of YAML. Since we use both, this has resulted in me writing a fair amount of YAML. I've never tried to systematically learn YAML; like a lot of other things to do with configuration files, it's something that I tended to pick up as I needed to know specific things. I sort of learned general ideas, copied examples, diagnosed and fixed complaints, and so on.

A while back I decided to install yamllint (well, the Ubuntu version of it) and use it on our YAML files. I expected to find some minor things and small surprises. Instead, I received a litany of warnings, primarily about having too much indentation. This was especially surprising to me because I'd absorbed the story that YAML was extremely picky about whitespace; you had to use two spaces, no more and no less, and carefully line everything up where it was required. Except, apparently, not always, at least as Prometheus and other Go programs accepted YAML.

(Now that I read various things on the Internet, I've found out that YAML doesn't require two spaces, it just requires a consistent number of spaces (with no tabs). Two spaces is apparently the common default and so generally what you find in documentation, starting sample configuration files, and so on.)

Where this came up was in this syntax, which I had written variants of over and over again:

groups:
- name: temperatures
  rules:
    - alert: TempCore
      [...]

According to yamllint, the '- alert: ...' should have been indented to the level of 'rules:', not one more level. Actually reproducing this in a synthetic example turned out to be sufficiently hard to do and understand that this is actually the start of one of our Prometheus alert rule files, rather than a more abstracted example, because my abstracted examples kept failing.

In some experimentation it may be that yamllint is really objecting to the inconsistency between the two indentation approaches for '- ...' stanzas here, where the 'groups' one isn't indented relative to the label but the 'rules' one is. But this again illustrates that YAML's rules are looser than I expected, if things can be written either way (and even in a mixed way) and still be legal. As best as I can tell from trying to read YAML syntax documentation, it's (probably) valid to write YAML both ways.

(Until I looked closely at the YAML I'd written just now I didn't even notice this inconsistency. I'm not sure when it came from, but I clearly did it a lot. Also, apparently some part of me feels that things should be indented.)

On the one hand, this shows that I don't understand YAML as much as I thought I did. On the other hand, I'm not sure that I want to understand YAML more than I do, because I often find it annoying (partly for reasons that aren't the fault of YAML per se but of how people use it). On the third hand, YAML is pretty much what I'm stuck with these days, so maybe I should know more about it. The ecosystems using YAML aren't about to change their spots at this point (and they shouldn't, it would be very disruptive to change their configuration syntax at this point).