pulumi-netbird

README

Pulumi NetBird Native Provider

NetBird is a modern, WireGuard-based mesh VPN. This provider integrates NetBird into Pulumi for seamless infrastructure automation.

This repository contains the Pulumi NetBird Provider, a native Pulumi provider built in Go using the pulumi-go-provider SDK. It enables you to manage NetBird resources—like networks, peers, groups, and access rules—declaratively using Pulumi's infrastructure-as-code framework.

✨ Features

• Manage NetBird resources using Pulumi in Go or YAML
• Built natively with Pulumi's Go SDK

📦 Installing plugin

To manually install the Pulumi NetBird resource plugin replace the version number (0.0.20) with the desired release if needed. The plugin will be downloaded from the specified GitHub repository.

pulumi plugin install resource netbird 0.0.20 --server github://api.github.com/mbrav/pulumi-netbird

🧪 Build and Test

make help                 # View available build/test commands

🚀 Example Usage with Pulumi YAML

You can use this provider with Pulumi YAML to manage NetBird infrastructure declaratively.

1. Setup

Navigate to the YAML example directory:

cd examples/yaml

Initialize a new stack and configure your credentials:

pulumi stack init test
pulumi config set netbird:token YOUR_TOKEN
pulumi config set netbird:url https://nb.domain:33073

2. Deploy

pulumi up

This deploys a sample NetBird environment with networks, groups, network resources, a router, and a policy.

Example Pulumi.yaml

name: provider-netbird
runtime: yaml
plugins:
  providers:
    - name: netbird
      path: ../../bin

# You can also define creds here
config:
  netbird:token: token
  netbird:url: https://nb.domain:33073

outputs:
  networkManagement:
    value:
      name: ${net-management.name}
      id: ${net-management.Id}

resources:
  net-management:
    type: netbird:resource:Network
    properties:
      name: Management
      description: Network for Management

  net-r1:
    type: netbird:resource:Network
    properties:
      name: R1
      description: Network for Region 1

  group-devops:
    type: netbird:resource:Group
    properties:
      name: DevOps
      peers: []

  group-backoffice:
    type: netbird:resource:Group
    properties:
      name: Backoffice
      peers: []

  group-hr:
    type: netbird:resource:Group
    properties:
      name: HR
      peers: []

  netres-r1-net-01:
    type: netbird:resource:NetworkResource
    properties:
      name: S1 Franfurt Net 01
      description: Network 01 in S1 Franfurt
      network_id: ${net-r1.id}
      address: 10.10.1.0/24
      enabled: true
      group_ids:
        - ${group-devops.id}

  netres-r1-net-02:
    type: netbird:resource:NetworkResource
    properties:
      name: S1 Franfurt Net 02
      description: Network 02 in S1 Franfurt
      network_id: ${net-r1.id}
      address: 10.10.2.0/24
      enabled: true
      group_ids:
        - ${group-devops.id}

  netres-r1-net-03:
    type: netbird:resource:NetworkResource
    properties:
      name: S1 Franfurt Net 03
      description: Network 03 in S1 Franfurt
      network_id: ${net-r1.id}
      address: 10.10.3.0/24
      enabled: true
      group_ids:
        - ${group-devops.id}

  router-r1:
    type: netbird:resource:NetworkRouter
    properties:
      network_id: ${net-r1.id}
      enabled: true
      masquerade: true
      metric: 10
      peer: ""
      peer_groups:
        - ${group-devops.id}

  test-import-peer:
    type: netbird:resource:Peer
    properties:
      inactivity_expiration_enabled: false
      login_expiration_enabled: false
      name: test-import-peer
      sshEnabled: true
    options:
      protect: true

  test-ssh-policy:
    type: netbird:resource:Policy
    properties:
      name: "Test SSH Policy"
      description: "Allow SSH access from admin group to servers"
      enabled: true
      posture_checks: []
      rules:
        - name: "SSH Access"
          description: "Allow inbound SSH from Admins to Servers"
          bidirectional: false
          action: accept
          enabled: true
          protocol: tcp
          ports:
            - "22"
          # sources:
          #   - "group-admins"
          # destinations:
          #   - "group-servers"

🦫 Example Usage with Pulumi Go

You can use this provider with Pulumi Go to manage NetBird infrastructure declaratively.

The SDK is accessible through the generated github.com/mbrav/pulumi-netbird/sdk/go/netbird module.

SDK versions are available to Go with tags that are prefixed with sdk/vx.x.x and can be listed with the following command:

go list -m -versions github.com/mbrav/pulumi-netbird/sdk

Output:

github.com/mbrav/pulumi-netbird/sdk v0.0.11 v0.0.12 v0.0.13 v0.0.14 v0.0.15 v0.0.16 v0.0.17 v0.0.18 v0.0.19 v0.0.20

1. Setup

Navigate to the Go example directory:

cd examples/go

Initialize a new stack and configure your credentials:

pulumi stack init test
pulumi config set netbird:token YOUR_TOKEN
pulumi config set netbird:url https://nb.domain:33073

2. Deploy

pulumi up

🐍 Example Usage with Pulumi Python

You can use this provider with Pulumi Python to manage NetBird infrastructure declaratively.

1. Setup

First, you must generate the python SDK:

make provider 
make sdk_python

Then install the wheel:

pip install sdk/python/bin/dist/pulumi_netbird-0.0.20.tar.gz

Navigate to the Python example directory:

cd examples/python

Initialize a new stack and configure your credentials:

pulumi stack init test
pulumi config set netbird:token YOUR_TOKEN
pulumi config set netbird:url https://nb.domain:33073

2. Deploy

pulumi up

📁 Repository Structure

• provider/ – Go implementation of the provider
• sdk/go/netbird/ – Go SDK for the NetBird provider
• examples/ – Example Pulumi projects using the provider

📚 References

• Pulumi Go Provider Docs
• NetBird Documentation
• Pulumi YAML Documentation