A few weeks back (six to be exact), I woke up to a message from my friend Jad asking about recommended practices on Terraform code organisation. He was looking at this in the context of managing the configuration of a vRealize Automation environment, especially in the scenario where you may have multiple teams with different responsibilities collaborating on that configuration.

Firstly, Jad I apologise for taking so long to get this written up. I hope the content is worth the wait!
Secondly, the thing I love about this particular request is that it opens up the conversation about what kind of things you can do with Terraform. Extending infrastructure-as-code beyond the “consumer” and out to your “admins” gives you a very real opportunity to transform the way you operate and run your infrastructure.

In this series of posts I will walk through my thinking behind module design, the details of each module, and then finally how you can mix and match them to meet the particular workflow you want to achieve.

Workflows

Before we start writing any code, let’s look at the flow that we want to tap into.

While this diagram shows an “end to end” flow, it is also representative of the dependencies between each of these elements - or so I thought when I started! More on that later.

In a real world deployment, you are unlikely to be performing end-to-end configuration very often. An few examples of tasks that would be performed more often:

1. Add a new vCenter, and make its resources available for consumption.
2. Configure a new Project, add existing resources/bring your own resources.
3. Configure a new network in NSX, add the network to a Network Profile.
4. Create a new template/image, update an existing Image Profile.
5. Create new image/flavor profiles due to adding a new logical Datacenter in vCenter.

These flows (among others) make you think about who it is that might be performing all of these actions. Is it going to be the same team, or different teams?

With that, I’m going to break this problem space down into two parts:

1. How can I write Terraform code that is flexible to support multiple flows, and makes my configuration more composable; and
2. How can we collaborate on our configuration beyond a single team?

Composable infrastructure configuration with modules

Modules sound like a pretty complex thing to build, but in reality they are just another set of Terraform code. They allow you to bring multiple resources together and simplify their interface for downstream consumption.

The main trick in this process of simplification is determining what kind of contract you intend to provide. This is just a fancy way of saying that you need to think about what kind of inputs (variables) you are going to need, and what kind of outputs you are going to provide. You also need to think a bit about which resources it makes sense to place into a single module.

Module requirements

After a bit of trial and error, I ended up landing on modules for each of the following, with the respective requirements as a starting place:

Cloud Accounts
Requirements:

• Configure a cloud account with only specified vSphere Datacenters enabled.
• Must be able to handle multiple key/value pairs to implement capability tags (these are a vRA construct).
• Return the ID of the created cloud account so that it can be used for downstream modules.
  Discarded:
• Support for multiple cloud accounts. This would have added unnecesary complexity to the user input model, and made assumptions about the capability tags being consistent between multiple cloud accounts.

Cloud Zones
Requirements:

• Configure one or more zones based on the provided vSphere datacenter name.
• Must be able to handle multiple key/value pairs to implement capability tags (these are a vRA construct).
• Return the zone id so that it can be used by downstream models.

Image Profiles
Requirements:

• Support configuration of multiple image mappings in the context of a single image profile, for a single cloud zone/region.

Flavor Profiles
Requirements:

• Support configuration of multiple flavor mappings in the context of a single flavor profile, for a single cloud zone/region.

Network Profiles
Requirements:

• Support configuration of a Network Profile and the addition of multiple networks to the profile.
• Hide the complexity of filtering for networks through the network fabric.
• Support the application of capability tags.

Storage Profiles
Requirements:

• Support configuration of a Storage Profile and the addition of multiple datastores and configurations to the profile.
• Hide the complexity of configuring Storage Profiles by providing sane defaults for most options.
• Allow users to provide capability tags.

These requirements are a pretty decent starting point, however an important takeaway is that you shouldn’t be surprised if they change a bit as we start testing these modules out. Iteration your implementation based on usage will always deliver a better outcome than sticking to the requirements that you started with based on a set of known or unknown assumptions.

Module layout

In terms of the content, there are a few minor differences between a module and straight Terraform code. Below is the structure of the repo that I will create for each of the modules.

├── main.tf
├── variables.tf
├── outputs.tf
├── README.md
├── examples
|   ├── main.tf
|   ├── variables.tf
|   ├── outputs.tf
|   ├── terraform.tfvars

The two big things are a README.md file, and an examples directory. Normally your README would give an introduction to the problem space of the module, and highlight mandatory and optional inputs, with a simple example. The examples directory might contain multiple sub-directories with examples that address more complex use cases for the module. If you were making this publicly available, you would also include a license file.

Now we have some requirements to work with, and a structure to follow for each of our modules - all that is left is to get coding.
In the next post we will build work through building out the cloud accounts module.

This post is part of a series.
Part 1 - This Article
Part 2 - Terraform Modules: vRealize Automation Administration - Cloud Accounts