netbird-iac/terraform/README.md

NetBird IaC

Terraform configuration for managing NetBird VPN resources via GitOps.

Resources Managed

• Groups: ground-stations, pilots, operators, fusion-servers
• Policies: Access control between groups
• Setup Keys: For peer enrollment

Usage

Making Changes

1. Edit the relevant .tf file
2. Create a PR
3. CI runs terraform plan - review the changes
4. Merge PR
5. CI runs terraform apply - changes applied

Adding a New Group

# groups.tf
resource "netbird_group" "new_team" {
  name = "new-team"
}

Adding a Setup Key (Per-Ticket)

# setup_keys.tf
resource "netbird_setup_key" "ticket_1234_pilot" {
  name        = "ticket-1234-pilot-ivanov"
  type        = "one-off"
  auto_groups = [netbird_group.pilots.id]
  usage_limit = 1
  ephemeral   = false
}

# outputs.tf
output "ticket_1234_pilot_key" {
  value     = netbird_setup_key.ticket_1234_pilot.key
  sensitive = true
}

Retrieving Setup Keys

After apply, retrieve keys locally:

terraform output -raw gs_setup_key
terraform output -raw pilot_setup_key

Local Development

# Create tfvars (copy from example)
cp terraform.tfvars.example terraform.tfvars
# Edit with your NetBird PAT

# Init and plan
terraform init
terraform plan

# Apply (be careful!)
terraform apply

CI/CD

Configured in .gitea/workflows/terraform.yml:

• PR: terraform plan
• Merge to main: terraform apply

Required secrets in Gitea:

• NETBIRD_TOKEN: NetBird PAT

State Management

State is committed to git (terraform.tfstate). This is acceptable for single-operator scenarios but not recommended for production with multiple operators.

For production, configure a remote backend (S3, Terraform Cloud, etc.).