https://github.com/fedlify/terraform-wireguard
Terraform module that renders WireGuard configs for hub-and-spoke or mesh topologies, with optional key generation and a Docker lab for integration testing.
https://github.com/fedlify/terraform-wireguard
infrastructure-as-code mesh-networking terraform-module vpn wireguard
Last synced: about 1 month ago
JSON representation
Terraform module that renders WireGuard configs for hub-and-spoke or mesh topologies, with optional key generation and a Docker lab for integration testing.
- Host: GitHub
- URL: https://github.com/fedlify/terraform-wireguard
- Owner: fedlify
- Created: 2025-09-23T00:59:44.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-23T03:22:17.000Z (9 months ago)
- Last Synced: 2025-10-03T18:54:56.704Z (9 months ago)
- Topics: infrastructure-as-code, mesh-networking, terraform-module, vpn, wireguard
- Language: HCL
- Homepage:
- Size: 11.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Terraform WireGuard Config Generator
Composable Terraform module that produces WireGuard configuration files for distributed networks. Feed the module a set of node definitions and pick a topology (`hub-and-spoke` or `mesh`). The module resolves peer relationships, applies overrides, and outputs ready-to-use configs for every node.
## Highlights
- Supports `hub-and-spoke` (single hub with many spokes) and full `mesh` topologies
- Generates consistent peer blocks with optional per-peer overrides and preshared keys
- Optionally auto-generates WireGuard key pairs via the bundled script or a custom command
- Applies shared defaults for listen ports, DNS servers, and persistent keepalive timers
- Ships with hub-and-spoke and mesh examples plus `terraform test` suites for validation
- Cloud agnostic: no providers or infrastructure resources required
## Inputs at a glance
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `topology` | `string` | `"mesh"` | Network layout. One of `hub-and-spoke` or `mesh`. |
| `hub` | `string` | `null` | Hub node name when `topology = "hub-and-spoke"`. |
| `nodes` | `map(object)` | – | Node definitions keyed by name. Each object accepts `private_key`, `public_key`, `addresses`, optional `listen_port`, `endpoint`, `allowed_ips`, `dns`, `mtu`. |
| `default_listen_port` | `number` | `null` | Port applied when a node omits `listen_port`. |
| `default_dns` | `list(string)` | `[]` | DNS servers injected when a node omits `dns`. |
| `default_persistent_keepalive` | `number` | `null` | PersistentKeepalive fallback (seconds). |
| `preshared_keys` | `map(map(string))` | `{}` | Optional preshared keys, indexed `[local][remote]`. |
| `peer_overrides` | `map(map(object))` | `{}` | Per-peer overrides for allowed IPs, endpoint, preshared key, and keepalive. |
| `auto_generate_keys` | `bool` | `false` | Generate key pairs for nodes missing key material. Requires a keygen command. |
| `keygen_command` | `string` | `null` | Override the default key generator; useful when `wg` is unavailable or you have custom tooling. |
See `variables.tf` for full type information.
## Outputs
| Name | Description |
|------|-------------|
| `wireguard_configs` | Map of node name to rendered configuration string (sensitive). |
| `peer_matrix` | Computed peer lists for every node. |
| `nodes` | Normalised node settings after defaults are applied. |
## Quick start
```hcl
module "wireguard" {
source = "github.com/fedlify/terraform-wireguard"
topology = "hub-and-spoke"
hub = "hub"
nodes = {
hub = {
private_key = var.hub_private_key
public_key = var.hub_public_key
addresses = ["10.44.0.1/24"]
endpoint = "vpn.example.com:51820"
allowed_ips = ["10.44.0.0/24"]
dns = ["10.44.0.1"]
}
laptop = {
private_key = var.laptop_private_key
public_key = var.laptop_public_key
addresses = ["10.44.0.2/32"]
}
phone = {
private_key = var.phone_private_key
public_key = var.phone_public_key
addresses = ["10.44.0.3/32"]
}
}
peer_overrides = {
laptop = {
hub = {
persistent_keepalive = 25
}
}
}
default_listen_port = 51820
}
output "hub_config" {
value = module.wireguard.wireguard_configs["hub"]
sensitive = true
}
```
After `terraform apply`, export configs:
```shell
terraform output -raw hub_config > hub.conf
```
## Key generation
- Enable `auto_generate_keys` when you prefer the module to mint key pairs for any node missing `private_key`/`public_key`.
- By default the module runs `${path.module}/scripts/generate-keys.sh`, which shells out to `wg genkey`; ensure the WireGuard tools are installed on the Terraform runner.
- Supply `keygen_command` to point at your own executable (for example, a wrapper around an HSM or a deterministic generator used in tests).
## Examples and tests
- `examples/hub-and-spoke` – simple hub with two spokes
- `examples/mesh` – three-node mesh with shared defaults
- `lab/docker-two-node` – docker-compose lab that boots two peers end-to-end
Run the automated tests (Terraform >= 1.6 required):
```shell
terraform test
```
## Implementation notes
- `allowed_ips` defaults to the node's `addresses` when omitted, which suits many client peers. Override it for routing larger CIDR ranges.
- Provide keys in WireGuard's standard Base64 format (`wg genkey`, `wg pubkey`) when not using `auto_generate_keys`.
- Use `peer_overrides` or `preshared_keys` when a single pair deviates from the computed defaults.
WireGuard (R) is a registered trademark of Jason A. Donenfeld. This project is not affiliated with or endorsed by WireGuard.