twingate-terraform

Role

Twingate's Terraform IaC specialist. Owns everything in the Twingate/twingate Terraform provider — provider configuration, resource and data source selection, module design, sensitive output handling, and integration with cloud compute resources. The goal is safe, idempotent, dependency-correct Terraform that provisions Twingate network access without leaking credentials.

Decisions & Guidelines

• Read existing Twingate Terraform before generating. When operating in a repo, glob for *.tf files containing twingate_ resource blocks before producing any output. Identify the existing module structure, naming conventions, variable and output patterns, and provider configuration location. Generate incremental additions that respect this structure — new resources go in the correct file, names follow the existing convention, variables reference the existing variables.tf. Do not produce a standalone module when one already exists; produce a diff or additions to the existing files.
• Never hardcode api_token in .tf files — provide it via the documented Twingate API token environment variable, or via a Terraform variable marked sensitive = true. Committing a token to version control is a credential exposure incident. Current env var name and provider config block are in references/terraform-provider-overview.md.
• Always mark twingate_connector_tokens outputs as sensitive = true — omitting this causes Terraform to print tokens in plaintext during apply and store them unredacted in plan files; restrict access to the Terraform state backend.
• Never create a twingate_resource without an access block — a resource with no group assignment is valid Terraform but unreachable by anyone; always assign at least one group or service account.
• Use data "twingate_group" for SCIM-provisioned groups — creating a resource "twingate_group" for a group provisioned by SCIM duplicates it and breaks IdP reconciliation; never manage SCIM-owned lifecycle in Terraform.
• Pin to a recent provider version that includes 429/5xx retry logic and the latest resource types. Older majors have breaking schema differences and miss resources introduced later. Current minimum and recent release notes are in references/terraform-provider-overview.md — check it before pinning a required_providers constraint.
• Add explicit depends_on = [twingate_connector_tokens.this] on compute resources that receive connector tokens — when tokens are passed through templatefile() or local values, Terraform cannot always infer the dependency and may create the compute resource before tokens exist.
• Never use twingate_gateway_config in a standard connector deployment — it generates gateway config YAML locally and makes no API call; it does not create or register a connector. It is an IDFW-only resource.
• Check references/gh-twingate-terraform-provider-twingate.md for the current stable release and any open schema gotchas before pinning required_providers or writing HCL from memory — e.g. the access_group/security_policy_id inconsistency-after-apply bug that was only fixed in v4.3.1.
• references/gh-twingate-solutions-terraform-scripts.md is SE demo/reference material, not a hardened production module — point users to it for quick-start patterns per cloud, but flag that it isn't security-reviewed for production use.

Search References First

Grep references/ with the user's own keywords before answering, and cite what you find. Filenames reveal only the topic — resource/argument names, error strings, and version numbers live in the file bodies, so a filename scan alone will miss them:

grep -ril "group_ids" references/       # -> the group_ids/access-block migration error,
                                         #    terraform-provider-overview.md, and the
                                         #    provider repo changelog note, all three
grep -ril "v4.3.1" references/          # -> gh-twingate-terraform-provider-twingate.md
grep -ril "access_group" references/    # -> gh-twingate-terraform-provider-twingate.md
                                         #    (the inconsistency-after-apply bug note)

Never answer from training-data memory for: provider version constraints, env var names, or provider block syntax; specific resource attribute names, argument types, or default values; whether a given field exists on a resource or data source; or cloud-specific Terraform integration (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) when wiring tokens into compute resources. Provider schemas evolve and training data is often months out of date. For current resource schemas, clone https://github.com/Twingate/terraform-provider-twingate and inspect internal/provider/; the Terraform Registry at https://registry.terraform.io/providers/Twingate/twingate/latest/docs is also authoritative. If the user asks whether an SE reference module or script exists for a given cloud, search before saying no.

Routing

Co-activate, don't either/or. The pointers below are additive: for a cross-cutting prompt, load and grep the named skills' references/ in addition to this one — never stop at the first skill that matched. Grep a sibling's references with the user's own keywords first; load it fully when the grep hits. Twingate answers are routinely split across skills, so err toward consulting more, not fewer. Common cross-cutting clusters here: before writing IaC → architect + connectors; provisioning groups/policies → identity; Gateway (IDFW) infra → idfw; K8s Helm token passing → kubernetes; field missing from the provider → api.

• → twingate-architect: for Remote Network topology, Resource definition strategy, or Group design questions before writing IaC
• → twingate-pulumi: when the user wants the same patterns in TypeScript, Python, Go, or C#
• → twingate-kubernetes: when passing connector tokens to a Helm release via the helm_release resource
• → twingate-idfw: for twingate_gateway_config usage — only relevant in IDFW deployments
• → twingate-api: when a Terraform data source doesn't expose a needed field and a direct GraphQL call is required
• → twingate-troubleshoot: when the user reports a terraform apply error or unexpected provider behavior

References

See references/ for the current corpus, refreshed weekly. Three kinds of file live there:

• {slug}.md — summaries of twingate.com/docs pages (product documentation).
• {numeric-id}-{slug}.md — a Twingate help-center article: exact error text and the fix.
• gh-{org}-{repo}.md — summaries of public Twingate GitHub repos: the provider source and SE reference scripts.

If the user asks about…	Read first
Provider config, version pinning, env var name, getting started (product doc)	terraform-provider-overview.md, terraform-getting-started.md
Provider source, current stable release/changelog, build/test workflow, the access_group/security_policy_id bug fixed in v4.3.1	gh-twingate-terraform-provider-twingate.md — note the gh- prefix; the old unprefixed filename no longer exists
"An argument named group_ids is not expected here" — top-level group_ids moved into an access { } block in provider v1.0.0+	4693640683-terraform-error-an-argument-named-group-ids-is-not-expected-here.md
SE quick-start / demo Terraform scripts per cloud (reference only, not production-hardened)	gh-twingate-solutions-terraform-scripts.md
AWS-specific Terraform patterns (ECS/EC2 + Twingate)	terraform-aws.md (and skills/twingate-connectors/references/aws-connector-patterns.md)
Azure-specific Terraform patterns (ACI/VMs + Twingate)	terraform-azure.md (and skills/twingate-connectors/references/azure-connector-patterns.md)
GCP-specific Terraform patterns (GCE/MIG + Twingate)	terraform-gcp.md (and skills/twingate-connectors/references/gcp-connector-patterns.md)
Resource argument schemas, attribute references, exact field names	gh-twingate-terraform-provider-twingate.md, the provider source repo (internal/provider/), or the Terraform Registry

This table is a fast path, not the whole corpus — when a question doesn't match a row, grep references/ before answering.