Looking for best-practices in documentation of configurable containersdocumentation container practice

General
1

Hi,

I’m looking for some best-practices in documentation of configurable containers.

What is clear: https://12factor.net/config tells us to use ENV for configurations

So, now there are different types and cases to deal with:

  • using docker logs to tell the user what he is doing wrong
    1. just shut down if configuration is missing, yell a fatal log
      • fail fast, fail on first missing
      • first evaluate all and give a summary of all missing configs
    2. just tell a warn/info log about optional but not explicit set ENVs
  • give a kickstart, like first approach, but:
    1. the image has predefined ENVs
    2. empty values has to be handled in application as “not set” and perhaps might be bothering if there are different interpretations for “blank” but not “unset”
    • This will be indeed quirky … even you don’t have any “documentation” of the available ENVs
  • use some LABELs for documentation purposed, like 
    LABEL doc.ENV.FIRST_OPTION=“Integer” \
    
doc.ENV.FIRST_OPTION.required=“true” \
    
doc.ENV.FIRST_OPTION.desc="…" \
    
doc.ENV.FIRST_OPTION.range=“0-10” \
    
doc.ENV.FIRST_OPTION.recommended=“5” \
    
doc.ENV.SECOND_OPTION=“String” \
    
doc.ENV.SECOND_OPTION.required=“false” \
    
doc.ENV.SECOND_OPTION.desc="…" \
    
doc.ENV.SECOND_OPTION.default="FooBar"

    but I bet that is not what labels should be used for…
  • there seems to be some “Container Linux” or “Kubernetes” related .dockercfg thing … but I don’t get it … anyhow what is the “spec” for it, even which system use it, and how…

The question behind: how to clean generate / populate a documentation of how an container application can be configured.

any ideas here!?

happy looking forward to get your feedback :wink:

~Marcel