Terraforming Parts Unknown: Strategies for Expanding Your Terraform Repertoire

Anyone using Terraform to increase repeatability/reliability of an infrastructure has experienced the need — and urgency — to deploy resources that are entirely new. Whether these resources are for a new product initiative, a client feature requirement or a personal project, below, I describe the process I use to work through challenges of deploying new-to-me resources.

THE BIG PICTURE

Terraform's declarative, idempotent configuration syntax is a powerful tool for maintaining consistency while interacting with a single service provider. Resources from each service provider have distinct arguments, attributes and representation in Terraform's state. For example, there isn’t an abstraction layer that allows us to treat VM resources in AWS like those in Azure/Digital Ocean/VSphere. This becomes clearer when thinking about the unique service provider offerings.

To effectively use Terraform to manage any arbitrary resource, you need two of three things:

• a basic understanding of Terraform's configuration syntax;
• a mental model of the resource, its relationships with other resources, and its service provider;
• a pragmatic approach to developing and refining your understanding of the resource.

Let’s walk through my process for reaching a critical mass of familiarity with an otherwise mysterious resource. These approaches are roughly ordered by the time investment needed, rather than sequence. I expect each individual would follow a unique path, even if the end results were identical. The deeper the mystery, the deeper the search.

1. Read the Terraform Docs for the Resource

This is obvious, but I find the concise, consistent formatting of Terraform resource docs easier to read than the service provider’s. Sometimes a good example and the descriptions in the argument reference are all I need to get a first-draft config written and applied into a sandbox. Otherwise, I typically spend time bouncing through related resources.

2. Search It Up

This is usually the first instinct, and justifiably since the ever-expanding bounty of articles, blog posts and GitHub Gists can be invaluable, regardless of our experience in cloud computing, Infrastructure as Code (IaC) or traditional development/operations roles.

My advice:

• don't copy/paste, you might seriously regret it;
• read multiple sources to compare where they agree/differ;
• cross-reference example configs with Terraform docs;
• don't limit your search to "with Terraform” — seek understanding, then code.

3. Try It with the Service Provider's Tools

By thinking of Terraform as a wrapper around the service provider's API, it is clear that exploring their native tools can answer specific questions about the resource. This can also expose you to relevant aspects of the platform. Consider:

• Do the CLI tools require the arguments you expect?
• What methods exist to describe the resource — do those fit your understanding?
• What parameters does the GUI interface ask you to provide?
• How does the GUI graphically represent the resource's relationship with the platform?

4. Build a Reference Prototype

The goal of this process is to explore the service provider and develop an intuitive sense of the resource. Once you have a strong understanding of the resource, you can build a prototype that fulfills one or two of the basic behaviors you're implementing.

Once you have a prototype, you can:

• use the service provider's tools to dump/describe the resource descriptions (to JSON, or what-have-you);
• write a from-scratch config;
• import the resource into Terraform. Add just the required arguments to get it to import, then use terraform state show or terraform plan and test modifying the resource config at will.

A few caveats to bear in mind:

• experiment in environments dedicated to that purpose — never in production;
• don't assume a 1:1 between GUI/CLI actions and Terraform resources;
• if you build up a config based on a JSON dump or Terraform plan/state show, replace the literal values with references to related resources;
• always destroy/taint and recreate imported resources to be sure your config correctly describes the resource and its dependencies.

Did I mention: never do this on production or any non-disposable environments!

5. Read the Service Provider Docs

Hey, where were these at when you were Searching It Up?

WRAPPING UP

In-between investigation activities, it’s been useful to ask myself:

• What do I know?
• What’s confusing?
• What information/experience am I missing?
• What’s the next step to divide and conquer the uncertainty?

There isn’t any magic here, but hopefully there’s an idea that will help you when you're looking to fill the gaps. If there is, let us know! If I've left out some interesting approach or made a grievous error, I'd appreciate hearing about that too.