Skip to content

Latest commit

 

History

History
126 lines (94 loc) · 6.72 KB

github.md

File metadata and controls

126 lines (94 loc) · 6.72 KB

Configure and run Azure Governance Visualizer from GitHub

GitHub can be used to orchestrate regular execution of Azure Governance Visualizer against your target management group. This allows headless, automated execution along with the ability to set least privileges on the executing account. It uses GitHub actions as the workflow orchestrator. These instructions will get you up and running from GitHub.

Prerequisites

  • A GitHub organization in which you have enough permissions to create a repository.

1. Create GitHub repository

  1. Go to https://github.com/new/import?visibility=private to start the repository creation process.
  2. Use 'https://github.com/JulianHayward/Azure-MG-Sub-Governance-Reporting.git' as the clone URL.
  3. Select your existing GitHub organization.
  4. Select 'Private'
  5. Click on 'Begin import'
  6. Navigate to your newly created repository

If you'd instead like to perform this from the GitHub CLI, see gh repo create for instructions.

2. Create and configure a service principal

For GitHub actions to authenticate and connect to Azure you need to create a service principal. This will allow the Azure Governance Visualizer scripts to connect to Azure resources and Microsoft Graph with a properly permissioned identity.

There are a few options to create the service principal, both will result in least privilege access:

Option 1 - Use workload identity federation (recommended)

This option uses Microsoft Entra workload identity federation to manage a service principal you create but without also the need for you to manage secrets or secret expiration. This process uses the OIDC (OpenID Connect) feature of GitHub workflows. This process uses the .github/workflows/AzGovViz_OIDC.yml workflow file and is the recommended method.

  1. Navigate to the Microsoft Entra admin center
  2. Click on 'App registrations'
  3. Click on 'New registration'
  4. Name your application (e.g. 'AzureGovernanceVisualizer_SC')
  5. Click 'Register'
  6. Your App registration has been created, in the 'Overview' copy the 'Application (client) ID' as we will need it later to setup the connection
  7. Under 'Manage' click on 'Certificates & Secrets'
  8. Click on 'Federated credentials'
  9. Click 'Add credential'
  10. Select Federation credential scenario 'GitHub Actions deploying Azure Resources'
  11. Fill the field 'Organization' with your GitHub Organization name
  12. Fill the field 'Repository' with your GitHub repository name
  13. For the entity type select 'Branch'
  14. Fill the field 'GitHub branch name' with your branch name (default is 'master' if you imported the Azure Governance Visualizer repository)
  15. Fill the field 'Name' with a name (e.g. AzureGovernanceVisualizer_GitHub_Actions)
  16. Click 'Add'

Store the service principal configuration in GitHub

  1. In the GitHub repository, navigate to 'Settings'
  2. Click on 'Secrets'
  3. Click on 'Actions'
  4. Click 'New repository secret'
  5. Create the following three secrets:
    • Name: CLIENT_ID Value: Application (client) ID (GUID)
    • Name: TENANT_ID Value: Tenant ID (GUID)
    • Name: SUBSCRIPTION_ID Value: Subscription ID (GUID)

Option 2 - Create and manage a service principal

This other option has you creating a service principal and requires you to manage secrets and secret expiration for that service principal. This process uses the .github/workflows/AzGovViz.yml workflow file.

  1. Navigate to the Microsoft Entra admin center
  2. Click on 'App registrations'
  3. Name your application (e.g. 'AzureGovernanceVisualizer_SC')
  4. Click 'Register'
  5. Your App registration has been created, in the 'Overview' copy the 'Application (client) ID' as we will need it later to setup the secrets in GitHub
  6. Under 'Manage' click on 'Certificates & Secrets'
  7. Click on 'New client secret'
  8. Provide a good description and choose the expiry time based on your need and click 'Add'
  9. A new client secret has been created, copy the secret's value as we will need it later to setup the secrets in GitHub

Store the newly created credentials in GitHub

  1. In the GitHub repository, navigate to 'Settings'
  2. Click on 'Secrets'
  3. Click on 'Actions'
  4. Click 'New repository secret'

    • Name: CREDS

    • Value:

      {
   "tenantId": "<GUID>",
   "subscriptionId": "<GUID>",
   "clientId": "<GUID>",
   "clientSecret": "<GUID>"
}

3. Set GitHub workflow permissions

  1. In the GitHub repository, navigate to 'Settings'
  2. Click on 'Actions'
  3. Click on 'General'
  4. Under 'Workflow permissions' select 'Read and write permissions'
  5. Click 'Save'

4. Configure the workflow YAML file

  1. In the folder ./github/workflows edit the appropriate YAML file based on your choice in Step 2
  2. In the env section enter your target Azure management group ID
  3. If you want to continuously run Azure Governance Visualizer then enable the schedule in the on section

5. Run Azure Governance Visualizer in GitHub actions

  1. In the GitHub repository, navigate to 'Actions'
  2. Click 'Enable GitHub Actions on this repository'
  3. Select the configured Azure Governance Visualizer workflow file
  4. Click 'Run workflow'

6. Publish the Azure Governance Visualizer HTML to a Azure Web App (Optional)

There are instances where you may want to publish the HTML output to a webapp so that anybody in the business can see up to date status of the Azure governance. The instructions for this can be found in the Azure Governance Visualizer accelerator repo.

Next steps

For report hosting, consider using the Azure Governance Visualizer accelerator which will give you an example on how to host the output on Azure Web Apps in conjunction with this GitHub automation.