NetBird Terraform Provider (netbirdio/terraform-provider-netbird)

NetBird Terraform Provider

https://github.com/netbirdio/terraform-provider-netbird
Admin
A Terraform Provider for managing NetBird accounts and their associated resources.

Tokens:27,948
Snippets:171
Trust Score:8.3
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# NetBird Terraform Provider

The NetBird Terraform Provider enables infrastructure-as-code management of NetBird zero-trust network resources. NetBird is a WireGuard-based mesh VPN that creates secure peer-to-peer connections between devices. This provider allows teams to automate the provisioning and configuration of their NetBird network infrastructure, including peers, groups, policies, DNS settings, routes, and access controls through declarative Terraform configurations.

The provider connects to the NetBird Management API and supports all core NetBird features including network access policies, setup keys for peer enrollment, DNS management, posture checks for device compliance, identity provider integration, reverse proxy services, and SCIM provisioning. It works with both the NetBird Cloud service (api.netbird.io) and self-hosted NetBird management servers.

## Provider Configuration

Configure the NetBird provider with your management API credentials. The token is a Personal Access Token (PAT) from your NetBird account.

```hcl
variable "netbird_token" {
  sensitive   = true
  description = "NetBird Management Access Token"
}

terraform {
  required_providers {
    netbird = {
      source = "registry.terraform.io/netbirdio/netbird"
    }
  }
}

provider "netbird" {
  token          = var.netbird_token        # Required - can also use NB_PAT env var
  management_url = "https://api.netbird.io" # Optional - defaults to NetBird Cloud
  tenant_account = "account-id"             # Optional - for multi-tenant impersonation
}
```

## netbird_group Resource

Create and manage groups for organizing peers and applying policies. Groups are fundamental building blocks for network segmentation and access control.

```hcl
# Look up an existing peer by IP address
data "netbird_peer" "webserver" {
  ip = "100.64.0.5"
}

# Create a group and assign peers to it
resource "netbird_group" "production_servers" {
  name = "Production Servers"
  peers = [
    data.netbird_peer.webserver.id,
  ]
}

# Import existing group: terraform import netbird_group.production_servers cvi609bl0ubs73ask10g
```

## netbird_network Resource

Create logical networks to organize and isolate resources. Networks contain resources and routers that define connectivity.

```hcl
resource "netbird_network" "corporate" {
  name        = "Corporate Network"
  description = "Main corporate network infrastructure"
}

# Output computed attributes
output "network_info" {
  value = {
    id        = netbird_network.corporate.id
    resources = netbird_network.corporate.resources
    routers   = netbird_network.corporate.routers
    policies  = netbird_network.corporate.policies
  }
}

# Import existing network: terraform import netbird_network.corporate cvr9ibrl0ubs73c11gr0
```

## netbird_network_resource Resource

Define network resources within a network that peers can access through routers.

```hcl
resource "netbird_group" "developers" {
  name = "Developers"
}

resource "netbird_network" "internal" {
  name        = "Internal Services"
  description = "Internal application services"
}

resource "netbird_network_resource" "api_service" {
  network_id  = netbird_network.internal.id
  name        = "API Gateway"
  description = "Internal API gateway service"
  address     = "api.internal.company.com"
  groups      = [netbird_group.developers.id]
  enabled     = true
}

# Import: terraform import netbird_network_resource.api_service network_id:resource_id
```

## netbird_network_router Resource

Configure routers that provide connectivity to network resources with traffic control options.

```hcl
resource "netbird_group" "router_peers" {
  name = "Router Peers"
}

resource "netbird_network" "datacenter" {
  name        = "Datacenter Network"
  description = "Datacenter connectivity"
}

resource "netbird_network_router" "primary" {
  network_id  = netbird_network.datacenter.id
  peer_groups = [netbird_group.router_peers.id]
  metric      = 100      # Lower metric = higher priority
  enabled     = true
  masquerade  = true     # Enable NAT for outbound traffic
}

# Import: terraform import netbird_network_router.primary network_id:router_id
```

## netbird_policy Resource

Create access control policies with rules defining allowed traffic between source and destination groups.

```hcl
resource "netbird_group" "backend_servers" {
  name = "Backend Servers"
}

resource "netbird_group" "frontend_servers" {
  name = "Frontend Servers"
}

# Basic TCP policy allowing frontend to backend communication
resource "netbird_policy" "frontend_to_backend" {
  name        = "Frontend to Backend Access"
  description = "Allow frontend servers to access backend services"
  enabled     = true

  rule {
    name          = "HTTP/HTTPS Access"
    action        = "accept"
    bidirectional = false
    enabled       = true
    protocol      = "tcp"
    ports         = ["80", "443", "8080"]
    sources       = [netbird_group.frontend_servers.id]
    destinations  = [netbird_group.backend_servers.id]
  }
}

# SSH policy with authorized groups for access control
resource "netbird_policy" "ssh_access" {
  name    = "SSH Access Policy"
  enabled = true

  rule {
    name          = "SSH Rule"
    action        = "accept"
    bidirectional = true
    enabled       = true
    protocol      = "netbird-ssh"
    sources       = [netbird_group.backend_servers.id]
    destinations  = [netbird_group.backend_servers.id]

    # Map source group IDs to authorized local users
    authorized_groups = {
      (netbird_group.backend_servers.id) = ["admin", "deploy"]
    }
  }
}

# Policy with port ranges
resource "netbird_policy" "database_access" {
  name    = "Database Access"
  enabled = true

  rule {
    name          = "Database Ports"
    action        = "accept"
    bidirectional = false
    enabled       = true
    protocol      = "tcp"
    sources       = [netbird_group.backend_servers.id]
    destinations  = [netbird_group.backend_servers.id]

    port_ranges {
      start = 5432
      end   = 5439
    }
  }
}

# Import: terraform import netbird_policy.frontend_to_backend cvr9ibrl0ubs73c11gr0
```

## netbird_setup_key Resource

Create setup keys for automated peer enrollment. Setup keys allow devices to join your NetBird network without manual approval.

```hcl
resource "netbird_group" "auto_enrolled" {
  name = "Auto-Enrolled Devices"
}

# Reusable setup key for automated deployments
resource "netbird_setup_key" "deployment" {
  name                   = "CI/CD Deployment Key"
  type                   = "reusable"        # or "one-off"
  expiry_seconds         = 2592000           # 30 days (0 for unlimited)
  usage_limit            = 100               # Max uses (0 for unlimited)
  auto_groups            = [netbird_group.auto_enrolled.id]
  ephemeral              = false             # true = delete peer after 10min inactive
  allow_extra_dns_labels = true
  revoked                = false
}

# Access the generated setup key
output "setup_key" {
  value     = netbird_setup_key.deployment.key
  sensitive = true
}

output "setup_key_info" {
  value = {
    id         = netbird_setup_key.deployment.id
    expires    = netbird_setup_key.deployment.expires
    state      = netbird_setup_key.deployment.state
    used_times = netbird_setup_key.deployment.used_times
    valid      = netbird_setup_key.deployment.valid
  }
}

# Import: terraform import netbird_setup_key.deployment cvr9ibrl0ubs73c11gr0
```

## netbird_peer Resource and Data Source

Manage peer configuration and look up existing peers by various attributes.

```hcl
# Look up peer by IP
data "netbird_peer" "by_ip" {
  ip = "100.64.0.10"
}

# Look up peer by name
data "netbird_peer" "by_name" {
  name = "production-web-01"
}

# Look up peer by ID
data "netbird_peer" "by_id" {
  id = "d057h0jl0ubs73cftnp0"
}

# Configure an existing peer's settings
resource "netbird_peer" "webserver" {
  id                            = data.netbird_peer.by_name.id
  name                          = "Production Web Server"
  ssh_enabled                   = true
  login_expiration_enabled      = true
  inactivity_expiration_enabled = true
  approval_required             = false
}
```

## netbird_peers Data Source

Query multiple peers with filtering criteria for bulk operations.

```hcl
data "netbird_group" "production" {
  name = "Production"
}

# Find peers matching multiple criteria
data "netbird_peers" "linux_servers" {
  os                            = "Ubuntu 24.04"
  connected                     = true
  ssh_enabled                   = true
  login_expiration_enabled      = true
  inactivity_expiration_enabled = false
  groups                        = [data.netbird_group.production.id]
}

# Use the matching peer IDs
output "matching_peers" {
  value = data.netbird_peers.linux_servers.ids
}

# Additional filter options available:
# - name, ip, connection_ip, dns_label
# - user_id, hostname, country_code, city_name
# - approval_required, login_expired, geoname_id
```

## netbird_user Resource

Manage users including service accounts for automation.

```hcl
resource "netbird_group" "admin_group" {
  name = "Administrators"
}

# Create a service user for automation
resource "netbird_user" "ci_service" {
  is_service_user = true
  name            = "CI/CD Service Account"
  auto_groups     = [netbird_group.admin_group.id]
  is_blocked      = false
  role            = "admin"  # or "user", "owner"
}

# Invite a regular user
resource "netbird_user" "developer" {
  is_service_user = false
  name            = "Jane Developer"
  email           = "jane@company.com"
  auto_groups     = [netbird_group.admin_group.id]
  is_blocked      = false
  role            = "user"
}

# Import: terraform import netbird_user.developer user_id
```

## netbird_token Resource

Create Personal Access Tokens for API authentication.

```hcl
# Look up current user
data "netbird_user" "current" {
  self = true
}

# Create a PAT for API access
resource "netbird_token" "api_access" {
  user_id         = data.netbird_user.current.id
  name            = "Terraform Automation Token"
  expiration_days = 90
}

output "token_value" {
  value     = netbird_token.api_access.id
  sensitive = true
}

# Import: terraform import netbird_token.api_access user_id:token_id
```

## netbird_dns_zone Resource

Create DNS zones for internal name resolution within your NetBird network.

```hcl
resource "netbird_group" "all_peers" {
  name = "All Peers"
}

resource "netbird_dns_zone" "internal" {
  name                 = "internal-services"
  domain               = "internal.company.com"
  enabled              = true
  enable_search_domain = true
  distribution_groups  = [netbird_group.all_peers.id]
}

# Import: terraform import netbird_dns_zone.internal zone_id
```

## netbird_dns_record Resource

Create DNS records within zones for service discovery.

```hcl
resource "netbird_dns_zone" "local" {
  name    = "local-zone"
  domain  = "local.company.com"
  enabled = true
}

# A Record for IPv4
resource "netbird_dns_record" "api" {
  zone_id = netbird_dns_zone.local.id
  name    = "api.local.company.com"
  type    = "A"
  content = "192.168.1.100"
  ttl     = 300
}

# AAAA Record for IPv6
resource "netbird_dns_record" "api_v6" {
  zone_id = netbird_dns_zone.local.id
  name    = "api.local.company.com"
  type    = "AAAA"
  content = "2001:db8::1"
  ttl     = 600
}

# CNAME Record
resource "netbird_dns_record" "mail" {
  zone_id = netbird_dns_zone.local.id
  name    = "mail.local.company.com"
  type    = "CNAME"
  content = "mail.external.com"
  ttl     = 300
}

# Wildcard Record
resource "netbird_dns_record" "wildcard" {
  zone_id = netbird_dns_zone.local.id
  name    = "*.local.company.com"
  type    = "A"
  content = "10.10.1.2"
  ttl     = 300
}

# Import: terraform import netbird_dns_record.api zone_id:record_id
```

## netbird_dns_settings Resource

Configure global DNS settings for management group exclusions.

```hcl
resource "netbird_group" "unmanaged_dns" {
  name = "Unmanaged DNS Peers"
}

resource "netbird_dns_settings" "main" {
  disabled_management_groups = [netbird_group.unmanaged_dns.id]
}
```

## netbird_nameserver_group Resource

Configure custom nameserver groups for DNS resolution.

```hcl
resource "netbird_group" "dns_users" {
  name = "DNS Users"
}

resource "netbird_nameserver_group" "corporate_dns" {
  name        = "Corporate DNS Servers"
  description = "Internal DNS servers for corporate domain resolution"

  nameservers = [
    {
      ip      = "8.8.8.8"
      ns_type = "udp"
      port    = 53
    },
    {
      ip      = "8.8.4.4"
      ns_type = "udp"
      port    = 53
    }
  ]

  groups                 = [netbird_group.dns_users.id]
  search_domains_enabled = true
}

# Import: terraform import netbird_nameserver_group.corporate_dns nsgroup_id
```

## netbird_route Resource

Create network routes for directing traffic through specific peers or peer groups.

```hcl
data "netbird_group" "routers" {
  name = "Router Peers"
}

data "netbird_group" "users" {
  name = "Users"
}

data "netbird_peer" "gateway" {
  name = "Gateway Server"
}

# Domain-based route through a specific peer
resource "netbird_route" "external_services" {
  network_id            = "external-access"
  description           = "Route to external services"
  domains               = ["api.external.com", "cdn.external.com"]
  peer                  = data.netbird_peer.gateway.id
  groups                = [data.netbird_group.users.id]
  access_control_groups = [data.netbird_group.routers.id]
}

# Network CIDR route through peer groups (HA)
resource "netbird_route" "datacenter" {
  network_id            = "datacenter-access"
  description           = "Route to datacenter network"
  network               = "10.0.0.0/8"
  peer_groups           = [data.netbird_group.routers.id]
  groups                = [data.netbird_group.users.id]
  access_control_groups = [data.netbird_group.routers.id]
}

# Import: terraform import netbird_route.datacenter route_id
```

## netbird_posture_check Resource

Define device compliance requirements that must be met before allowing network access.

```hcl
resource "netbird_posture_check" "compliance" {
  name        = "Device Compliance Check"
  description = "Ensure devices meet security requirements"

  # Minimum NetBird client version
  netbird_version_check {
    min_version = "0.25.0"
  }

  # Operating system version requirements
  os_version_check {
    android_min_version        = "13.0.0"
    ios_min_version            = "16.0.0"
    darwin_min_version         = "13.0.0"
    linux_min_kernel_version   = "5.15.0"
    windows_min_kernel_version = "10.0.19041"
  }

  # Geographic restrictions
  geo_location_check {
    locations = [
      { country_code = "US" },
      { country_code = "CA" },
      { country_code = "GB" },
      { country_code = "DE" }
    ]
    action = "allow"  # or "deny"
  }

  # Network range restrictions
  peer_network_range_check {
    ranges = ["10.0.0.0/8", "192.168.0.0/16"]
    action = "allow"
  }

  # Required process checks (multiple allowed)
  process_check {
    linux_path   = "/usr/bin/crowdstrike-falcon"
    mac_path     = "/Library/CS/falcond"
    windows_path = "C:\\Program Files\\CrowdStrike\\CSFalconService.exe"
  }
}

# Apply posture check to policy
resource "netbird_policy" "secure_access" {
  name                   = "Secure Access Policy"
  enabled                = true
  source_posture_checks  = [netbird_posture_check.compliance.id]

  rule {
    name          = "Compliant Device Access"
    action        = "accept"
    bidirectional = true
    enabled       = true
    protocol      = "all"
    sources       = [netbird_group.users.id]
    destinations  = [netbird_group.servers.id]
  }
}

# Import: terraform import netbird_posture_check.compliance check_id
```

## netbird_account_settings Resource

Configure account-wide settings for peer management and security.

```hcl
resource "netbird_account_settings" "main" {
  # JWT/SSO settings
  jwt_groups_enabled     = true
  jwt_groups_claim_name  = "groups"
  jwt_allow_groups       = ["engineering", "devops"]

  # Peer expiration settings
  peer_login_expiration_enabled      = true
  peer_login_expiration              = 604800  # 7 days in seconds
  peer_inactivity_expiration_enabled = true
  peer_inactivity_expiration         = 2592000 # 30 days in seconds

  # Access control settings
  peer_approval_enabled     = true
  regular_users_view_blocked = false
  groups_propagation_enabled = true

  # Network features
  routing_peer_dns_resolution_enabled    = true
  network_traffic_logs_enabled           = true
  network_traffic_packet_counter_enabled = false
}
```

## netbird_identity_provider Resource

Configure external identity providers for SSO authentication.

```hcl
resource "netbird_identity_provider" "okta" {
  name          = "Okta SSO"
  type          = "oidc"
  client_id     = "0oa1234567890abcdef"
  client_secret = var.okta_client_secret
  issuer        = "https://company.okta.com"
}
```

## netbird_scim Resource

Configure SCIM provisioning for automated user and group synchronization.

```hcl
resource "netbird_scim" "okta_scim" {
  provider_name       = "okta"
  prefix              = "okta-sync"
  enabled             = true
  group_prefixes      = ["engineering", "product", "security"]
  user_group_prefixes = ["users", "contractors"]
}
```

## netbird_reverse_proxy_domain Resource

Register custom domains for the NetBird reverse proxy service.

```hcl
data "netbird_reverse_proxy_clusters" "all" {}

resource "netbird_reverse_proxy_domain" "app" {
  domain         = "app.company.com"
  target_cluster = data.netbird_reverse_proxy_clusters.all.clusters[0].address
}
```

## netbird_reverse_proxy_service Resource

Expose internal services through the NetBird reverse proxy with authentication.

```hcl
data "netbird_reverse_proxy_domain" "free" {
  type = "free"  # Use NetBird's free subdomain
}

data "netbird_peer" "webserver" {
  name = "web-server"
}

resource "netbird_reverse_proxy_service" "webapp" {
  name   = "Internal Web App"
  domain = data.netbird_reverse_proxy_domain.free.domain

  targets {
    target_id   = data.netbird_peer.webserver.id
    target_type = "peer"
    port        = 8080
    protocol    = "http"
  }

  auth {
    link_auth {
      enabled = true  # Require NetBird authentication
    }
  }
}
```

## Summary

The NetBird Terraform Provider enables complete automation of zero-trust network infrastructure. Primary use cases include automated peer enrollment using setup keys for CI/CD pipelines, declarative network segmentation through groups and policies, compliance enforcement via posture checks, and centralized DNS management for service discovery. Teams can version control their entire network configuration, enabling GitOps workflows where network changes go through code review and are applied consistently across environments.

Integration patterns typically involve combining multiple resources: groups organize peers by function or environment, policies define access rules between groups, setup keys enable automated enrollment, and DNS/routes provide service connectivity. For enterprise deployments, identity provider integration enables SSO authentication while SCIM provisioning keeps users and groups synchronized with corporate directories. The provider works seamlessly with both NetBird Cloud and self-hosted deployments, making it suitable for organizations with varying security and compliance requirements.