terraform-provider-stackguardian

StackGuardian Terraform Provider

The StackGuardian Terraform Provider allows Terraform to programmatically interact with the StackGuardian API to help you manage resources on the StackGuardian platform, ultimately enabling organizations to manage cloud infrastructure in a cost-efficient, secure, and compliant way.

It covers 15 resources and 17 data sources — workflows, workflow groups, stacks, templates and their revisions, connectors, policies, roles, role assignments and runner groups.

[!TIP] Looking for ready-to-use examples? All StackGuardian Terraform modules and examples are maintained in the terraform-stackguardian-modules repository.

Quick start

The provider is published on the Terraform Registry:

terraform {
  required_providers {
    stackguardian = {
      source  = "StackGuardian/stackguardian"
      version = "~> 1.12"
    }
  }
}

provider "stackguardian" {
  api_key  = "<YOUR-API-KEY>"                   # or env var STACKGUARDIAN_API_KEY
  org_name = "<YOUR-ORG-NAME>"                  # or env var STACKGUARDIAN_ORG_NAME
  api_uri  = "https://api.app.stackguardian.io" # or env var STACKGUARDIAN_API_URI; use "https://api.us.stackguardian.io" for the US region
}

resource "stackguardian_workflow_group" "example" {
  resource_name = "Simple-Workflow-Group"
  description   = "Example of how to create a workflow group using the StackGuardian Terraform Provider"
  tags          = ["tf-provider-example", "example"]
}

Documentation

Reference for every resource and data source is on the Terraform Registry, alongside eleven guides:

Examples

• terraform-stackguardian-modules — the collection of StackGuardian Terraform modules and examples.
• Quickstart — a minimal working configuration to get started.
• Onboarding projects — end-to-end projects covering connectors, workflow groups, roles and role assignments.

Development

Prerequisites

• Go >= 1.26.7 (see go.mod)
• Terraform — CI tests against 1.14.0; the acceptance suite skips versions below 1.1.0, and the import {} block examples need 1.5.0 or newer
• tfplugindocs for documentation work, via make tools-install
• act to run the GitHub workflows locally (optional)

Common tasks

Documentation workflow

docs/ is generated — never edit it by hand. Content lives in two places:

• Attribute text comes from MarkdownDescription in each schema.go, mostly via shared constants in internal/constants/. A data source should reuse the same constant as its resource twin so the two cannot drift.
• Page prose lives in docs-templates/, and embedded .tf snippets in docs-examples/.

Edit those, then:

make docs-generate           # rebuild docs/
make docs-validate           # structure and frontmatter
make docs-validate-examples  # type-check every example
make docs-check              # fail if docs/ is stale

docs-validate-examples needs no credentials and makes no API calls. It builds the provider, serves it from a local filesystem mirror, and runs terraform validate over every example — the standalone files under docs-examples/ and docs-guides-assets/, plus every ```terraform block embedded in page and guide prose. Prose blocks are not uniform, so scripts/extract-doc-blocks.py classifies each one and checks it the way it can actually be checked: self-contained snippets are validated, import {} blocks have their target verified against the schema, and bare attribute fragments have their names looked up. That catches unknown resource types, renamed attributes, bad references and type errors before a reader copies them.

Testing

Unit tests need nothing:

make test

Acceptance tests create and destroy real resources, so they need an organization:

export TF_ACC=1
export STACKGUARDIAN_API_KEY=<key>
export STACKGUARDIAN_API_URI=<uri>
export STACKGUARDIAN_ORG_NAME=<org>

make test-acc                                                   # everything
make test-acc TEST=./internal/resource/workflow_git/            # one package
make test-acc TESTARGS='-run TestAccWorkflowGit_WithVcsConfig'  # one test

Every identifier the suite creates is generated per run and prefixed tfacc-, via acctest.ResourceName. Static names made the suite order-dependent: a run that failed before its destroy step left the name taken, and every later run failed at create with 409 already exists. The shared prefix is what makes a leak identifiable afterwards.

When a run is interrupted between create and destroy, its resources survive. Sweep them:

make test-acc-sweep        # report what carries the prefix; deletes nothing
make test-acc-sweep-apply  # delete it

The sweep only ever touches names carrying the tfacc- prefix, and reports rather than deletes unless you ask it to.

Running the workflows locally

The GitHub workflows can be run on your machine with act, which avoids pushing a branch to see a CI result:

make gh-workflow-test-provider     # the provider test workflow
make gh-workflow-test-api-stg      # API tests against staging
make gh-workflow-test-api-prd      # API tests against production

Release notes for each version are in the CHANGELOG and on the GitHub releases page.

Contributing

Contributions are welcome — please see CONTRIBUTING.md for guidelines and the Code of Conduct for community standards. Use GitHub issues to report bugs or request features.

License

This project is licensed under the Mozilla Public License 2.0.