Better Documentation with Infrastructure as Code

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.


Intro to Git and the Rise of Social Coding Presentation

Over the Christmas season, I participated in social coding community event called Commitmas. The objective was to learn git and try to use it every day for 12 days. As I wrote in another blog post, Rockin Around the Commitmas Tree, this was a great opportunity to jump start learning to use it with others in the community.

Since then I’ve continued using git on a regular basis for various side projects. I wanted the opportunity to share with the PernixData SE team a little bit about what I’ve learned and why it’s important for us to learn and use git. I feel that learning git is a crucial foundational skill for building and managing next generation datacenters and developing applications. I also like git for daily use to manage versions of documents or presentations.

Putting together this presentation was a bit special for me for two reasons. First, it’s the first technical presentation that I created that wasn’t related to my core competency, VMware vSphere. This stands out to me because it’s representative of my personal journey to be an early adopter of these new technologies. The configuration management/container/PaaS space is still in a very early phase and it reminds me of stories I’ve heard about having to perform vMotion on the command line. That’s always sound so old school to me because I started using vSphere in 2009 when 4.0 was released and it was all well established. I often wonder what this space will look in a few years and will it take less time to mature.

It’s also the first time that I’ve used reveal.js to create a presentation. I’ve had the chance to see a few presentations with done with reveal.js and really like the elegance and simplicity of it. As a technologist, I like the geekiness of creating my presentation with HTML.

Git: Syncing a Fork In It

On the second day of Commitmas, I had a new hurdle to jump — I forked @mjbrender’s repo, submitted a PR, and he accepted my changes as well as changes from @joshcoen and now my fork is outdated. How do I update my fork and local repo with the changes?

To rectify this, we’re going to leverage two git commands: git remote add upstream and git fetch upstream command.

With git remote add upstream, we’re going to specify the repository that we forked. In my case, I did:

git remote add upstream

A git remote -v verifies that we added the upstream source:

Screen Shot 2014-12-22 at 10.12.15 PM

Then we perform git fetch upstream to copy the original repository (the one we forked) to our local repository (on our dev box):

Screen Shot 2014-12-22 at 10.12.23 PM

Now we just fetched the upstream/master branch/repo and needs to be merged into our master branch. We can switch to our master branch with git checkout master.

Finally, git merge upstream/master to merge upstream/master to our master branch.

Screen Shot 2014-12-22 at 10.12.55 PM

The final stretch! Our local repository is now a clone of the original repository again but we need to push our changes back to our repository on GItHub.

Screen Shot 2014-12-22 at 10.28.16 PM

Done! Join in the Commitmas conversation on Twitter using the #vBrownBag hashtag! Happy committing!

Rockin’ Around the Commitmas Tree


My good friend Matthew Brender started a fun project for the holiday season called 12 Days of Commitmas to encourage everyone to continue to grow over the holiday season by learning or expanding their knowledge with git and coding. These skills will become increasingly prevalent and necessary in 2015 as more sysadmins and organizations implement version control to manage code for configuration management tools like Ansible.

When looking at the skill levels that Matt created, I found myself between beginner and intermediate. In the spirit of code contribution and learning git, and playing with Markdown, I submitted my first pull request on GitHub to expand the skill levels.

My Goal for Commitmas

Because my coding skills are relatively weak (improving them is a 2015 goal), I will contribute documentation to a project on GitHub. Internally on the SE team at PernixData, there are some PowerShell scripts that I will create repositories for in GitLab. I haven’t picked a project on GitHub yet to contribute to but I’m considering something related to Ansible. This will give me a chance to explore the different Ansible projects on GitHub and learn/do more with Markdown. I’m also going to push all of my commits using the CLI as I currently lean heavily on the GUI. I know there’s nothing wrong with using the GUI but I believe that true mastery comes from using the CLI when applicable.

Join in the Commitmas conversation on Twitter using the #vBrownBag hashtag! Happy committing!

Enabling Sublime Text for Command Line Use

I have been using Sublime Text 2 on my PC for a few months and now that I have a Mac, I got around to installing it today. I have been used to modifying scripts and code snippets from the command line by using “subl <filename>”. Unfortunately, that didn’t work after installing Sublime. I’ve read other blog and seen people use it so I figured that it was just an error after installation. Let’s fix it!

The first thing we need to do is create a .bash_profile file if we don’t have one already.

touch ~/.bash_profile

Then we can add this nifty alias to our .bash_profile:

alias subl=”/Applications/Sublime\ Text\”

Finally, reload that bad boy

source ~/.bash_profile

This was a head scratcher but a quick fix.