terraform-docs/docs/USER_GUIDE.md

User Guide

Terraform Versions

Support for Terraform v0.12.x has been added in terraform-docs version v0.8.0. Note that you can still generate output of module configuration which is not compatible with Terraform v0.12 with terraform-docs v0.8.0 and future releases.

Installation

Please refer to Installation for various installation options.

Code Completion

The code completion for bash or zsh can be installed using:

Note: Shell auto-completion is not available for Windows users.

bash

terraform-docs completion bash > ~/.terraform-docs-completion
source ~/.terraform-docs-completion

# or simply the one-liner below
source <(terraform-docs completion bash)

zsh

terraform-docs completion zsh > /usr/local/share/zsh/site-functions/_terraform-docs
autoload -U compinit && compinit

To make this change permanent, the above commands can be added to your ~/.profile file.

Syntax, Usage, and Output Formats

Please refer to Formats Guide for guidance on output formats, execution syntax, CLI options, etc.

Docker Image

terraform-docs is also available as a Docker image. Docker tag latest refers to latest stable released version and edge refers to HEAD of master at any given point in time.

docker run quay.io/terraform-docs/terraform-docs

The named version tags are identical to the official GitHub releases without leading v.

docker run quay.io/terraform-docs/terraform-docs:0.9.0 # corresponding to v0.9.0 release

Usage:

# to view the help
docker run quay.io/terraform-docs/terraform-docs help

# to view the version
docker run quay.io/terraform-docs/terraform-docs version

# to generate 'markdown table' of '/path/to/module'
docker run \
    -v /path/to/module:/module \
    quay.io/terraform-docs/terraform-docs \
    markdown table --sort-by-required /module

Configuration File

terraform-docs can read the desired formatter and options from a file, instead of being passed to in CLI. This is a convenient way to share the configuation amongst teammates and also CI pipelines. To do so you can use -c or --config flag which accepts name of the config file (default to .terraform-docs.yml). Example .terraform-docs.yml:

formatter: markdown table
header-from: doc.txt
sections:
  hide:
    - inputs
    - outputs
settings:
  indent: 4
  required: false

when executed:

terraform-docs ./example/ # this will read the config above and:
                          #
                          # 1) generate output of 'Markdown Table'
                          # 2) read module 'Header' from 'doc.txt'
                          # 3) hide 'Inputs' and 'Outputs'
                          # 4) set 'Indention' to 4
                          # 5) hide 'Required' column

Please refer to Config File Reference for all the available confiuartion options.

Control Visibility of Sections

Output generated by terraform-docs consists of different sections (header, requirements, providers, inputs, outputs) which are visible by default. The visibility of these can be controlled by one or combination of : --show-all, --hide-all, --show <name> and --hide <name>. For example:

terraform-docs --show-all --hide header ...                # show all sections except 'header'
terraform-docs --hide-all --show inputs --show outputs ... # hide all sections except 'inputs' and 'outputs'

Generate Module Header

Module header can be extracted from different sources. Default file to extract header from is main.tf, otherwise you can specify the file with --header-from FILE. Supported file formats to read header from are:

1. .adoc
2. .md
3. .tf
4. .txt

The whole file content is being extracted as module header when extracting from .adoc, .md or .txt. But to extract header from .tf file you need to use following javascript, c or java like multi-line comment:

/**
 * # Main title
 *
 * Everything in this comment block will get extracted.
 *
 * You can put simple text or complete Markdown content
 * here. Subsequently if you want to render AsciiDoc format
 * you can put AsciiDoc compatible content in this comment
 * block.
 */

resource "foo" "bar" { ... }

Note: This comment must start at the immediate first line of the .tf file before any resource, variable, module, etc.

Generate terraform.tfvars

You can generate terraform.tfvars in both hcl and json format by executing the following:

terraform-docs tfvars hcl /path/to/module

# or

terraform-docs tfvars json /path/to/module

Note that any required input variables will be empty, "" in HCL and null in JSON format.

Integrating With Your Terraform Repository

A simple git hook .git/hooks/pre-commit added to your local terraform repository can keep your Terraform module documentation up to date whenever you make a commit. See also git hooks documentation.

#!/bin/sh

# Keep module docs up to date
for d in $(ls -1 modules)
do
  terraform-docs md modules/$d > modules/$d/README.md
  if [ $? -eq 0 ] ; then
    git add "./modules/$d/README.md"
  fi
done