Repository conventions

AWS Platform Guide

thoughtbot creates some standard Git repositories for AWS organizations.

Landing Zone Repository

The landing zone repository contains foundational Cloudformation templates and service control policies deployed as a customized package for Customizations for Control Tower. We typically name this repository “organization-landing-zone.”

landing-zone/
  manifest.yaml
  policies/
  templates/

You can create this repository using the aws-landing-zone-template, by selecting it in the Repository template dropdown during repo creation.

GitHub docs for Creating a repository from a template.

Creating a GitHub repository from a template

Infrastructure Repository

The infrastructure repository contains Terraform modules for managing cloud resources and Kubernetes Helm charts required for the platform. We name this repository “organization infra.”

infra/
  cd/
  ci/
  cicd-common/
  cluster/
  hosted-zones/
  network/
  operations-platform/
  workload-platform/

You can create this repository using the flightdeck-template, by selecting it in the “Repository template” dropdown during repo creation in GitHub.

GitHub docs for Creating a repository from a template.

Application Repository

Source code for applications should also be managed in Git. We recommend that each application contain a Dockerfile for building Docker images and a buildspec for pushing them to an ECR repository.

Dockerfile
buildspec.yaml

You can quickly create new applications using Suspenders.

Manifest Repository

For each application repository being deployed, we will create an additional repository containing deployment manifests and configuration values and makes it easy to deploy both using a CI/CD pipeline. This allows us to separate code from configuration. These repositories should be named “application-manifests.”

buildspec.yaml
bases/
charts/
overlays/

Terraform Conventions

We use Terraform to maintain infrastructure as code.

State Backends

On AWS, we use the S3 backend for Terraform state. We create a separate backend bucket for each AWS account. Terraform state should be encrypted using unique, customer-managed KMS keys. The key for each module’s state should reflect that module’s path within the infrastructure repository.

You can use the Terraform state backend Cloudformation template to create a secure Terraform state backend for each AWS account. When using Control Tower, you can use customizations for Control Tower to create a Terraform state backend as part of the baseline for each account.

The landing zone template repository comes with configuration for Terraform state backends.

Filenames

`backend.tf`	Configuration for the state backend
`main.tf`	Resources, data sources, modules, and locals
`outputs.tf`	Outputs
`providers.tf`	Configuration for Terraform providers
`variables.tf`	Variables
`versions.tf`	Required Terraform and provider versions

Formatting

All files should be formatted using terraform fmt.

AWS Platform Guide

The guide for building and maintaining production-grade Kubernetes clusters with built-in support for SRE best practices.

Source available on GitHub.

Work with us to scale your application, improve stability, and increase the rate of defect-free deployments.

Get Started