simenwo / bicep-module-library

This repository is used as part of my session at a Meetup with Global Azure Norway - Bergen

Bicep Module Library for Azure: Automated Documentation and Deployment

Info

This repository supports a session at Global Azure Norway - Bergen, demonstrating how to set up a web catalog for your Bicep registry. This setup facilitates easier access to code documentation and ensures documentation remains current by automating updates.

How it Works

Our solution consists of three main composite GitHub actions and one pipeline for building the catalog in an Azure Static Web App:

• lint-psrule: Lints Bicep modules and tests them with PsRule, assessing compliance with the Azure Well-Architected Framework (WAF).
• publish: Manages module versioning within the Azure Container Registry (ACR) and deploys the module.
• generate-docs: Automates the creation of Markdown files for documentation and creates pull requests with documentation updates.

When changes from the generate-docs are approved, it triggers the pipeline to update the Static Web App, ensuring the module library is current.

Set It Up Yourself

1. Set Up Your Azure Container Registry (ACR)

Start by establishing an Azure Container Registry (ACR) for your internal modules. You can easily establish this by following this Microsoft guide:

• Quickstart: Create a container registry using a Bicep file

Alternatively, you can use the code under /infrastructure and run the following command to execute the Bicep deployment:

az deployment sub create --location <YOUR-LOCATION> --name <YOUR-DEPLOYMENT-NAME> --template-file <BICEP-FILE> --parameters <PARAMETER-FILE>

To deploy a Bicep module to this ACR, run the following command (this is also handled by the first pipeline):

az bicep publish --target 'br:<ACRNAME>.azurecr.io/<REPONAME>:<VERSION>' --file <BICEP-FILE>

2. Create Your Modules

Create your Bicep modules under /modules. Resource modules should be placed in the /res folder, and pattern modules in the /ptn folder. Alongside each module, include a version.json file containing the version number of the module. The versioning starts at 0.1.0 and follows semantic versioning, updating only the MAJOR and MINOR versions when updating the module with breaking changes or new features. The PATCH number is automatically updated with each change.

{
    "version": {
        "major": 0,
        "minor": 1
    }
}

3. Create the pipeline for your module

Use the template pipeline to create the pipeline for your module and fill in the necessary inputs:

name: MODULE NAME CI/CD # Give your pipeline a name

paths:
    - <PATH_TO_YOUR_BICEP_FILE> # Trigger only on changes to the specified module path

MODULE_REPO_NAME: <REPOSITORYNAME_IN_ACR> #Choose appropriate name e.g module/res/keyvault
MODULE_FILE_PATH: <PATH_TO_YOUR_BICEP_FILE> # E.g 'modules/res/keyVault/deploy.bicep'
MODULE_VERSION_FILE_PATH: <PATH_TO_YOUR_VERSION_FILE> # E.g 'modules/res/keyVault/version.json'
MODULE_TEST_FILE_PATH: <PATH_TO_TEST_FILE> #E.g 'modules/res/keyVault/tests/default/main.test.bicep'
MODULE_REGISTRY_NAME: <NAME_OF_YOUR_ACR> 

The pipeline also uses federated credentials to sign in to Azure, so these need to be established. The secrets are then uploaded to GitHub secrets in the repository and used by the pipeline to sign in to Azure.

4. Create an Azure Static Web App for MKDOCS

The final step before you can run your pipelines is to create an Azure Static Web App for your module library. This can be done through the Azure portal or with Bicep.

After creating your Azure Static Web App, connect it to your repository. This will create a pipeline in your repository, which needs configuration to make the documentation automation work. The pipeline should have a name like azure-static-web-app-<some-autogenerated-name>.yml.

Configure the trigger of this pipeline to be on branch main and the path to be docs/. This ensures that the pipeline triggers every time there is a change in the docs folder.

on:
  push:
    branches:
      - main
    paths:
      - 'docs/*'

Add a step to build MKDocs before the "Build and Deploy" step:

      - name: Run MKbuild
        run: |
          pip install mkdocs-material
          mkdocs build

Set the app_location for MKDocs in the "Build and Deploy" step. The path is /site:

      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_POLITE_PLANT_0E4048A03 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/site/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "/" # Built app content directory - optional
          ###### End of Repository/Build Configurations ######

Before running the pipelines, ensure you have an mkdocs.yaml file at the root of your project. You can use the one in this repository and customize it to your liking. To learn more about the different features, visit MKDocs or Material for MKDocs.

5. Run the pipeline(s)

Congratulations! You should now be ready to run the pipeline(s). To activate the Bicep module pipeline, it needs to be placed under .github/workflows/. The pipeline for the Azure Static Web App should already be placed here automatically.