# Terraform provider

> Page: https://docs.plotwork.dev/terraform-provider. Index of every page: https://docs.plotwork.dev/llms.txt

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](https://github.com/plotwork-official/terraform-provider-plotwork), MIT licensed. |

## 1. Install and sign in

```hcl
terraform {
  required_providers {
    plotwork = {
      source  = "plotwork-official/plotwork"
      version = "~> 0.1"
    }
  }
}

provider "plotwork" {}
```

```shell
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](https://docs.plotwork.dev/importing-from-code-and-data.md) lists. Pass a module's files and write the SVG wherever the team reads it:

```hcl
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:

```hcl
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](https://docs.plotwork.dev/diagrams-in-ci.md) |
| Diagrams made from many repositories, in one place | [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md) |

## See also

| Page | Why |
|---|---|
| [Importing from code and data](https://docs.plotwork.dev/importing-from-code-and-data.md) | Every format `plotwork_import` reads |
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Links, stable links and how long diagrams are kept |
| [Keep diagrams in sync in CI](https://docs.plotwork.dev/diagrams-in-ci.md) | The pull request check |
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The language for a hand-written template |