Try for free Book a demo

Generating Azure documentation from an Azure DevOps Pipeline

Azure Documenter

4 Mins Read | Last modified on July 22nd, 2024

Generating Azure document from an Azure DevOps Pipeline featured image

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.

Azure documentation generation from Azure DevOps Pipeline

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.

Azure Resource Details document type

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.

Specific resource groups or specific tags

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.

Get API Key

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.

Trigger Document Generation

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.

Publish the document to an Azure Storage Account

I can now download the document from Turbo360 and see my updated Resource Details document.

Turbo360 Azure Documentation

We hope this gives you some good options to connect our documentation features to your DevOps process, creating good governance options for your solutions.

Related Reading

This article was originally published on Feb 20, 2024. It was most recently updated on Jul 22, 2024.

Related Articles