From 036e2fa6842e6515fcc2a440b6375b36177465b7 Mon Sep 17 00:00:00 2001 From: Patrick Chugh Date: Sun, 4 Oct 2026 21:52:31 +0100 Subject: [PATCH] Document drawing environments you have no access to TerraVision plans Terraform against empty local state, so it draws what the code plus a variables file would deploy, for an account the reader cannot log in to or one that does not exist yet. The scanner comparison and two new FAQ questions say so, with the exact --varfile command and the real requirements: Terraform, Graphviz and credentials the provider accepts, but no access to the target account or its state. Co-Authored-By: Claude Fable 5.1 --- docs/alternatives.md | 4 +++- docs/faq.md | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/alternatives.md b/docs/alternatives.md index fe56888f..323a0225 100644 --- a/docs/alternatives.md +++ b/docs/alternatives.md @@ -43,7 +43,9 @@ Diagrams is a Python library: you write a script that declares each node, cluste ## TerraVision vs live cloud scanners (Hava, Cloudviz, Holori) -Live scanners connect to your cloud accounts with read-only access and draw what is deployed, including drift and resources created by hand. They are hosted, commercial services. TerraVision draws the desired state from code, needs no access to your cloud account, and works before anything is deployed. Use a scanner to audit what is running; use TerraVision for design reviews, pull requests and documentation that follows the code. +Live scanners connect to your cloud accounts with read-only access and draw what is deployed, including drift and resources created by hand. They are hosted, commercial services. TerraVision draws the desired state from code, needs no access to the account it draws, and works before anything is deployed. Use a scanner to audit what is running; use TerraVision for design reviews, pull requests and documentation that follows the code. + +A scanner can only draw an account it has been given access to. TerraVision draws from the code plus a variables file, so it can draw production for engineers who are not given production access, and it can draw an environment that does not exist yet: pass `--varfile prod.tfvars` and it shows what the code would deploy there. ## TerraVision vs `terraform graph` diff --git a/docs/faq.md b/docs/faq.md index 23e0a0e9..35bf0e2f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -103,6 +103,24 @@ The graph is built from `terraform plan` output, which represents the *desired* --- +### Can I draw an environment I don't have access to? + +Yes. TerraVision draws from the Terraform code and a variables file, not from a live account or its state. It plans the code against empty local state, so the diagram shows what the code would deploy. You need Terraform, Graphviz and credentials the provider accepts, but no access to the target account or its state. + +```bash +terravision draw --source ./infra --varfile prod.tfvars --outfile architecture-prod +``` + +Any valid credentials for the provider will do, because Terraform only validates them before planning. The exception is a data source that reads from the target account, such as a lookup of an existing VPC by id; that needs access to whatever it reads. Pass `--varfile` more than once to layer files, or `--workspace` to select a Terraform workspace. + +--- + +### Can I draw dev and prod from the same code? + +Yes, in the same way: one variables file per environment, one diagram each. Pass `dev.tfvars` for one run and `prod.tfvars` for the other, with different `--outfile` names, and compare the two diagrams. + +--- + ## Output and Customization ### What output formats are supported?