How to Manage Terraform feature flags with Flagsmith

Most teams start using Terraform feature flags for one of two reasons:

• Someone's already using count and a boolean variable to conditionally create a resource, and they want to know if the same trick extends to actual product flags.
• Someone's already running Flagsmith (or eyeing it) and wants flag changes to go through the same pull request review as everything else in the repo.

This article covers the second one in depth: how the Flagsmith Terraform provider models flags, environments, and segments as resources, how to run flag changes through a review and apply cycle instead of a dashboard, and what actually changes once your flag catalog outgrows a handful of toggles.

What Terraform feature flags actually are

Terraform feature flags cover two genuinely different practices.

The first is the count meta-argument used as a boolean switch: count = var.enable_load_balancer ? 1 : 0 conditionally creates or omits a resource based on a variable, which is useful for infrastructure-level toggles, whether an environment gets a load balancer, a read replica, a CDN distribution, or a second availability zone.

The second is managing an actual feature-flagging platform, complete with targeting rules and percentage rollouts, plus a UI product managers can use without touching HCL, as Terraform resources.

That's what Flagsmith's feature management platform gives you. The count pattern is infrastructure conditionally existing or not; a flag platform is behavior conditionally exposed to specific users, independent of whether the underlying resource exists at all. You'll usually want both in the same repository: count for what gets provisioned, Flagsmith for what gets shown.

Setting up your Flagsmith Terraform provider

Flagsmith authenticates with a master API key generated from Organisation Settings inside Flagsmith (API Access, then Create API Key), and generating one requires organisation administrator permission.

The provider configuration:

Keep the key out of the repository. Pass it as a variable backed by an environment variable (TF_VAR_flagsmith_master_api_key) or your secrets manager of choice, never a literal string committed to version control.

The provider talks directly to Flagsmith's API, not to a local snapshot of what the flag looked like last time someone ran terraform apply. Every terraform plan reflects the platform's live state, which means a flag someone toggled by hand in the dashboard shows up as drift the moment you plan again, not as a silent divergence you discover later.

Defining and updating a feature flag in code

Here is an example of a project running a staged rollout. Say you're gating a redesigned checkout flow behind a flag and rolling it out to a defined segment before opening it to everyone:

Run terraform apply, and Flagsmith creates the feature and its environment binding, then the segment rule, in one pass. The terraform apply output confirms each resource as it's created, with Creation complete logged against every one in order.

Widening the rollout later is a one-line change: bump value = 10 to value = 50 in the segment's percentage-split condition, run terraform plan to confirm the diff is exactly that and nothing else, then terraform apply.

That diff, not a slider in a dashboard, is now the record of who widened the rollout and when.

Running flag changes through pull requests

The mechanics above work from a laptop, but the actual value shows up once flag changes go through the same pull request flow as your other Terraform code. Open a PR that touches checkout_rollout_cohort.tf, and a plan gets posted for review before anyone merges; merging it triggers the apply.

A reviewer sees exactly what percentage moved, not a screenshot of a dashboard, and the flag's entire history lives in git log alongside the commits that shipped the checkout flow it gates.

Stategraph's orchestration plugs into that flow directly. Open the PR and stategraph-bot comments with the plan: the resources impacted and the cost delta, plus (if you've set approval requirements per environment) who still needs to sign off before staging or production can merge.

Merge the PR and the apply runs, without you hand-assembling the CI glue that stitches terraform plan and apply to GitHub events yourself.

Rollback can still be reviewed. Instead of hunting for the previous value, open (or pre-stage, in draft, ready to merge the moment something looks wrong) a revert PR. Merging it re-applies the prior segment rule exactly, with its own plan and its own record in history.

What about the dashboard-drift case from earlier? An engineer flipping a flag by hand mid-incident is a legitimate escape hatch. Just don't treat a PR-triggered plan as your only chance to catch it: Stategraph's drift detection surfaces that hand-toggled flag against your Terraform-managed state without waiting for the next PR that happens to touch it.

Why flag-catalog scale changes the calculus

Everything is easy to manage at five flags, but then you hit fifty, and then five hundred spread across a dozen environments. At this point, most of the tooling built around this workflow stops scaling.

A terraform apply locks the entire state file, not just the flag you touched. Two engineers rolling out unrelated flags in the same Flagsmith project still queue behind each other: the lock has no concept of which changes actually overlap and which don't.

Stategraph's graph-scoped execution plans and applies against the subgraph a change actually reaches, so independent flag changes run in parallel instead of waiting in line.

The plan itself gets slower at scale too. A full terraform plan against a state holding hundreds of flags refreshes all of them to report a diff on one, which is a lot of API round trips and noise. Stategraph scopes the plan to the changed feature and its environment.

Then there's the question nobody's dashboard answers cleanly: what actually depends on this flag?

Knowing which segments and downstream services a feature actually touches, before a reviewer approves widening a rollout from 10% to 50%, is blast radius information you can query straight from the graph.

As a result, you can query that from the actual dependency graph, rather than reconstructing it from memory during an incident.

The flag definition no longer lives in one repository while the code or infrastructure reading it lives in another, which can be an issue when a platform team owns the Flagsmith project and product teams own the services consuming it.

Coordinating that as two separate applies leaves a window where one side has shipped and the other hasn't. A cross-state transaction closes that window by applying both as one atomic change.

Use cases for Terraform feature flags

Here are a few use cases for Terraform feature flags with Flagsmith and Stategraph:

• Environment consistency. Flags drifting out of sync across development, staging, and production is a routine failure mode when they live only in a dashboard, and a routine non-issue once the same Terraform configuration, with per-environment variables, governs every one of them.
• Canary rollouts. These follow the segment pattern shown above almost exactly, just with the percentage climbing over days or weeks instead of jumping straight to 100. Pairing that with Terraform's plan output gives you a paper trail of exactly which commit widened the audience at each stage, which is useful after the rollout is finished if you're trying to correlate a metric change with when a feature actually reached more users.
• Deprecation. The rollout in reverse benefits from the same discipline: reducing a flag's audience to zero and eventually deleting the feature resource entirely, tracked in git rather than abandoned in a dashboard nobody audits.

Conclusion

Terraform feature flags prove their merit when you ship a rollout through a pull request and watch a reviewer catch a percentage typo in the plan before it reaches a single user.

Flagsmith gets you the resource model; a PR-driven plan and apply cycle gets you the review; and once your flag count outgrows what a whole-state plan can comfortably handle, graph-scoped execution, resource-level locking, and blast-radius visibility are what keep that review meaningful instead of ceremonial.

Try Stategraph free and run your next flag rollout through it.

Terraform feature flags FAQs

Can you use Terraform to create and roll back feature flags?

Yes. Flagsmith's Terraform provider lets you define a feature and its environment state, plus any segment rules, as resources, and terraform apply creates them directly in Flagsmith.

Rolling back means reverting the commit or pull request that changed the resource and applying again, which restores the prior configuration with its own plan and its own audit trail rather than a remembered dashboard value.

Does Flagsmith's Terraform provider support segments and percentage rollouts?

Yes, through the flagsmith_segment resource, which accepts rules with a PERCENTAGE_SPLIT operator among others, and the flagsmith_feature_state resource, which binds a feature's enabled state and segment priority to a specific environment.

Is the count meta-argument the same thing as a feature flag?

count is different from a feature flag in that it conditionally creates or omits a resource entirely, which suits infrastructure-level toggles like whether an environment provisions a load balancer.

A platform like Flagsmith governs runtime behavior for defined user segments, independent of what infrastructure exists, so most teams use both for different parts of the same system rather than choosing one over the other.