Best Practices

​

One owner per object

• Agree which product areas are code-managed and note it where admins will see it (a policy’s description or tags = ["terraform-managed"] work well).
• To reference portal-managed objects from Terraform without owning them, use the data sources: barndoor_mcp_server, barndoor_agent, barndoor_policy, barndoor_llm_provider, barndoor_dlp_detection_engine, plus catalog lookups barndoor_mcp_server_directory and barndoor_agent_directory.
• To take ownership of a portal-created object, import it (below) — from then on, hands off in the UI.

​

Secrets and state hygiene

• Supply client_secret via BARNDOOR_CLIENT_SECRET, never in configuration. In CI, use your platform’s secret store (see CI/CD).
• Mark your own secret inputs (api_key variables and the like) as sensitive = true.
• Barndoor’s write-only credential attributes (barndoor_llm_provider.api_key, MCP server OAuth secrets, log-export storage credentials such as S3 access keys and Azure account keys or SAS tokens) are stored in the platform’s secret store and never returned by the API — but the values you supplied still live in your Terraform state file. Treat state as secret: use a remote backend with encryption and restricted access.
• Rotate the provider credential on a schedule that fits your team. Rotation keeps the client ID and invalidates only the secret — update BARNDOOR_CLIENT_SECRET wherever it’s stored, and remember one credential is active per organization, so every pipeline shares it.

​

Pin the provider version

terraform {
  required_providers {
    barndoor = {
      source  = "barndoor-ai/barndoor"
      version = "~> 0.3"
    }
  }
}

​

Importing existing configuration

import {
  to = barndoor_policy.search_read_only
  id = "6f1c9312-8f3e-4bde-9c2b-b3a1d1cf34a4"
}

terraform plan -generate-config-out=generated.tf

• Write-only attributes come back empty. Credentials the platform never returns (OAuth secrets, API keys, log-export storage credentials) can’t be populated by import. The first plan after importing will propose re-sending any such values present in your configuration — that in-place update is expected and safe.
• Some resources only adopt via import. barndoor_idp, barndoor_dlp_field_control_policy, and live barndoor_llm_model_pricing rules deliberately refuse to create over an existing object, so out-of-band setup is never silently overwritten — the error message directs you to import instead.

​

Destroy is not always delete

​

Plans that look like drift but aren’t

• barndoor_llm_model_pricing.id changes on every price update — pricing is an append-only versioned store, and each change creates a new version. That’s by design, not drift.
• barndoor_llm_rate_limit: removing requests_per_minute or tokens_per_minute from configuration clears that metric on the platform — the plan is telling the truth; make sure it’s what you meant.
• After importing resources with write-only credentials, the first plan re-sends those values (see Importing).
• barndoor_notification_channel.signing_secret is never refreshed. The platform reveals a webhook channel’s signing secret exactly once, on creation or rotation, and cannot return it again — so state holds whatever was last issued to Terraform, and a plan will never show a difference even if the secret was rotated elsewhere. Rotate through rotate_when_changed (which rotates in place, preserving the channel) so Terraform stays the source of truth. On import the attribute is empty, because Terraform was not the recipient of the reveal; has_signing_secret still reports whether the platform holds one.

​

CI/CD with GitHub Actions

name: terraform
on:
  pull_request:
  push:
    branches: [main]

env:
  BARNDOOR_BASE_URL: https://platform.barndoor.ai
  BARNDOOR_TOKEN_URL: https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token
  BARNDOOR_CLIENT_ID: ${{ vars.BARNDOOR_CLIENT_ID }}
  BARNDOOR_ORGANIZATION_ID: ${{ vars.BARNDOOR_ORGANIZATION_ID }}
  BARNDOOR_CLIENT_SECRET: ${{ secrets.BARNDOOR_CLIENT_SECRET }}

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform plan -input=false
        if: github.event_name == 'pull_request'
      - run: terraform apply -input=false -auto-approve
        if: github.ref == 'refs/heads/main'

• Only BARNDOOR_CLIENT_SECRET is a secret; the other four values are identifiers and can live in plain repository variables.
• Because one provider credential is active per organization, CI and humans share it — if you rotate it, update the CI secret in the same change.
• Use a remote state backend (S3, GCS, Terraform Cloud, …) so CI runs and local runs see the same state.

​

Troubleshooting