No, I expect the system administrator to refer to a readme, user guide or API doc that explains how to inject custom options at the command line or through a web API, etc., and absolutely never by mutating a config file outside of version control with code review from the team that maintains that specific type of config.
Take Apache or Postfix, for example, which are configured via possibly complex configuration files and not a “web API”. It is definely useful to have comments explaining configurations. For example, “here we deviated from the default for such and such reasons”. That’s true whether the file isn’t maintained manually or via some Puppet or Chef template or something else.
But if the config file has a comment like “here we deviated from the default...” it suffers the sane risk of being out if sync as the documentation would suffer anywhere.
So then, instead of forcing someone else to dig around a file like that, why would you put the docs about your modified config file somewhere else, and in a format that’s much easier to read?
For example you could make a whole git repository solely to hold a certain config file, allowing it to be versioned and even including an “install” script so that some other tool like docker could be used to faithfully reproduce a config setup.
Basically the only examples I have seen anywhere in this thread where people think in-line config comments matter are large desktop applications like Transmission or Postgres which have the unfortunately bad practice of letting users modify complex config files (instead of forcing all overrides of defaults to be ENV variable based).
And even in these cases, it seems more like lazy people who just personally prefer to sling a config file around rather than doing some minimal best practice like putting it in a repo to wrap it up like a mini-package and give much better documentation to someone who might “install” that config than what crappy in-line comments can give, and to enforce code review even for your own local config changes.
If you think there’s a risk of comments becoming outdated in a config file, then the risk of it becoming outdated in a separate place seems even higher.
Configuration via environment variables is as far from best practice as I can imagine. It prevents proper validation of settings (e.g. a typo can’t be detected because you don’t know which environment variables are used by other programs), not to mention the possible security implications. Besides, these environment variables would have to be set somewhere, like a startup shell script, which I bet would end up with explanatory comments anyway.
This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.
> “then the risk of it becoming outdated in a separate place seems even higher.”
I’d say they are almost identical risks, and for all practical purposes there is no difference. Putting comments inside the config file only makes discovery much harder than putting it in a user guide, man page, etc. with no offsetting benefit of consistency.
> “Configuration via environment variables is as far from best practice as I can imagine”
You are arguing against perhaps the most dominant notion of config best practices in the modern era when you say that [0]. Quoting from the 12 Factor App best practices on config:
> “Another approach to config is the use of config files which are not checked into revision control, such as config/database.yml in Rails. This is a huge improvement over using constants which are checked into the code repo, but still has weaknesses: it’s easy to mistakenly check in a config file to the repo; there is a tendency for config files to be scattered about in different places and different formats, making it hard to see and manage all the config in one place. Further, these formats tend to be language- or framework-specific.
The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.”
You say,
> “This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.”
I don’t think those are the reasons for putting config into the environment at all. I think a main reason is specifically so that end users modify config with ENV vars that disallow scattered and non-reproducible collections of config (e.g. if you share the command or script that defined the environment, the settings are enforced; if you share something that relied on a local config file you had modified but no one else knows about, they can’t get your settings).
> You are arguing against perhaps the most dominant notion of config best practices in the modern era
I don’t know that it’s “dominant”, nor that it’s good merely because it’s “from the modern era”. But even if all that is true, 12 factor apps constitute a small subset of configurable software that is deployed worldwide, and hardly a silver bullet for all kinds of software (it even defines itself as a methodology specific to SaaS applications).
