terraform-docs VS OPA (Open Policy Agent)

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!

How can we handle this? Are there any mechanisms to prevent or at least to some extent safeguard this kind of issues without falling back to a manual workflow? There is. One huge advantage of sticking to (de-facto) standards like Terraform is that first we are probably not the first ones to come up with this question and second there is a huge ecosystem around Terraform that might help us with such challenges. And for this specific scenario the solution is the Open Policy Agent. Let us take a closer look how the solution could look like.

A popular Policy-as-Code tool for Terraform is OPA, everyone's favorite versatile open-source policy engine that enforces security and compliance policies across your cloud-native stack, making it easier to manage and maintain consistent policy enforcement in complex, multi-service environments.

Harness Policy As Code uses Open Policy Agent (OPA) as the central service to store and enforce policies for the different entities and processes across the Harness platform. In this section, you will define a policy that will deny a pipeline execution if there is no approval step defined in a deployment stage.

OPA: While OPA is an open-source, general-purpose policy engine capable of enforcing unified and context-aware policies throughout the stack, it can also accept and output data in formats such as JSON, effectively functioning as a tool for generating or modifying configurations. Although it does not provide out-of-the-box schema definition support, it allows the integration of JsonSchema definitions.

In essence, container image signing involves adding a digital stamp to an image, affirming its authenticity. This digital assurance guarantees that the image is unchanged from creation to deployment. In this blog, I'll explain how to sign container images for Kubernetes using Cosign and the Open Policy Agent. I will also share a tutorial that demonstrates these concepts.

In this post we will explores two powerful solutions for addressing this issue: the Open Policy Language (OPA) and Google’s Zanzibar.

Rego is a declarative query language from the makers of the Open Policy Agent (OPA) framework. The Cloud Native Computing Foundation (CNCF) accepted OPA as an incubation-level hosted project in April 2019, and OPA graduated from incubating status in 2021.

Now there are more subdivided practice: * Policy as Code: Sentinel, OPA * Database as Code: bytebase * AppConfiguration as Code: KusionStack, Acorn * ...... (Welcome to add more)