Terraform provider
How to draw your infrastructure as code with the Plotwork provider for Terraform and OpenTofu, so the diagram changes on every apply. It is for platform engineers and architects who want diagrams that follow the infrastructure without a separate CI job.
TL;DR
| Question | Answer |
|---|---|
| What is it? | The provider plotwork-official/plotwork. The diagram is part of the configuration, so an apply that changes the infrastructure changes the picture. |
| What does it give me? | plotwork_import turns files into diagram source, plotwork_render turns source into an SVG, and plotwork_diagram publishes it to your library or your organisation's. |
| Where can the SVG go? | Anywhere a Terraform resource can write: aws_s3_object, azurerm_storage_blob, google_storage_bucket_object, local_file. |
| Which plan? | plotwork_import and plotwork_render need Pro or above. plotwork_diagram publishes on every plan. |
| How does it sign in? | An API key in PLOTWORK_API_KEY: a personal key, or an organisation key from Keys and CI. |
| Does it work with OpenTofu? | Yes. The tests run on Terraform 1.9 and later and on OpenTofu. |
| What leaves my machine? | The files you pass plotwork_import, and diagram source. Nothing is stored unless plotwork_diagram publishes it. |
| Where is the code? | plotwork-official/terraform-provider-plotwork (opens in a new tab), MIT licensed. |
1. Install and sign in
terraform { required_providers { plotwork = { source = "plotwork-official/plotwork" version = "~> 0.1" } }}
provider "plotwork" {}export PLOTWORK_API_KEY="pw_..."export PLOTWORK_ORG="acme" # only to publish to an organisation's library| Variable | Argument | What |
|---|---|---|
PLOTWORK_API_KEY | api_key | A personal key from API keys, or an organisation key from Keys and CI |
PLOTWORK_ORG | organization | The organisation plotwork_diagram publishes to. Needed with an organisation key |
PLOTWORK_API_URL | api_url | Another API address, such as a preview environment |
2. Draw the configuration into your own storage
plotwork_import reads every format importing from code and data lists. Pass a module's files and write the SVG wherever the team reads it:
data "plotwork_import" "network" { format = "terraform" files = { for f in fileset(path.module, "*.tf") : f => file("${path.module}/${f}") }}
data "plotwork_render" "network" { source = data.plotwork_import.network.source scheme = "auto"}
resource "aws_s3_object" "network" { bucket = "acme-architecture" key = "diagrams/network.svg" content = data.plotwork_render.network.svg content_type = "image/svg+xml"}coverage and warnings on plotwork_import say what the diagram left out.
3. Draw live values from module outputs
Write the diagram yourself and fill it with what the apply produced. Terraform publishes it after the resources it reads, and again when one of their values changes:
resource "plotwork_diagram" "network" { name = "prod network" alias = "prod-network" source = templatefile("${path.module}/network.diagram.tftpl", { vpc_cidr = aws_vpc.main.cidr_block lb_dns_name = aws_lb.app.dns_name })}The repository's examples/complete folder has a whole stack with its template.
4. Publish and keep a stable link
| Argument | What it does |
|---|---|
organization | Publishes to that organisation's private library. Members open it with view_url. |
alias | A stable link in your own library. stable_url never changes and shows the latest picture. |
folder, name | Where and under what label it is filed. |
classification | public, internal or confidential, for an organisation's diagram. |
A change to the source publishes a new diagram, then deletes the one it replaced, so the library does not fill up with old versions. A diagram deleted in the portal, or expired by the plan, is published again by the next apply. terraform destroy deletes it.
5. Choose between the provider and CI
| You want | Use |
|---|---|
| The diagram to follow each apply, in the same run | The provider |
| A pull request to fail when committed diagrams drift | The GitHub Action |
| Diagrams made from many repositories, in one place | Diagrams as code |
See also
| Page | Why |
|---|---|
| Importing from code and data | Every format plotwork_import reads |
| Hosted diagrams | Links, stable links and how long diagrams are kept |
| Keep diagrams in sync in CI | The pull request check |
| Writing diagrams | The language for a hand-written template |