nSights Talks

Documentation as Code Using Terraform-Docs

Tutorial Highlights & Transcript

00:00 - Beginning of Video
Hi everyone, today I’m gonna give a really short demo about documentation using Terraform Docs. I got to know about this when I wanted to create an automatic ReadMe whenever I create a pull request into another branch.
00:24 - What is Terraform-Docs
What is Terraform-docs? It helps you create a ReadMe by looking at your Terraform code, which includes modules and providers. You don’t have to do anything. Just write Terraform code and it will create the documentation for you. You can use this with CI pipelines or even run this on your local hosts to do testing. If you want to do this on your local host, this is the type of command you would use to run this on your local host.
00:58 - Basic Actions Script
Today, I’m going to be using it with GitHub actions. This is what the basic GitHub actions workflow looks for in Terraform Docs. I’ll be triggering the Terraform docs with a pull request. I’ll create a pull request from my dev branch into the main branch, and the dev branch doesn’t have a ReadMe. If I create the pull request, it will automatically trigger this workflow and create a ReadMe and inject it into the main branch. Here we can see this increasingly cloning the branch into the host. And using the Terraform docs module, it will create a ReadMe in the output file and inject it.
01:53 - When to Use Terraform-Docs
When do you use Terraform-documents? You can use this whenever you want to create healthy documentation. There’s also an attached GitHub link. I’ll drop the GitHub link into the chat if anyone wants to go to the GitHub repository and use it for their own testing and purposes.
02:11 - Demo
Let me show you how it works. I’ve created this workflow over here in my GitHub repository. Currently, this is the same workflow that I showed you in the screenshot. This branch doesn’t have a ReadMe. As I create a pull request from this branch to the main branch, it will create a ReadMe and inject it into this branch. I’ve created a pull request, so it will trigger the job. This dev branch should have ReadMe now. As we can see, it has created ReadMe requirements. It has the provider name and version, the Docker version, provider name, and modules. It included the VPC module, the resource directory being created in an S3 bucket, input variables that are being called, and outputs. We can create custom documents with this like the way it originally created the documentation.
Jasmeet Singh

Moeez ul Haq

DevOps Support Engineer


Moeez is a DevOps Support Engineer at nClouds.