Skip to content

quickstart.md

Latest commit

 

History

History
124 lines (96 loc) · 5.94 KB

quickstart.md

File metadata and controls

124 lines (96 loc) · 5.94 KB
Raw
title Quickstart
description Open a sample Form in the Explorer, find one resource, and read the evidence behind its placement, then run the same analysis on your machine.

Open a synthetic Azure commerce platform of 97 planned resources in the Explorer, find one resource, and read the evidence behind its placement. The first half needs only a browser; the second half installs Rootform and produces the same result on your machine.

Rootform turns a Terraform or OpenTofu plan, or a state export, into a Form: a portable saved result you can explore, explain, compare, and check. The Explorer is the Form's interactive view. Nothing here runs Terraform, since the sample plan is already exported.

Open the sample Form

Open the Playground and keep Commerce platform with Plan selected. The canvas shows the top level of the planned architecture: four resource groups, the relations between them, and a few resources that no group holds.

The Explorer at the top level of the commerce platform plan: four resource group blocks with their object counts, relation labels such as Peers with and Delivers to, and the Planned changes selector The Explorer at the top level of the commerce platform plan: four resource group blocks with their object counts, relation labels such as Peers with and Delivers to, and the Planned changes selector

The selector at the top left reads Planned changes, Refreshed to Planned: this plan was made against the infrastructure the state already holds, so it shows what the proposal adds, removes, or replaces on top of it. The counters at the bottom read the added, removed, changed, and indeterminate entries.

Find one resource

Press Search (⌘K on macOS, Ctrl+K elsewhere) and type prod_data. The first result is the subnet azurerm_subnet.prod_data with its path prod / prod: resource group prod, virtual network prod. Choose it, and the Explorer opens the virtual network that holds the subnet. Select the prod_data card to open the Inspector on the right.

Read why it is placed there

In Details, Contexts lists two placements: Ownership in resource group prod and Network in VNet prod. Incoming contexts lists the four private endpoints placed in this subnet; Scene members counts them.

Open the Evidence tab. Under Evidence, the entry azurerm_subnet.prod_data → azurerm_virtual_network.prod is the network placement. Expand its Resolution: it names the Rule azure.rule.subnet, the attribute it followed, source.virtual_network_name, and the kind of evidence that settled it. The resolved outcome establishes this placement.

The Evidence tab for azurerm_subnet.prod_data: evaluated value and verified traversal, the resolved outcome, and both placement closures with their candidate counts The Evidence tab for azurerm_subnet.prod_data: evaluated value and verified traversal, the resolved outcome, and both placement closures with their candidate counts

That one fact carries the whole idea. Rootform did not draw the subnet inside the VNet because Terraform references it: a Rule in the Azure Dialect declares what the reference means, and the plan evidence proved it. Trace a placement explains how producer references become architectural facts and what incomplete evidence changes.

Run the same analysis locally

Install Rootform, then download the two files that produced this Form: the plan JSON export and the saved plan it was exported from.

mkdir rootform-quickstart && cd rootform-quickstart
curl -fsSLO https://raw.githubusercontent.com/rootform-dev/rootform/v0.3.0/examples/playground/commerce-platform/head/plan.json
curl -fsSLO https://raw.githubusercontent.com/rootform-dev/rootform/v0.3.0/examples/playground/commerce-platform/head/plan.tfplan

Analyze the plan. Rootform reads both files, prints a summary, and opens the Explorer in your browser from a local server:

rootform run plan.json --plan-file plan.tfplan
�[1mPlan analyzed�[0m
�[2mEnrichment�[0m         Saved plan paired with this plan JSON (1 module)
�[2mStage�[0m              Planned
�[1m�[38;5;208mArchitecture�[0m
  �[2mInstances�[0m      97
  �[2mInterpreted�[0m    97
  �[2mContexts�[0m       110

The terminal also shows the Explorer address; press Ctrl+C when you are done. Enrichment records that the saved plan paired with the JSON export, which is how Rootform followed references whose values are unknown until apply. Instances counts the resource instances in the plan, and Interpreted counts those a Rule matched: all 97 here. The 110 contexts are placements like the one you just read.

Keep the Form

Write the Form to a file instead of serving it:

rootform run plan.json --plan-file plan.tfplan --no-serve -o analysis.json
�[2mWrote     �[0m analysis.json

analysis.json reopens with rootform run analysis.json without the plan files. Explain an architecture questions it from the terminal, Check a Form with Policies evaluates Policies against it, and Compare two Forms sets it against another revision. It holds no sensitive plan values, but it names resources and describes topology.

Next, move to your own files with Analyze your plan or state, or stay with this sample in Explore a Form.