Manage Firezone with Terraform

The Firezone Terraform Provider lets you manage Firezone Portal configuration alongside the infrastructure that runs your Gateways. Define Sites, Resources, Policies, Groups, Actors, memberships, and Gateways in the same Terraform configuration that defines your cloud or on-premises infrastructure.

Use the provider to review access changes in a Terraform plan, discuss them in pull requests, and apply the same configuration across environments. You can also import supported Portal objects, which lets your team bring an existing Firezone account under Terraform management over time.

The provider reference covers each resource, data source, and argument. This guide covers the workflow for configuring and operating Firezone with Terraform.

Set up the provider

Create an API token under Settings → API Tokens in the admin portal. Store it outside your Terraform configuration and export it before you run Terraform:

export FIREZONE_TOKEN="<your-api-token>"

Add the provider to your configuration. Firezone Cloud uses https://rest-api.firezone.dev; for a self-hosted Portal, set endpoint to its bare API host.

terraform {
  required_providers {
    firezone = {
      source = "firezone/firezone"
    }
  }
}

provider "firezone" {
  endpoint = "https://rest-api.firezone.dev"
}

The provider reads FIREZONE_TOKEN from your environment. You can also set FIREZONE_ENDPOINT when you do not want to write the endpoint in configuration. Run terraform init, then use terraform plan to review changes before you apply them.

Manage access configuration

Use Terraform resources for Sites, Resources, Policies, native Groups, Actors, Group memberships, and Gateways. The example below creates a Site and an internal application, then grants a directory-synced Engineering Group access to it:

resource "firezone_site" "production" {
  name = "production"
}

resource "firezone_resource" "internal_app" {
  site_id = firezone_site.production.id
  name    = "internal-app"
  type    = "dns"
  address = "app.internal.example.com"

  filters {
    protocol = "tcp"
    ports    = ["443"]
  }
}

data "firezone_group" "engineering" {
  name = "Engineering"
}

resource "firezone_policy" "engineering_app" {
  group_id    = data.firezone_group.engineering.id
  resource_id = firezone_resource.internal_app.id
  description = "Engineering access to the internal application"
}

Use data sources for existing Sites, Groups, Actors, Clients, authentication providers, and Entra, Google Workspace, or Okta directories. A data source returns one record. Use an ID when you need to reference a Resource, Policy, or Gateway created outside Terraform.

Deploy and rotate Gateways

firezone_gateway creates a Gateway and returns a sensitive single-owner token. Pass that token to the Terraform resource or module that deploys the Gateway host. The same handoff works with the Firezone Gateway modules for AWS, Azure, and Google Cloud, or with your own Docker, Kubernetes, or VM configuration.

resource "firezone_gateway" "us_east" {
  site_id                = firezone_site.production.id
  name                   = "us-east-1a"
  token_rotation_trigger = "2026-09-15"
}

Change token_rotation_trigger to rotate the token. The value is arbitrary; a date records when your team last requested a rotation. Terraform then exposes the replacement token for the resource that deploys the Gateway host. Update that host during the grace period, because the old token stops working when the Gateway connects with the replacement or the grace period ends.

Terraform stores Gateway tokens in state. Restrict access to your remote state backend and encrypt it at rest. When your secret manager supports write-only arguments, use one to avoid storing the token a second time in state.

See Manage Gateway Tokens for the Portal workflow and the single-owner token lifecycle.

Adopt an existing Portal

Import a supported object before Terraform manages it. Start with a matching resource block, import the Portal object by ID, then run terraform plan and adjust the block until the plan reports no changes:

resource "firezone_site" "production" {
  name = "production"
}

terraform import firezone_site.production <site-id>

Import lets your team move Sites, Resources, Policies, Groups, Actors, memberships, Gateways, and static device-pool memberships into Terraform in stages. Check the provider reference for each resource's import ID format.

What the Terraform Provider cannot manage

The provider does not manage these Firezone areas:

• Authentication providers and directories. Set them up in the Portal, where an administrator completes the OAuth authorization flow. Use their data sources in Terraform after setup.
• Device enrollment. Devices can only be enrolled in two ways, either the first time the Device connects to Firezone or using Device sync through a posture provider.
• Service-account tokens. For now, the Terraform provider does not have a way to to create a service-account token and the token must be created in the Portal.
• Gateway status and metadata. Use the Portal to inspect a Gateway's online state, addresses, and version.
• Account Settings. Any changes to your account, such as seat count, must go through the Portal.
• Logs. Though logs have a REST API endpoint, it is not enabled through the Terraform provider.
• Device-Posture integrations. Similar to Authentication and Directory providers, Device-Posture integrations can require interactive authorization and must be done in the Portal.

See the provider reference for the current resource and data-source list.

Further reading

• Firezone Terraform Provider on the Terraform Registry
• Provider source and issue tracker
• Deploy Gateways

Need help? See all support options.