Terraform in organisations

TL;DR

1. The shape of the setup

The platform team keeps the organisation's look in one root module, reviewed like the rest of the platform. Application teams keep their diagrams beside their own infrastructure and publish them to the library. Neither needs the other's key.

PictureSourceOutline

Keep the design resources in exactly one state. Two workspaces that both declare the brand, or the same icon name, undo each other's apply in turn.

2. Make the keys

1. In the portal, open the organisation and choose Keys and CI.
2. Create a key named for where it runs, such as terraform-design, and tick Brand, icons and patterns.
3. Create one key for each application pipeline, such as terraform-payments, with Diagrams ticked.
4. Copy each key into the secret store of the pipeline that uses it (section 5). An owner or admin can reveal a key again later.

An organisation key belongs to the organisation, not to the person who made it, so it keeps working when that person leaves. It acts only in its own organisation. The organisation holds at most ten active keys. A key belongs to one environment: a key made on the preview portal works with the beta provider's default API, and a production key needs api_url = "https://api.plotwork.dev".

3. Lay out the modules

platform-design/              # the design workspace, one per organisation  versions.tf  main.tf                     # brand, icons, patterns  icons/    payments-api.svg    ledger.svg  patterns/    payments-service.pattern.json
payments/infra/               # an application stack  versions.tf  main.tf                     # the stack's own resources  diagrams.tf                 # plotwork_import and plotwork_diagram  network.diagram.tftpl

The design workspace:

1terraform {2  required_providers {3    plotwork = {4      source  = "plotwork-official/plotwork"5      version = "0.1.0-beta.2"6    }7  }8}9
10# Reads PLOTWORK_API_KEY: the design key.11provider "plotwork" {12  organization = "acme"13}14
15resource "plotwork_organization_brand" "this" {16  primary = "#2a78d6"17}18
19resource "plotwork_organization_icon" "this" {20  for_each = fileset("${path.module}/icons", "*.svg")21
22  name = trimsuffix(each.value, ".svg")23  svg  = file("${path.module}/icons/${each.value}")24}25
26resource "plotwork_pattern" "this" {27  for_each = fileset("${path.module}/patterns", "*.pattern.json")28
29  content = file("${path.module}/patterns/${each.value}")30}31
32output "icon_refs" {33  value = { for file, icon in plotwork_organization_icon.this : file => icon.ref }34}

An application stack:

1# Reads PLOTWORK_API_KEY: this stack's diagrams key.2provider "plotwork" {3  organization = "acme"4}5
6data "plotwork_import" "infra" {7  format = "terraform"8  files  = { for f in fileset(path.module, "*.tf") : f => file("${path.module}/${f}") }9}10
11resource "plotwork_diagram" "infra" {12  source         = data.plotwork_import.infra.source13  name           = "Payments infrastructure"14  folder         = "Payments/Infrastructure"15  classification = "internal"16}

A stack draws the organisation's icons by name, as icon=org:payments-api, in a hand-written template. It needs no reference to the design workspace's state: the name is the contract. Hosting custom icons for Terraform covers where the SVGs can live.

4. Names, folders and labels

5. Run it in CI

Set the key as the environment variable PLOTWORK_API_KEY, marked sensitive, in the system that runs the plan. Leave api_key out of the configuration, and never write a key in a .tfvars file that is committed. If a module takes the key as a variable, declare it sensitive = true.

GitHub Actions

1name: plotwork-design2
3on:4  pull_request:5  push:6    branches: [main]7
8permissions:9  contents: read10
11jobs:12  terraform:13    runs-on: ubuntu-latest14    env:15      PLOTWORK_API_KEY: ${{ secrets.PLOTWORK_DESIGN_KEY }}16      PLOTWORK_ORG: acme17    steps:18      - uses: actions/checkout@v719      - uses: hashicorp/setup-terraform@v420      - run: terraform init21      - run: terraform plan -out=tfplan22      - if: github.ref == 'refs/heads/main'23        run: terraform apply tfplan

For OpenTofu, use opentofu/setup-opentofu@v2 and tofu in place of terraform. Keep the secret in a protected environment when pull requests from forks can run the workflow.

HCP Terraform, Terraform Enterprise and Atlantis

6. Take over what is already there

An organisation that set its brand, icons or patterns in the portal can move them into code without deleting anything. Write the resources, then import each one:

1import {2  to = plotwork_organization_brand.this3  id = "acme"4}5
6import {7  to = plotwork_organization_icon.this["payments-api.svg"]8  id = "acme/payments-api"9}10
11import {12  to = plotwork_pattern.this["payments-service.pattern.json"]13  id = "acme/payments-service"14}

The command form works too: terraform import 'plotwork_organization_icon.this["payments-api.svg"]' acme/payments-api, or tofu import. Plotwork keeps a checked copy of an icon, not the file, so the first apply after importing an icon uploads the configured file once. Download the icons from the portal first if the repository does not have them yet.

7. Drift: the configuration wins

Terraform reads each resource on every plan. A change made outside it shows as drift, and the next apply puts the configuration back.

Tell admins that the design workspace owns the brand, icons and patterns, so a fix belongs in a pull request. On Pro and Enterprise the organisation's audit log records who saved or deleted each icon and pattern.

8. What each plan includes

An organisation has its owner's plan, and an organisation key is held to it. If the owner moves to Free, the brand and icons are kept but not drawn, and active on the brand turns false.

9. Best practices

10. Troubleshooting

See also