Skip to main content

Using templates in Terraform to document a deployment

I’ve been doing a bunch of new Terraform recently, and I’ve started using it to document the deployments it’s creating. In particular, I’ve started using Terraform to create README files which describe the exact infrastructure it’s just created.

Here’s my latest example: a README for an API deployment which tells you where to access the app and how to deploy new versions. All of the instructions (except the initial docker build) can be copy/pasted exactly, with no need for the reader to fill in placeholder values.

Screenshot of a README file for a 'semantic-search API'. It includes a URL where the API can be accessed, and then numbered step-by-step instructions for deploying a new version of the API. Each step includes a brief prose description and then a command for the developer to run.

The alternative would be some sort of generic README with placeholder values that the reader has to fill in, which is how a lot of documentation works – but having them pre-filled is quite nice. It makes it a little bit quicker to start using whatever resources I’ve just spun up.

The sort of stuff I put in these READMEs include:

To create this README, I have Terraform render a template file, and I pass in the

resource "local_file" "readme" {
  content = templatefile(
      name         =
      ecr_repo_url = aws_ecr_repository.api.repository_url
      cluster_name =
      service_name =
      domain_name  = local.domain_name

  filename = "README.html"

and then I tell the user about it with a Terraform output:

output "next_steps" {
  value = <<EOT
Your new API has been created at ${module.api.domain_name}

For instructions on deploying new code, open ${local_file.readme.filename} in your browser

When somebody runs terraform apply, they see something like this:

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.


next_steps = <<EOT
Your new API has been created at

For instructions on deploying new code, open README.html in your browser

I’ve found this especially useful for short-lived or experimental deployments, which aren’t tied into a more automated or polished build system. Having some quick instructions for getting them up and running are quite handy.

I’m not going to do this for all the Terraform I write, but I’m quite enjoying it in the places where I have.