This week, I met with one of our partners, and my good friend Rik Hepworth asked a great question. This was:
“Mike, we really like Azure Documenter in Turbo360, but what would be awesome is if I can generate the documentation from a DevOps pipeline so each time we deploy updates to Azure, we can regenerate the documentation”
In this article, we will look at how to do it.
Setup Document
First off, I have set up a document that can be generated with the right configuration. In this case, I am using the Azure Resource Details document type shown below.
As a side note, you can use any document in this approach, but in Azure Documenter, we have a feature that allows you to schedule the document generation, which will cover a lot of your needs and the one I think you most likely to want to trigger from a pipeline is the resource details.
When you set up your document, you can provide filters to focus on the resources. It will generate a document around. Maybe you will use specific resource groups or specific tags, as shown below.
Get API Key
Next, you will need to create an API key, which you do in the settings section of Turbo360. You will need your key to have access to Azure Documenter.
Script to Generate Document
In order to generate the document from a pipeline, we will need to call the Turbo360 API, and there are two operations we need:
- GetDocumentConfigurations
- GenerateDocument
Using get document configurations, we will use the name of the document, and we will look up the ID and document type for the document we want to trigger.
We will then call the GenerateDocument operation, passing in those parameters.
The below Powershell script shows you how to do this.
$documentName = "Your document name here"
$apiKey = ""
$baseUrl = "https://portal.turbo360.com/AzureDocumenter/"
# Define any headers you might need (optional)
$headers = @{
"APIKey" = $apiKey
"Content-Type" = "application/json"
}
# Call Get Document Configurations to find the document
$url = $baseUrl + "GetDocumentConfigurations"
$documentConfigurationResponse = Invoke-RestMethod -Uri $url -Method GET -Headers $headers
Write-Host $documentConfigurationResponse
$id = ""
$documentType = ""
# Iterate through each object in the JSON array
foreach ($item in $documentConfigurationResponse) {
if ($item.name -eq $documentName) {
$id = $item.id
$documentType = $item.documentType
# Output the id and documentType
Write-Host "Found matching object:"
Write-Host "ID: $id"
Write-Host "Document Type: $documentType"
# Break the loop once a matching object is found
break
}
}
# Trigger the Generation of the document
$url = $baseUrl + "GenerateDocument"
$body = @{
"id" = $id
"documentType" = $documentType
} | ConvertTo-Json
$documentGenerateResponse = Invoke-RestMethod -Uri $url -Method POST -Headers $headers -Body $body
Write-Host $documentGenerateResponse
Azure DevOps Pipeline
Next, we need to use this PowerShell script in an Azure DevOps Pipeline. In the pipeline, I will probably hold the API key as a variable or get it from Key Vault.
Below you can see I added a PowerShell task to the pipeline, and I have just used the script from the above section but with one modification, as shown below, to get the API key from a variable.
This pipeline is very simple and just triggers the document. In your pipeline, you are probably doing a lot more work to deploy the application, but you could just add the Powershell task to the end of your pipeline.
Below, you can see where the pipeline ran, and it triggered my document to be generated. Turbo360 will now generate a new version of this document, which can be accessed from Turbo360, or you can make it publish the document to an Azure Storage Account that you provide.
I can now download the document from Turbo360 and see my updated Resource Details document.
We hope this gives you some good options to connect our documentation features to your DevOps process, creating good governance options for your solutions.
