Azure Gather Script Instructions

This guide will walk through the requirements and steps to successfully generate documentation using Documentation as a Service.

Pre-Requesites

  • Powershell version 5.1 (version 7.1 or newer preferred)
  • Az Powershell module
    • https://docs.microsoft.com/en-us/powershell/azure/install-az-ps
  • Az.ResourceGraph module
    • Command: "Install-Module -Name Az.ResourceGraph -Scope CurrentUser -Repository PSGallery -Force"
  • Internet Connectivity
  • Read access or higher to an Azure environment

Downloading the latest Gather Script

  • Open a Browser and navigate to https://DocumentationAsCode.com
  • Log in with your Softchoice account
  • On the services dashboard, under Documentation as Code, select Azure
  • Click the link to download the latest version of the gather script, it will be a zip folder
  • Open your downloads folder and extract the file in the Get-AzureResources.zip to a new folder on your C: drive
    • Make sure to save the gather script somewhere you can find it later on your computer

Running the gather script

  • Browse to where you saved the gather script
  • Right-click on the file and select "Run with Powershell", If you don't have this prompt, open the file with PowerShell ISE and run the script
    • If you get a security warning, click open. Optionally, you can uncheck the "Always ask before opening this file" box to ignore this warning in the future
  • The script will prompt you for credentials, use the Azure account that has access to the environment you want to document
  • The script will start searching for Azure Tenants that you have access to. After a minute, a new GUI window will open asking you to select the tenant that you want documented. Select the tenant and press the "Select Tenant" button.
    • You will get a second authentication pop-up if your identity has access to more than one tenant. This is to refresh your token to see all subscriptions.
  • The GUI will open a second window which will list all the available subscriptions within the selected tenant.
    • Note: You can select more than one subscription by using the checkbox at the top
  • Once you have selected your subscription(s), click "Go!" in the bottom right corner, closing the GUI.
  • The original PowerShell window will start reading through the environment collecting information from the Azure resources, then save the output JSON file in the same folder as the gather script
    • Note: The script will remind you where the file is saved at to help find it easier
  • Press Enter when prompted, which will close the PowerShell window

  • Navigate to the folder where you saved the gather script and locate the JSON file

    • Note: The name of the JSON file will be your subscription's ID, along with the name of the subscription and the timestamp of when the information was gathered.

    GUI

Generating Documentation

  • Return to https://DocumentationAsCode.com
  • Login with your Softchoice account
  • On the services dashboard, under Documentation as Code, select Azure
  • Under Generate Reports:
    • Enter the customer's name
    • Enter your name
    • Choose the type of document(s) you want to generate. The options are:
      1. Word
      2. Visio
      3. Network Visio
      4. Diagram.io
    • Click the "Browse" button and navigate to the JSON file that the script created. It will be in the same folder as the gather script unless you moved it somewhere else
  • Click Generate Document
  • You'll see a notification that the file has been uploaded and will be delivered shortly
  • Check your email for the documentation, coming from dac@softchoice.com
    • Note: Check your Other or Junk folders if you do not recieve your document within 5 minutes
  • Click the Download Document button in the email to download your documentation

Common Errors/Issues

  • Login-AzAccount is not recognized as the name of a cmdlet
    • Open PowerShell as an Administrator and run "Install-Module Az -force", then select "Yes to All [A]"
  • WARNING: Unable to aquire token for tenant
    • These can be ignored unless one of the tenants is the one you are trying to document.
      1. Open up Powershell and type "Clear-AzContext", and choose "Yes"
    • If that doesn't work:
      1. Open up Powershell and manually log in using "Login-AzAccount -tenantid "
      2. Type cd , press enter
      3. type ".\Get-AzureResources.ps1", press enter
  • Subscription(s) not showing up in the GUI
    • Validate you have at least Reader access to the subscription.
    • Verify in the Powershell terminal that you successfully logged into the customer's tenant and there was no missing tokens for that tenant ID.
  • Not prompting for credentials/frozen/hanging
    • Check to see if the login screen is hidden behind other open windows

Diagram.io (Diagrams.net) document release notes

release 0.4.0

  • Added support for below resources:
    • VWAN
    • Azure Firewalls
    • VPN Sites
    • VPN Gateways
    • ExpressRoute Gateways
  • Fixed distance between Azure-Hierarchy subscriptions
  • New Azure Icons!

release 0.3.0

  • Added brackets to organize resource groups.

release 0.2.0

  • Added Azure hierarchy diagram (Beta) on page 2. Below Items supported
    • Management Groups
    • Subscriptions
    • Resource Groups

release 0.1.0

  • Draws network diagram. Below resources supported
    • Vnets
    • Vnet peers
    • Subnets
    • Virtual Network Gateways
    • Expressroute Circuits
    • Expressroute Connections
    • Local Gateways
    • Ipsec connections