Transforming Terraform Output Values to Markdown with Terraputs

An introduction to using a tool I wrote, terraputs, to transform Terraform configuration output values to markdown. I owe a hat tip to my colleagues Justin LaRose and Travis Truman for giving me the idea to create terraputs.

Problem

You’d like to publish your Terraform configuration’s up-to-date output values in a human-friendly, easy-to-read, accessible format. Perhaps you’d like to publish their current values to your project’s README.md, a wiki, or some other form of documentation.

Solution

terraputs is a minimal CLI tool I created to print Terraform output values as markdown.

Usage

terraputs accepts a -state flag, the value of which should be a Terraform configuration’s state JSON, as represented by terraform show -json. For example:

terraputs \
  -state $(terraform show -json)

As a result, terraputs reads the Terraform configuration’s state, parses the outputs’ names, values, and types, and prints a markdown representation. For example:

# Terraform Outputs

Terraform state outputs.

| Output | Value | Type
| --- | --- | --- |
| a_basic_map | map[foo:bar number:42] | map[string]interface {}
| a_list | [foo bar] | []interface {}
| a_nested_map | map[baz:map[bar:baz id:123] foo:bar number:42] | map[string]interface {}
| a_sensitive_value | sensitive; redacted | string
| a_string | foo | string

terraputs also accepts an optional -heading flag for specifying the heading value. For example:

terraputs \
  -state $(terraform show -json)
  -heading "Terraform outputs for `$(terraform workspace show)`"

…which could result in a custom heading clarifying context, such as the output values’ environment or workspace:

# Terraform outputs for `production-aws-us-east-1`

Demo

The demo shows…

  1. applying a Terraform configuration with output values of various types
  2. using terraputs to save the Terraform configuration’s outputs as an OUTPUTS.md markdown file, in effect surfacing human-friendly documentation of the up-to-date outputs values that can be published to a git repo, wiki, and/or project documentation.
  3. using glow to render the OUTPUTS.md file, providing viewers a sense of its rendered formatting