General Style Guide¶

Terraform files should obey the syntax rules for the HashiCorp Configuration Language (HCL) and the general formatting guidelines provided by the Terraform Project through the fmt command.

In addition, Rackspace follows the following standards when writing Terraform:

• Use Snake Case for all resource names
• Declare all variables in variables.tf, including a description and type
• Declare all outputs in outputs.tf, including a description
• Pin all modules and providers to a specific version or tag
• Always use relative paths and the file() helper
• Prefer separate resources over inline blocks (e.g. aws_security_group_rule over aws_security_group)
• Always define AWS region as a variable when building modules
• Prefer variables.tf over terraform.tfvars to provide sensible defaults

Running terraform¶

• All changes should be made through CI/CD tooling, and Terraform should not be run locally – especially terraform apply
• Terraform versions and provider versions should be pinned, as it’s not possible to safely downgrade a state file once it has been used with a newer version of Terraform
• Create “GitHub release” objects for releases, which automatically make tags, lets us define release notes / change log, and provides download links
• S3 (standard region) with DynamoDB locking, with versioning & server-side encryption in S3
• Standard bucket name : tf-state-(aws acct #)
• All changes should be mapped to a specific AWS account as a GitHub repo
• Read only state should be visible directly in S3
• Repositories should always have a .terraform-version file.

Grouping state into layers¶

There are a few different designs employed in the Terraform community for how to structure your Terraform files, modules, and directories. The community around Terraform has written blog posts and spoken at HashiConf about how these patterns evolve over time; many of the recommendations focus on how to best group Terraform state. At Rackspace, we’ve built upon the existing best practices (e.g. ‘Terraservice’) and created a concept we call layers in order to isolate Terraform state.

Writing and organizing Terraform with modules¶

Generally, Rackspace maintains modules for most common use cases, and uses these modules to build out your account. If we do not have a pre-existing module, the next best choice is to use the built-in aws_* resources offered by the AWS provider for Terraform. Please let us know if we don’t have a module or best practice for building out a specific resource or AWS product.

A common recommendation in the Terraform community is to think of modules as functions that take an input and provide an output. Modules can be built in your shared repository or in your account repositories. If you find yourself writing the same set of resources or functionality over and over again, consider building a module instead.

When to consider writing a module:

• When multiple resources should always be used together (e.g. a CloudWatch Alarm and EC2 instance, for autorecovery)
• When Rackspace has a strong opinion that overrides default values for a resource
• When module re-use remains shallow (don’t nest modules if at all possible)

Rackspace Module Standards¶

Rackspace maintains a number of Terraform modules available at https://github.com/rackspace-infrastructure-automation. Contributions should follow these guidelines.

• use semantic versioning for shared code and modules
• always point to GitHub releases (over a binary or master) when referencing external modules
• always extend, don’t re-create resources manually
• parameters control counts, for non-standard numbers of subnets/AZs/etc.
• use overrides to implement Rackspace best practices
• use variables with good defaults for things Rackspace expects to configure
• Modules should use semantic versioning light (Major.minor.0) for AWS account repositories
• Modules should be built using the standard files: main.tf, variables.tf, output.tf
• Consider writing tests and examples, and shipping them in directories of the same name
• Readme files at should contain a description of the module as well as documentation of variables. An example of documentation can be found here.
• The files in .circleci are managed by Rackspace and should not be changed. If you would like to submit a module, please do so without this folder.
• The files in example can be named anything as long as they have .tf as the extension.
• The tests directory must be called tests and each test must be test#. Inside each test# folder should be exactly one file called main.tf
• Use Github’s .gitignore contents for Terraform.

  variable "environment" {
    description = "Application environment for which this network is being created. one of: ('Development', 'Integration', 'PreProduction', 'Production', 'QA', 'Staging', 'Test')"
    type        = "string"
    default     = "Development"
  }
   variable "tags" {
    description = "Custom tags to apply to all resources."
    type        = "map"
    default     = {}
  }

  locals {
    tags {
      Name            = "${var.name}"
      ServiceProvider = "Rackspace"
      Environment     = "${var.environment}"
    }
  }

tags = "${merge(var.tags, local.tags)}"