Creating documentation isn’t fun. I’ve done my fair share in 10 years of administering systems. I’ve written documentation on AD, Exchange, router and switch configurations, VoIP system configuration and operations, and so on. As a one man shop that architected all the systems I ran, I was unsure what level of detail was required. What helped the most was having an outside resource that could review the documentation and try to fix a problem given the information I documented. Whatever question he had, that also had to be added.

What I’m not used to is taking over an infrastructure or application and being tasked to administer it. Even with decent documentation from the previous admin, you really don’t know the environment until you’ve had to fix a problem.

Recently, I tasked myself with taking over and update an internal application when the previous owner left. Because it was a small (but useful) tool, documentation was non-existent. To make the necessary updates to it, I had to spend plenty of time understanding how the application was structured. Once that I was done, I was ready to add my code and begin testing it.

Here’s the problem I was faced with: I don’t want to disrupt the application in production so I need a test environment but I don’t know everything I need to install to match the production application. Sure I could clone the VM, change the hostname and IP address, etc and hack at it that way. But there’s a better tool to tackle this with that will allow me to document the application and build the environment in a repeatable way. Enter configuration management and the concept of infrastructure as code.

Tools such as Puppet, Chef, and Ansible enable this ability. By implementing the concept of infrastructure as code, admins have the ability to provide useful documentation for systems and applications in the environment and also establish a mechanism to stand up additional application components or even provision new hardware. I chose to learn Ansible because I like the fact that the syntax is very simple (YAML), it uses SSH to communicate with the host, and is agentless.

From my investigation into the app, I know I need Ubuntu Linux, PHP, Apache, Postgresql, and Python. With a little command line-fu, I can find out which versions of the software I need and ensure that my configuration specifics those versions to be installed.

By implementing the concept of infrastructure as code, relevant and detailed documentation is provided for you, your team, and those that come after you.