From dac5cea5eef94561f2f66271cb4ddf200459edc1 Mon Sep 17 00:00:00 2001 From: Slawomir Koszewski Date: Sun, 23 Aug 2026 22:10:29 +0200 Subject: [PATCH] Add Azure deployment examples and enhance configuration management - Update .gitignore to exclude Terraform files - Enhance README with Azure deployment instructions - Refactor publish.sh to use a container for changelog parsing - Add Azure example files including Terraform configurations - Create cloud-init templates for PKI and default configurations - Implement workload VM setup for testing routing --- .gitignore | 4 + README.md | 3 +- debian-package/publish.sh | 9 +- examples/azure/README.md | 45 +++++++ examples/azure/network.tf | 104 +++++++++++++++ examples/azure/outputs.tf | 9 ++ examples/azure/providers.tf | 3 + examples/azure/router.tf | 111 ++++++++++++++++ examples/azure/routes.tf | 25 ++++ examples/azure/terraform.tfvars.example | 18 +++ examples/azure/variables.tf | 170 ++++++++++++++++++++++++ examples/azure/versions.tf | 14 ++ examples/azure/workload.tf | 44 ++++++ examples/cloud-init-with-pki.yaml.tpl | 84 ++++++++++++ examples/cloud-init.yaml.tpl | 28 +--- examples/install.sh | 4 + 16 files changed, 651 insertions(+), 24 deletions(-) create mode 100644 examples/azure/README.md create mode 100644 examples/azure/network.tf create mode 100644 examples/azure/outputs.tf create mode 100644 examples/azure/providers.tf create mode 100644 examples/azure/router.tf create mode 100644 examples/azure/routes.tf create mode 100644 examples/azure/terraform.tfvars.example create mode 100644 examples/azure/variables.tf create mode 100644 examples/azure/versions.tf create mode 100644 examples/azure/workload.tf create mode 100644 examples/cloud-init-with-pki.yaml.tpl diff --git a/.gitignore b/.gitignore index c7ffa0f..8a03275 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,7 @@ CLAUDE.md __pycache__ .vscode tmp +.terraform* +*.tfstate +*.tfstate.* +*.auto.tfvars diff --git a/README.md b/README.md index c14f752..e651fbf 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,8 @@ from the internal NIC instead; with `mode = auto` the interface names go too. Alternatively write `/etc/vpn-router/vpn-router.conf` directly before or after installing. A configuration-management tool should do that and then restart `vpn-router-setup`. -See [examples/](examples/) for a cloud-init template and a shell installer. +See [examples/](examples/) for a cloud-init template and a shell installer, and +[examples/azure/](examples/azure/) for a full Terraform example that deploys a router on Azure. ## Configuration diff --git a/debian-package/publish.sh b/debian-package/publish.sh index a88e2e5..f2a9a48 100755 --- a/debian-package/publish.sh +++ b/debian-package/publish.sh @@ -1,8 +1,13 @@ #!/bin/sh set -e -VERSION="$(dpkg-parsechangelog --show-field Version -l debian/changelog)" -PACKAGE="$(dpkg-parsechangelog --show-field Source -l debian/changelog)" +changelog_field() { + container run --rm -v "$(pwd):/mnt" vpn-router-builder \ + dpkg-parsechangelog --show-field "$1" -l /mnt/debian/changelog +} + +VERSION="$(changelog_field Version)" +PACKAGE="$(changelog_field Source)" DEB="out/${PACKAGE}_${VERSION}_all.deb" if [ ! -f "$DEB" ]; then diff --git a/examples/azure/README.md b/examples/azure/README.md new file mode 100644 index 0000000..d6d44f8 --- /dev/null +++ b/examples/azure/README.md @@ -0,0 +1,45 @@ +# Azure example + +Deploys `vpn-router` on an Azure VM: a two-NIC router (external/WAN and internal/protected), +a demo protected `workload` subnet routed through it, and cloud-init that installs and +configures the package on first boot. See the repository's top-level [README](../../README.md) +for what the package itself does. + +## Prerequisites + +- An Azure subscription and `az login` (or another form of Azure credentials Terraform can pick + up). +- An SSH key pair for `admin_ssh_public_key`. +- A build of the `vpn-router` package published to the repository at `repo_url` (default: the + project's Gitea Debian registry). See [../../debian-package](../../debian-package) for + `build.sh`/`publish.sh`. +- That repository must allow anonymous reads, since the router pulls the package with no + credentials configured. On Gitea this means the `debian` package registry under the + `slawek` account is set to public/anonymous-read; `publish.sh` still authenticates to + upload, only reads are anonymous. This is a one-time change made on the Gitea side, outside + this repository. + +## Usage + +```sh +cp terraform.tfvars.example terraform.tfvars +$EDITOR terraform.tfvars +export TF_VAR_psk='change-me' # keep secrets out of tracked files +``` + +`platform = azure` and `mode = auto` are hard-coded into the cloud-init template call in +`router.tf`: the router has exactly two NICs, the external one carries the default route (it is +marked `primary` and holds the public IP), which is exactly the case `mode = auto` is designed +to detect reliably - see the top-level README's "What mode decides" section. + +## Verifying + +```sh +ssh @$(terraform output -raw router_public_ip) +systemctl status vpn-router-setup +swanctl --list-sas +``` + +Set `deploy_workload_vm = true` and re-apply to add a VM on the `workload` subnet (no public +IP - reach it via the router or Azure Bastion) for confirming that its traffic to `remote_cidrs` +actually flows through the router. diff --git a/examples/azure/network.tf b/examples/azure/network.tf new file mode 100644 index 0000000..d6aa094 --- /dev/null +++ b/examples/azure/network.tf @@ -0,0 +1,104 @@ +resource "azurerm_resource_group" "this" { + name = "rg-${var.name}" + location = var.location +} + +resource "azurerm_virtual_network" "this" { + name = "vnet-${var.name}" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + address_space = [var.vnet_address_space] +} + +resource "azurerm_subnet" "ext" { + name = "ext" + resource_group_name = azurerm_resource_group.this.name + virtual_network_name = azurerm_virtual_network.this.name + address_prefixes = [var.ext_subnet_cidr] +} + +resource "azurerm_subnet" "int" { + name = "int" + resource_group_name = azurerm_resource_group.this.name + virtual_network_name = azurerm_virtual_network.this.name + address_prefixes = [var.int_subnet_cidr] +} + +resource "azurerm_subnet" "workload" { + name = "workload" + resource_group_name = azurerm_resource_group.this.name + virtual_network_name = azurerm_virtual_network.this.name + address_prefixes = [var.workload_subnet_cidr] +} + +resource "azurerm_dns_a_record" "router_ext" { + count = var.dns_zone_id != null ? 1 : 0 + + name = trimsuffix(var.local_fqdn, ".${split("/", var.dns_zone_id)[length(split("/", var.dns_zone_id)) - 1]}") + zone_name = split("/", var.dns_zone_id)[length(split("/", var.dns_zone_id)) - 1] + resource_group_name = split("/", var.dns_zone_id)[4] + ttl = 300 + records = [azurerm_public_ip.ext.ip_address] +} + +resource "azurerm_network_security_group" "router_ext" { + name = "nsg-${var.name}-ext" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + + security_rule { + name = "Allow-SSH-TCP-22" + priority = 100 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + source_port_range = "*" + destination_port_range = "22" + source_address_prefix = "*" + destination_address_prefix = "*" + } + + security_rule { + name = "Allow-IKE-UDP-500" + priority = 110 + direction = "Inbound" + access = "Allow" + protocol = "Udp" + source_port_range = "*" + destination_port_range = "500" + source_address_prefix = "*" + destination_address_prefix = "*" + } + + security_rule { + name = "Allow-IPsec-NAT-T-UDP-4500" + priority = 120 + direction = "Inbound" + access = "Allow" + protocol = "Udp" + source_port_range = "*" + destination_port_range = "4500" + source_address_prefix = "*" + destination_address_prefix = "*" + } + + dynamic "security_rule" { + for_each = var.wireguard_enabled ? [1] : [] + content { + name = "Allow-WireGuard-UDP" + priority = 130 + direction = "Inbound" + access = "Allow" + protocol = "Udp" + source_port_range = "*" + destination_port_range = tostring(var.wireguard_listen_port) + source_address_prefix = "*" + destination_address_prefix = "*" + } + } +} + +resource "azurerm_network_interface_security_group_association" "router_ext" { + network_interface_id = azurerm_network_interface.ext.id + network_security_group_id = azurerm_network_security_group.router_ext.id +} diff --git a/examples/azure/outputs.tf b/examples/azure/outputs.tf new file mode 100644 index 0000000..84f9ba5 --- /dev/null +++ b/examples/azure/outputs.tf @@ -0,0 +1,9 @@ +output "router_public_ip" { + description = "Public IP address of the router VM." + value = azurerm_public_ip.ext.ip_address +} + +output "router_internal_ip" { + description = "Private IP address of the router's internal NIC - the next hop to use in routes configured outside this Terraform run (another route table, or an on-prem device) that need to reach remote_cidrs through this router." + value = azurerm_network_interface.int.private_ip_address +} diff --git a/examples/azure/providers.tf b/examples/azure/providers.tf new file mode 100644 index 0000000..ab91b24 --- /dev/null +++ b/examples/azure/providers.tf @@ -0,0 +1,3 @@ +provider "azurerm" { + features {} +} diff --git a/examples/azure/router.tf b/examples/azure/router.tf new file mode 100644 index 0000000..948db08 --- /dev/null +++ b/examples/azure/router.tf @@ -0,0 +1,111 @@ +data "http" "repo_gpg_key" { + url = "${var.repo_url}/repository.key" +} + +locals { + supply_pki = var.ca_cert_file != "" + + cloud_init_vars = { + hostname = var.name + fqdn = var.local_fqdn + repo_url = var.repo_url + repo_gpg_key = data.http.repo_gpg_key.response_body + ubuntu_codename = var.ubuntu_codename + platform = "azure" + mode = "auto" + external_interface = "" + internal_interface = "" + local_id_mode = var.local_id_mode + local_cidrs = var.local_cidrs + int_addr = "" + int_gateway_ip = "" + remote_addrs = var.remote_addrs + remote_id = var.remote_id + remote_cidrs = var.remote_cidrs + psk_b64 = base64encode(var.psk) + p2s_enabled = var.p2s_enabled + p2s_address_pool = var.p2s_address_pool + p2s_ca_name = "VPN Router CA" + wg_enabled = var.wireguard_enabled + wg_address = var.wireguard_address + wg_listen_port = var.wireguard_listen_port + } +} + +resource "azurerm_public_ip" "ext" { + name = "pip-${var.name}-ext" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + allocation_method = "Static" + sku = "Standard" +} + +resource "azurerm_network_interface" "ext" { + name = "${var.name}-ext-nic" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + ip_forwarding_enabled = true + + ip_configuration { + name = "ext" + subnet_id = azurerm_subnet.ext.id + private_ip_address_allocation = "Dynamic" + public_ip_address_id = azurerm_public_ip.ext.id + } +} + +resource "azurerm_network_interface" "int" { + name = "${var.name}-int-nic" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + ip_forwarding_enabled = true + + ip_configuration { + name = "int" + subnet_id = azurerm_subnet.int.id + private_ip_address_allocation = "Dynamic" + } +} + +resource "azurerm_linux_virtual_machine" "router" { + name = var.name + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + size = var.vm_size + admin_username = var.admin_username + admin_password = var.admin_password != "" ? var.admin_password : null + disable_password_authentication = var.admin_password == "" + + network_interface_ids = [ + azurerm_network_interface.ext.id, + azurerm_network_interface.int.id, + ] + + admin_ssh_key { + username = var.admin_username + public_key = var.admin_ssh_public_key + } + + os_disk { + caching = "ReadWrite" + storage_account_type = "StandardSSD_LRS" + } + + source_image_reference { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + + custom_data = base64encode( + local.supply_pki + ? templatefile("${path.module}/../cloud-init-with-pki.yaml.tpl", merge(local.cloud_init_vars, { + label = split(".", var.local_fqdn)[0] + ca_cert = file(var.ca_cert_file) + server_cert = file(var.server_cert_file) + server_key = file(var.server_key_file) + })) + : templatefile("${path.module}/../cloud-init.yaml.tpl", local.cloud_init_vars) + ) +} diff --git a/examples/azure/routes.tf b/examples/azure/routes.tf new file mode 100644 index 0000000..410eb94 --- /dev/null +++ b/examples/azure/routes.tf @@ -0,0 +1,25 @@ +locals { + remote_cidr_list = [for c in split(",", var.remote_cidrs) : trimspace(c) if trimspace(c) != ""] +} + +resource "azurerm_route_table" "router" { + name = "rt-${var.name}" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location +} + +resource "azurerm_route" "to_remote" { + for_each = toset(local.remote_cidr_list) + + name = "to-${replace(each.value, "/", "-")}" + resource_group_name = azurerm_resource_group.this.name + route_table_name = azurerm_route_table.router.name + address_prefix = each.value + next_hop_type = "VirtualAppliance" + next_hop_in_ip_address = azurerm_network_interface.int.private_ip_address +} + +resource "azurerm_subnet_route_table_association" "workload" { + subnet_id = azurerm_subnet.workload.id + route_table_id = azurerm_route_table.router.id +} diff --git a/examples/azure/terraform.tfvars.example b/examples/azure/terraform.tfvars.example new file mode 100644 index 0000000..6934a19 --- /dev/null +++ b/examples/azure/terraform.tfvars.example @@ -0,0 +1,18 @@ +# Copy to terraform.tfvars (or a git-ignored *.auto.tfvars) and adjust. +# Keep secrets - psk here - out of any tracked file: set them with +# TF_VAR_psk or in a git-ignored *.auto.tfvars instead. + +location = "westeurope" +name = "vpn-router-example" +admin_ssh_public_key = "ssh-ed25519 AAAA... you@example.com" + +local_fqdn = "router.example.com" +local_cidrs = "10.0.3.0/24" + +remote_addrs = "peer.example.net" +remote_id = "peer.example.net" +remote_cidrs = "192.168.0.0/24" + +p2s_enabled = false +wireguard_enabled = false +deploy_workload_vm = false diff --git a/examples/azure/variables.tf b/examples/azure/variables.tf new file mode 100644 index 0000000..661a67c --- /dev/null +++ b/examples/azure/variables.tf @@ -0,0 +1,170 @@ +variable "location" { + description = "Azure region to deploy into." + type = string +} + +variable "name" { + description = "Base name used to derive resource names." + type = string + default = "vpn-router-example" +} + +variable "admin_ssh_public_key" { + description = "SSH public key installed for the admin_username on both VMs." + type = string +} + +variable "admin_username" { + description = "Admin username on both VMs." + type = string + default = "azureuser" +} + +variable "admin_password" { + description = "Admin password for the router VM. SSH key auth is always configured; leaving this empty additionally disables password authentication, setting it enables password auth alongside the key." + type = string + default = "" + sensitive = true +} + +variable "vm_size" { + description = "VM size for the router." + type = string + default = "Standard_B2ls_v2" +} + +variable "local_fqdn" { + description = "FQDN of the router, used as the road-warrior/IKE identity and, when dns_zone_id is set, as the name of the A record created for it." + type = string +} + +variable "dns_zone_id" { + description = "Resource ID of an existing Azure DNS zone to create local_fqdn's A record in, pointing at the router's public IP. local_fqdn must be a name within that zone. Leave null to skip - local_fqdn is then just a label with nothing making it resolve." + type = string + nullable = true + default = null +} + +variable "local_id_mode" { + description = "IKE local identity source: fqdn, public_ip or internal_ip." + type = string + default = "fqdn" +} + +variable "local_cidrs" { + description = "Local subnet CIDR(s) advertised into the site-to-site tunnel. Should include the workload subnet CIDR." + type = string +} + +variable "remote_addrs" { + description = "Remote gateway address(es) or FQDN for the site-to-site tunnel." + type = string +} + +variable "remote_id" { + description = "Remote peer's IKE identity, without a leading @." + type = string +} + +variable "remote_cidrs" { + description = "Remote subnet CIDR(s) reachable through the site-to-site tunnel." + type = string +} + +variable "psk" { + description = "Pre-shared key for the site-to-site IKEv2 tunnel." + type = string + sensitive = true +} + +variable "p2s_enabled" { + description = "Enable road-warrior (P2S) access." + type = bool + default = false +} + +variable "p2s_address_pool" { + description = "CIDR block assigned to road-warrior clients." + type = string + default = "" +} + +variable "ca_cert_file" { + description = "Path to an existing CA certificate PEM to supply instead of letting the package generate one. Leave empty to auto-generate." + type = string + default = "" +} + +variable "server_cert_file" { + description = "Path to an existing server certificate PEM, paired with ca_cert_file." + type = string + default = "" +} + +variable "server_key_file" { + description = "Path to an existing server private key PEM, paired with ca_cert_file." + type = string + default = "" + sensitive = true +} + +variable "wireguard_enabled" { + description = "Enable the WireGuard endpoint." + type = bool + default = false +} + +variable "wireguard_address" { + description = "Address and prefix length for the wg0 interface." + type = string + default = "" +} + +variable "wireguard_listen_port" { + description = "UDP port WireGuard listens on." + type = number + default = 51820 +} + +variable "deploy_workload_vm" { + description = "Deploy a bare VM on the workload subnet, for manually verifying routing through the router." + type = bool + default = false +} + +variable "repo_url" { + description = "Base URL of the Debian package repository the router pulls vpn-router from." + type = string + default = "https://gitea.koszewscy.waw.pl/api/packages/slawek/debian" +} + +variable "ubuntu_codename" { + description = "Ubuntu release codename of the router VM's image, used to select the apt repo component." + type = string + default = "noble" +} + +variable "vnet_address_space" { + description = "Address space of the example VNet." + type = string + default = "10.0.0.0/16" +} + +variable "ext_subnet_cidr" { + description = "CIDR of the router's external (WAN-facing) subnet." + type = string + default = "10.0.1.0/24" +} + +variable "int_subnet_cidr" { + description = "CIDR of the router's internal (protected-network-facing) subnet." + type = string + default = "10.0.2.0/24" +} + +variable "workload_subnet_cidr" { + description = "CIDR of the demo protected workload subnet, routed through the router." + type = string + default = "10.0.3.0/24" +} + diff --git a/examples/azure/versions.tf b/examples/azure/versions.tf new file mode 100644 index 0000000..941d27b --- /dev/null +++ b/examples/azure/versions.tf @@ -0,0 +1,14 @@ +terraform { + required_version = ">= 1.9" + + required_providers { + azurerm = { + source = "hashicorp/azurerm" + version = ">= 4.0, < 5.0" + } + http = { + source = "hashicorp/http" + version = ">= 3.4, < 4.0" + } + } +} diff --git a/examples/azure/workload.tf b/examples/azure/workload.tf new file mode 100644 index 0000000..9a4303e --- /dev/null +++ b/examples/azure/workload.tf @@ -0,0 +1,44 @@ +# Bare VM on the workload subnet, for manually verifying that its traffic to +# remote_cidrs flows through the router. Off by default so a plain apply +# stays to just the router. + +resource "azurerm_network_interface" "workload" { + count = var.deploy_workload_vm ? 1 : 0 + name = "${var.name}-workload-nic" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + + ip_configuration { + name = "workload" + subnet_id = azurerm_subnet.workload.id + private_ip_address_allocation = "Dynamic" + } +} + +resource "azurerm_linux_virtual_machine" "workload" { + count = var.deploy_workload_vm ? 1 : 0 + name = "${var.name}-workload" + resource_group_name = azurerm_resource_group.this.name + location = azurerm_resource_group.this.location + size = var.vm_size + admin_username = var.admin_username + disable_password_authentication = true + network_interface_ids = [azurerm_network_interface.workload[0].id] + + admin_ssh_key { + username = var.admin_username + public_key = var.admin_ssh_public_key + } + + os_disk { + caching = "ReadWrite" + storage_account_type = "StandardSSD_LRS" + } + + source_image_reference { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } +} diff --git a/examples/cloud-init-with-pki.yaml.tpl b/examples/cloud-init-with-pki.yaml.tpl new file mode 100644 index 0000000..895b9e0 --- /dev/null +++ b/examples/cloud-init-with-pki.yaml.tpl @@ -0,0 +1,84 @@ +#cloud-config +# +# Example: install and configure vpn-router during first boot, supplying an +# existing CA and server certificate instead of letting the package generate +# one. See cloud-init.yaml.tpl for the variant that generates its own CA. +# +# Template variables are Terraform templatefile() placeholders. Adapt or drop +# them for whatever renders this file.