Documentation for Terraform usage and best practices
For our purposes, Terraform is a declarative way to provision AWS resources. It can be used for infrastructure or deployable applications.
To use Hashicorp's own description, Terraform enables you to safely and predictably create, change, and improve infrastructure. It is an open source tool that codifies APIs into declarative configuration files that can be shared amongst team members, treated as code, edited, reviewed, and versioned.
You can think of Terraform as our successor to handel and handel-codepipeline. It's more powerful and more flexible, but it requires some additional knowledge about the way AWS resources operate.
We're the Terraform Working Group at BYU OIT. Connect with us!
Follow the steps at byu-oit/hello-world-api to create and deploy a simple application.
Use the S3 Backend module to deploy the Backend resources (S3 Bucket and Dynamo Table) into your account. This only needs to be done once per account. In each project's main.tf, include the following block at the top:
terraform {
backend "s3" {
bucket = "terraform-state-storage-<account_number>"
lock_table = "terraform-state-lock-<account_number>"
key = "my-cool-app.tfstate"
region = "us-west-2"
}
}
Terraform Modules are in public GitHub repositories using the naming pattern terraform-<provider>-<module_name>. They should be created from the terraform module template and have the terraform-module GitHub topic.
Deployable Terraform applications should be in private GitHub repositories. They should have the terraform GitHub topic.
Our terraform modules follow (for the most part) the module structure defined by Terraform. See the terraform module template for the basic structure of our terraform modules.
When using a terraform module you specify a source which tells Terraform where to find the source code for the module.
We have opted to use the GitHub source method using git
over HTTPS to pull the source code of our modules living in public GitHub repos. This is the easiest way to pull modules
from GitHub from within a CICD pipeline (aka CodeBuild) without having to do extra configuration. The downside to this
is if you need to use a module residing in a private GitHub repo, you will then have to use a GitHub access token tied
to a user who has access to the private repo.
The Terraform Working Group is a group of individuals from different teams working together on the best practices of using Terraform at BYU. There is no particular owner, product, nor project backing the Terraform Working Group.
- GitHub team: Terraform Developers
- Slack channel: #terraform
- Participate in working group meetings
- Thursdays from 2:30 to 4 (for the year 2020) - Ask on Slack for calendar invite or Zoom link
- Meeting notes: Box
- Task Board: ServiceNow
Reach out on Slack at #terraform, or create GitHub issues and pull requests on existing repositories.
To create a new module, create a new repo from the the terraform module template, name it accordingly, and share the repository with the Terraform Developers team on GitHub, which will allow you to request reviews from the Terraform Developers.