Introducing fastly2git: version change visualization

As a Sales Engineer at Fastly, I spend much of my time building and testing services. Services are our unit of configuration: typically, you would have a service for each domain that you cache through Fastly.

Here’s the basic workflow: you make changes to a new version of the configuration for a service. Once you’re happy with the changes, you activate the version. Within a few seconds, the new version of the configuration is live and serving your traffic.

I love this rapid, iterative workflow, and at times while prototyping an experiment I end up with tens or hundreds of versions. I sometimes need to check which version introduced what logic. A neat tool in the Fastly web application is version diff, which allows you to inspect the changes between any two different versions of a service. I thought it would be nice if I could explore the versions interactively on my local computer using command line tools. For example, I could annotate every part of the configuration with what version that part was introduced in to help track down logic bugs.

I built a little tool you might use to help you dig into a Fastly service’s configuration using command line tools on your local computer and quickly figure out where certain logic was introduced. Let me take you through my thought processes.

I had a little think about this. I noticed three things:

1. Everything you see in the Fastly application is based on the Fastly API, so I could access all the information about service versions programmatically.

2. We number service versions as increasing integers (1, 2, 3…), but you can activate old versions, so your activation history can look like (1, 2, 4, 3, 5, 6…). This reminded me a little of source code version control systems like Subversion or Git.

3. Changing our configuration either the easy way (in the application) or in a more involved way that also provides greater power (by uploading Custom VCL) results in changes to one file. We call this the “generated VCL” which is compiled and distributed to our cache nodes.

I’ve previously investigated the internals of version control systems and this led me to wonder if I could expose the versions of a service in a Git repository. With a little help from the Fastly API and Rugged Ruby modules, and a small amount of programming later, I present: fastly2git.

Given a Fastly API key, a service ID and a local directory, fastly2git will download the generated VCL for all of the versions of a service and create a Git repository containing them:

You can investigate the changes between the current and previous versions or arbitrary versions. Here I’m using git log -p --word-diff=colorto show additions in green and removals in red for all versions:

You can even annotate which version any line in the latest configuration has come from, for example, to see which version introduced a particular piece of logic:

I certainly had fun writing fastly2git. Let me know in the comments below if you find it useful, and don’t hesitate to contact support@fastly.com with any questions.