10 February 2022
If you are using Bicep to define your Azure infrastructure, you'll know how much easier it is than using ARM. If you've been writing Infrastructure as Code for even a short space of time you'll have noted the uncanny similarities between it and Terraform. Being the new tool on the block it lacks a few utilities that an established player such as Terraform has. One such tool is a document generator. This means that creating and updating documentation for your infrastructure has to be done manually, which can be time-consuming and error-prone. Given the chore that creating and maintaining documentation can be its surprising that its not a built in feature of Terraform and that there is only one (that I've come across) such tool Terraform docs, https://github.com/terraform-docs/terraform-docs/
As a Bicep user, it would be incredibly helpful if there was a similar documentation generator. This would allow you to automatically generate documentation from your Bicep code, saving you time and ensuring that your documentation is always up to date and accurate.
There are many benefits to having a Bicep documentation generator, including:
Increased productivity: Generating documentation automatically from your Bicep code would save you time and increase productivity, allowing you to focus on other important tasks.
Accuracy: Manually creating documentation can lead to errors, which can cause confusion and problems down the line. Automatic documentation generation from your Bicep code ensures that your documentation is always accurate and up to date.
Readability: Bicep code is designed to be concise and readable, and there would be a visible one to one correlation between the generated documentation and the code opening up a wider audience to Bicep.
Consistency: Automatic documentation generation ensures that documentation is consistent across different projects and teams, making it easier to collaborate and share knowledge.
Onboarding: New team members can quickly get up to speed with the infrastructure by reviewing the automatically generated documentation, which would help them understand how everything fits together.
Since there isn't a native tool not all of the advantages are lost, there is a workaround. Bicep generates ARM as intermediate step and that allows it to use a lot of ARM template tools. We can use PSDocs.Azure.
PSDocs.Azure
PSDocs.Azure is part of the open-source PSDocs project from Microsoft. PSDocs is a PowerShell module that generates documentation from various sources, including ARM templates. It generates documentation in multiple formats, including Markdown, HTML, and PDF, and it provides a lot of flexibility when it comes to customizing the output.
PSDocs.Azure generates documentation from metadata property in an ARM template.
As its documentation states
a metadata property can be added in most places throughout the template. For example:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"metadata": {
"name": "Storage Account",
"description": "Create or update a Storage Account."
},
"parameters": {
"storageAccountName": {
"type": "string",
"metadata": {
"description": "The name of the Storage Account."
}
},
"tags": {
"type": "object",
"metadata": {
"description": "Tags to apply to the resource.",
"example": {
"service": "<service_name>",
"env": "prod"
}
}
}
},
"resources": [
],
"outputs": {
"resourceId": {
"type": "string",
"value": "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]",
"metadata": {
"description": "A unique resource identifier for the storage account."
}
}
}
}
And helpfully, Bicep's @description decorator produces a metadata tag in the ARM template.
This
@description('Specifies the Azure location where the key vault should be created.')
param location string = resourceGroup().location
Generates this
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Specifies the Azure location where the key vault should be created."
}
}
However, the @description decorator is limited to parameters. It can be applied to any part of Bicep file and it will deploy as expected.
@description('Specifies the Azure location where the key vault should be created.')
param location string = resourceGroup().location
@description('A description of the expected file content here.')
var myFile = loadJsonContent('my-file-with-data.json')
@description('Further description of how the resource and how the file is used here.')
resource newResource 'Vendor.SomeNamespace/ResourceType@202x-01-01' = {
But it will only generate a metadata property for the parameter.
In conclusion, as a Bicep user, having a built-in documentation generator would be a valuable addition to the Bicep toolset. Extending the existing build function will help to utilise currently available tools. As Bicep continues to gain popularity, its important that it keeps up with other infrastructure as code tools, such as Terraform's documentation generator and it can be done without having to invest in completely new tools..
Comments