DEV Community

Cover image for ARM template to architecture diagram from a GitHub URL
Cloudeval AI profile image Prateek Singh
Prateek Singh for Cloudeval AI

Posted on Originally published at cloudeval.ai

ARM template to architecture diagram from a GitHub URL

#azure #architecture #devops #github

TL;DR: To turn a GitHub-hosted ARM template into an architecture diagram, keep the URL path and swap github.com for cloudeval.ai. Cloudeval reads the ARM JSON, looks for a matching parameters file, creates a project and opens architecture and dependency views. No Azure credentials are needed. Compile Bicep to ARM JSON first.

By Prateek Singh, founder of Ganak AI Labs. Updated 6 October 2026.

Someone drops a link in the channel: "Can we use this Quick Start template for the new environment?" It points to an azuredeploy.json on GitHub.

You open it and get about 250 lines of nested JSON. Variables build resource IDs, dependsOn arrays pile up, and a public IP is easy to miss.

Before anyone deploys, you need to know what the template builds and how it's wired. A diagram answers that faster than a read-through. Here's the shortest path from a GitHub URL to one: a one-word change in the address bar.

Disclosure: I'm the founder of Cloudeval.

Key terms used below

  • ARM template: an Azure Resource Manager (ARM) JSON file that declares the resources Azure deploys.
  • Azure Quick Start Templates: Microsoft's public sample repository of ARM templates, Azure/azure-quickstart-templates on GitHub.
  • Architecture view and dependency view: two Cloudeval diagram layouts. The first shows what exists. The second shows what depends on what.

Why is an ARM template hard to review as raw JSON?

ARM JSON is written for Resource Manager, not for people. The architecture is spread across resources, parameters, variables, nested deployments and implicit relationships.

You only see the shape of the system once you've resolved all of that in your head.

A diagram gives reviewers a shared picture first. It should tell you:

  • what resources the template creates
  • which services depend on each other
  • whether the network shape matches what you expected
  • whether public-facing resources stand out
  • whether the template should be split up

How do I turn a GitHub ARM template URL into a diagram?

  1. Pick a public or accessible ARM JSON template on GitHub.
  2. Swap github.com for cloudeval.ai in the URL and press Enter.
  3. Check the detected parameters file, then choose Review & Create.
  4. Read the architecture view, then the dependency view.
  5. Run reports, or script the same flow with the CLI.

Step 1: Pick a GitHub-hosted ARM JSON template

The shortcut works on ARM JSON that Cloudeval can read from GitHub. blob, tree and raw GitHub URLs all work when they point to a supported template (GitHub URL guide).

This walkthrough uses a Quick Start that deploys one VM with two NICs in a virtual network:

https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json
Enter fullscreen mode Exit fullscreen mode

It creates a virtual machine, a storage account, two network interfaces, a public IP address, a virtual network and two network security groups. That's small enough to check against the diagram by eye.

Working in Bicep? Compile it first with az bicep build --file main.bicep and use the generated ARM JSON. Cloudeval reads Bicep compiled to ARM JSON, not .bicep files.

Step 2: Swap github.com for cloudeval.ai

Keep everything after the host exactly as it is. Change only the domain:

https://cloudeval.ai/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json
Enter fullscreen mode Exit fullscreen mode

Press Enter. Cloudeval opens Quick Project Creation with the GitHub URL already filled in.

You need to be signed in to Cloudeval. You don't need an Azure subscription.

Cloudeval Quick Project Creation dialog importing an Azure Quick Start ARM template after github.com was changed to cloudeval.ai
Quick Project Creation picks up the URL and starts the import.

Step 3: Check the parameters file and create the project

Many templates need a parameters file. When the URL follows a common naming pattern, Cloudeval looks for a matching one in the same repository.

You'll see Looking..., Found or Not found beside the parameters field. If it picks the wrong file, paste the right parameters URL.

Confirm the project name, provider and URLs, then choose Review & Create. Cloudeval creates the project and opens the workspace. If setup is still running, let it finish before you run reports or share the project.

Step 4: Read the architecture view, then the dependency view

Start with the architecture view. It answers "what exists?": resource groups, major resources, service boundaries and topology.

Check it against the template. For this Quick Start, you should find the VM, both NICs, the public IP and the two network security groups.

Cloudeval architecture diagram of an Azure template with a network interface selected and its problems panel listing a public IP attached
Select a resource to see its properties and findings beside the graph.

Switch to the dependency view when relationships matter. It shows upstream and downstream resources, paths that widen the blast radius, and where the declared topology differs from what you expected.

The two views answer different questions, so use both.

Here's a 30-second look at how the diagrams are laid out:

Step 5: Run reports, or script the same flow

The URL only creates the project. Run reports from the workspace once import is done. The Architecture & Dependencies tab ties each finding to its dependency context and affected resources.

Cloudeval Architecture and Dependencies report tab for an Azure project showing nodes, mapped findings, critical paths and an architecture evidence map
Findings mapped to dependency context and affected resources.

Prefer the terminal? The CLI takes the same GitHub URL:

npm install -g @ganakailabs/cloudeval-cli   # Node.js 20+
cloudeval login

cloudeval projects create \
  --template-url https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.compute/1vm-2nics-2subnets-1vnet/azuredeploy.json \
  --name "Quick Start: 1 VM, 2 NICs" \
  --provider azure \
  --format json \
  --output ./cloudeval-project.json

PROJECT_ID=$(jq -r '.data.project.id' ./cloudeval-project.json)

cloudeval projects export-diagram "$PROJECT_ID" \
  --layout dependency --format svg --output dependency.svg --non-interactive
Enter fullscreen mode Exit fullscreen mode

export-diagram takes --layout architecture|dependency and --format png|jpeg|svg. That's handy for a design doc or a PR description.

When should you use repository sync or upload instead?

The URL swap is built for speed on a single template. Pick another path when the source is more complicated:

Situation Use Why
One public ARM JSON file GitHub URL swap Fastest browser path, with parameters detection
Linked or nested templates (templateLink) Workspace import with .cloudeval/config.yaml Resolves relative linked files from an entry template
Private repo, branch history, refresh on push GitHub repository sync (Cloudeval GitHub App) Keeps commit and branch context on the project
Template built locally or not reachable by URL Local upload Nothing has to be public

All the options are in Import an ARM or Bicep template.

Is a generated diagram enough to approve a template?

No. A diagram shows what the template declares. It doesn't prove what happens at deployment or at runtime.

Microsoft's own tools still matter. The Bicep extension for VS Code has a built-in visualizer for a quick look while editing. az deployment group what-if is still the real answer to "what will change in this subscription?"

What the URL flow adds is speed and a shareable review for templates you didn't write. There's no download and no Azure access, and the same project holds reports, findings and exports.

Findings draw on 1,650+ checks. Not every project runs every check, and unsupported areas show as "Not assessed" instead of passing.

It doesn't deploy anything, read your live subscription (that's a separate Cloud sync) or test routing and access in a deployed environment.

Frequently asked questions

How do I convert an ARM template to an architecture diagram?

Import the ARM JSON into a Cloudeval Azure project, by upload or by GitHub URL, and open the architecture view. For a GitHub-hosted template, the quickest way is to replace github.com with cloudeval.ai in the URL and press Enter.

Is there an Azure ARM template visualizer that works from a URL?

Yes. Cloudeval accepts blob, tree and raw GitHub URLs that point to supported ARM JSON, and the cloudeval.ai host swap opens the import directly. For Bicep files open in VS Code, Microsoft's Bicep visualizer is the built-in option.

Do I need a live Azure connection?

No. You need a Cloudeval account to create the project, but ARM template import doesn't need Azure credentials. Live Cloud sync is a separate workflow.

Does importing the template deploy Azure resources?

No. Importing creates a Cloudeval project so you can review the template. Deploying Azure resources is a separate step that you run yourself.

Can I use Bicep directly?

Not in this workflow. Compile Bicep to ARM JSON first with az bicep build, then import the generated file with any parameters and linked files the project needs.

Takeaway

When someone shares an ARM template on GitHub, change one word in the URL and look at the dependency view before you read the JSON. It gives the team a picture to argue about. Then run what-if before you deploy.

For the full reference answer, see How do I convert an ARM template to an architecture diagram?

Related on cloudeval.ai

Try it

Take any ARM template URL on GitHub, swap github.com for cloudeval.ai, and open the dependency view. Start in the Cloudeval app and follow the GitHub URL guide.

About the author

Prateek Singh is the founder of Ganak AI Labs and builds Cloudeval AI.

cloudeval.ai | Docs | YouTube | GitHub | LinkedIn

Top comments (0)