Configuration management is not documentation, at least not of intentions

March 14, 2012

In this Sysadvent paen to configuration management I read the following little bit:

[...] In using a config management system, you are implicitly documenting the system's "desired state" - Why is the system configured this way? [...]

No you aren't. If you use very well named configuration management classes and variables and so on, you may have at best started to document the why of your configuration. Otherwise, configuration management documents the how of your configuration but it can only lightly touch on the much bigger picture of why.

(Here I want to distinguish between a CM configuration itself and any comments that you add to the CM configuration. Using a CM system doesn't require writing comments, and writing documentation on the why's of a configuration doesn't require putting that documentation into a CM configuration file as comments.)

Documentation on why needs to cover two aspects of the system, neither of which CM captures. The first aspect is why the system exists at all; what is the high level picture of why the system and the services running on it do and how they interrelate to other machines and services. Your CM system can tell you that this system runs Apache, but there's nothing in the CM configuration itself that will necessarily tell you why. The second aspect is why this system is set up the way it is, things like why you chose a particular daemon and why its configuration is the way it is. There may be vitally important information buried in these decisions, for example the painfully acquired knowledge that on machines with X memory you cannot set Apache parameter Y larger than value Z, but a CM configuration is again silent on all of that.

(And there is also things like why you didn't use some attractive setting.)

There is also a meta-issue, which is that a CM configuration is usually an incomplete specification of the real system. Using a CM system is all about telling it what you do to a target system, ie more or less what you change on it. If you don't need to change something, if the system comes set up for it correctly from the start, it's quite likely that this knowledge will not be in your CM configuration. This is great for compact CM setups, except that once again it means that your CM configuration is missing important information about the system.

(You can use a CM system to redundantly specify everything about a system's configuration, carefully telling it to do things like enable all of the Apache modules that you need even though they're all already enabled in the default install. But I really suspect that most people writing CM configurations are not that bloody-minded and determined; instead they specify the changes and additions that they needed to make to the base system to get things working.)

Written on 14 March 2012.
« Why it matters whether your software works when virtualized
The right way to do wikitext transitions »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed Mar 14 00:06:16 2012
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.