terraform-docs VS terraform

Documentation is really important, so having a README.md file inside your Terraform repository that explains how to use the automation (including descriptions of variables and outputs) really help in understanding what has been implemented. To easily generate the description of variables and outputs, you can leverage tfdocs.

‍Terraform-docs is a tool that automatically generates documentation from Terraform modules in various output formats, including markdown, JSON, and others. It's particularly useful for maintaining up-to-date documentation of your Terraform modules' inputs, outputs, providers, and resources.

Earlier this year I wrote about the challenges I faced creating a Terraform module. I mentioned then that I was leveraging terraform-docs and GitHub Actions to automate documentation, but a full workflow walkthrough was out of that post's scope.

### Muti-Stage pipeline for windows trigger: - main variables: terraformDocsVersion: '0.16.0' serviceConnectionName: 'Terraform-SPN-DevOps-MagiconionM' keyvaultName: 'pwd9000-core-kv' pool: vmImage: 'windows-latest' stages: - stage: GenerateTerraformDocumentation jobs: - job: Generate_Terraform_Documentation steps: - checkout: self persistCredentials: true # this allows the later scripts to use the system-provided git token to push changes back to the repo ### Link to key vault. - task: AzureKeyVault@1 inputs: azureSubscription: $(serviceConnectionName) #ADO service connection (Service principal) KeyVaultName: $(keyvaultName) SecretsFilter: 'TerraformDocsPAToken' RunAsPreJob: true displayName: Get PAToken from Keyvault ### Install Terraform-Docs. - powershell: | Invoke-WebRequest -Uri "https://github.com/terraform-docs/terraform-docs/releases/download/v$(terraformDocsVersion)/terraform-docs-v$(terraformDocsVersion)-windows-amd64.zip" -OutFile "terraform-docs.zip" Expand-Archive -Path "terraform-docs.zip" -DestinationPath "$(System.DefaultWorkingDirectory)\terraform-docs" -Force $env:Path += ";$(System.DefaultWorkingDirectory)\terraform-docs" displayName: 'Install terraform-docs' ### Remove all old README.md files and generate new README.md files for each TF module. - powershell: | # Set Modules Root Directory Set-Location "$(Build.SourcesDirectory)\@TF_Modules" # Get all subdirectories (Terraform module directories) $terraformModuleDirs = Get-ChildItem -Path (Get-Location) -Directory # Loop through each directory to cleanup/remove old README files foreach ($dir in $terraformModuleDirs) { # Get all files in the directory $readMeFiles = Get-ChildItem -Path $dir.FullName -Filter 'README.md' # Loop through each file in each terraform module foreach ($file in $readMeFiles) { # Check if README file already exists and remove if ($file) { # Remove the file Remove-Item $file.FullName -Confirm:$false Write-Output "Old file '$($file.Name)' removed from '$($dir.FullName)'" } } #After cleanup create a new README.md file with 'terraform-docs' based on latest TF module code in current folder(terraform module) $tfFiles = Get-ChildItem -Path $dir.FullName -Filter *.tf if ($tfFiles.Count -gt 0) { # Create new README.md file $(System.DefaultWorkingDirectory)\terraform-docs\terraform-docs.exe markdown table $dir.FullName --output-file "README.md" } else { Write-Output "No .tf files found." } } displayName: 'Cleanup and Generate new README for each TF module' ### Commit and push updated README.md files for TF modules. - powershell: | git config --local user.email "[email protected]" git config --local user.name "Terraform Docs" git add *.md git commit -m "Update README.md for each TF module" git push origin HEAD:$(Build.SourceBranchName) displayName: 'Commit and Push updated README.md files for TF modules' env: SYSTEM_ACCESSTOKEN: $(TerraformDocsPAToken)

I'm going to have to figure out how to run terraform-docs.io against each module. I have zero terraform experience.

Terraform-docs: This tool generates documentation for your Terraform modules in various formats, such as Markdown, HTML, and JSON. Terraform-docs parses your Terraform code and extracts documentation from comments, variable and output descriptions, and input/output examples. The tool then generates a table of contents with links to the relevant documentation for each module, which makes it easy to understand the purpose and usage of each module.

Terraform docs

I have been using https://terraform-docs.io to generate documentation of my terraform modules. However creating nested objects with optionals makes the documentation rather ugly and hard to read. See gh issue which also describes this type of issue: https://github.com/terraform-docs/terraform-docs/issues/656

I am looking for a way to automate doc creation and updates for ansible roles. I recently discovered terraform-docs and I am curious if there is something similar for ansible.

terraform-docs: https://github.com/terraform-docs/terraform-docs

Do you have other Terraform-related open-source tools that you recommend? Please go ahead and add in the comments!

State Encryption was one of those long requested features[0] (I had it on my ideas list for years[1]) that Hashicorp didn't have much incentive to build. I don't think it has to with distancing opentofu as such, but the opentofu team prioritizing the right things that customers actually need.

[0]: https://github.com/hashicorp/terraform/issues/9556

[1]: https://github.com/captn3m0/ideas#-mars-terraform-remote-htt...

https://github.com/hashicorp/terraform/issues/34402

I’m not a lawyer and have no idea who is right or wrong but I understand why Hashicorp is scrutinizing this.

Just to give an example of the power of Go for CLI builds, you may have already used or at least heard of Docker, Kubernetes, Prometheus, Terraform, but what do they all have in common? They all have a large part of their usability via CLI and are developed in Go 🐿.

Each app’s front end is built with Qwik and uses Tailwind for styling. The server-side is powered by Qwik City (Qwik’s official meta-framework) and runs on Node.js hosted on a shared Linode VPS. The apps also use PM2 for process management and Caddy as a reverse proxy and SSL provisioner. The data is stored in a PostgreSQL database that also runs on a shared Linode VPS. The apps interact with the database using Drizzle, an Object-Relational Mapper (ORM) for JavaScript. The entire infrastructure for both apps is managed with Terraform using the Terraform Linode provider, which was new to me, but made provisioning and destroying infrastructure really fast and easy (once I learned how it all worked).

For example, integrating Terraform for infrastructure as code (IaC) into the IDP can streamline updates and rollbacks.

In this project, you will understand and get hands on experience around the entire concept around CI/CD from applications perspective. To fully gain real expertise around this idea, it is best to see it in action across different programming languages and from the platform perspective too. From the application perspective, we will be focusing on PHP here; there are more projects ahead that are based on Java, Node.js, .Net and Python. By the time you start working on Terraform, Docker and Kubernetes projects, you will get to see the platform perspective of CI/CD in action.

Infrastructure as Code (IaC) is an important part of any true hosting operation in the public cloud. Each of these platforms has their own IaC solution, e.g. AWS CloudFormation. But they also support popular open-source IaC tools like Pulumi or Terraform. A category of tools that also needs to be discussed is API gateways and other app-specific load balancers. There are applications for internal consumption, which can be called microservices if you have a lot of them. And often microservices use advanced networking options such as a service mesh instead of just the native private network offered by a VPC.

To quickly deploy the architecture, we will be using Terraform. With Terraform, we can automate the deployment process and have our infrastructure up and running in minutes.