feat(terraform): add the Azure vnet module

deployment/terraform/modules/azure/vnet/main.tf

@@ -0,0 +1,100 @@
+locals {
+  # Subnets opt in to the NAT gateway individually. A delegated database subnet
+  # and the Application Gateway subnet must stay off it.
+  nat_gateway_subnets = var.enable_nat_gateway ? {
+    for key, subnet in var.subnets : key => subnet if subnet.nat_gateway
+  } : {}
+}
+
+resource "azurerm_virtual_network" "this" {
+  name                = "${var.name}-vnet"
+  resource_group_name = var.resource_group_name
+  location            = var.location
+  address_space       = var.address_space
+  tags                = var.tags
+}
+
+resource "azurerm_subnet" "this" {
+  for_each = var.subnets
+
+  name                              = "${var.name}-${each.key}"
+  resource_group_name               = var.resource_group_name
+  virtual_network_name              = azurerm_virtual_network.this.name
+  address_prefixes                  = each.value.address_prefixes
+  service_endpoints                 = each.value.service_endpoints
+  private_endpoint_network_policies = each.value.private_endpoint_network_policies
+
+  dynamic "delegation" {
+    for_each = each.value.delegation != null ? [each.value.delegation] : []
+    content {
+      name = "delegation"
+      service_delegation {
+        name    = delegation.value
+        actions = each.value.delegation_actions
+      }
+    }
+  }
+}
+
+# A single public IP keeps egress on one address, so downstream allowlists stay
+# stable across node replacements. Standard SKU is required by NAT gateway.
+resource "azurerm_public_ip" "nat" {
+  count = var.enable_nat_gateway ? 1 : 0
+
+  name                = "${var.name}-nat-pip"
+  resource_group_name = var.resource_group_name
+  location            = var.location
+  allocation_method   = "Static"
+  sku                 = "Standard"
+  zones               = var.nat_gateway_zones
+  tags                = var.tags
+}
+
+resource "azurerm_nat_gateway" "this" {
+  count = var.enable_nat_gateway ? 1 : 0
+
+  name                    = "${var.name}-nat"
+  resource_group_name     = var.resource_group_name
+  location                = var.location
+  sku_name                = "Standard"
+  idle_timeout_in_minutes = var.nat_gateway_idle_timeout_minutes
+  zones                   = var.nat_gateway_zones
+  tags                    = var.tags
+}
+
+resource "azurerm_nat_gateway_public_ip_association" "this" {
+  count = var.enable_nat_gateway ? 1 : 0
+
+  nat_gateway_id       = azurerm_nat_gateway.this[0].id
+  public_ip_address_id = azurerm_public_ip.nat[0].id
+}
+
+resource "azurerm_subnet_nat_gateway_association" "this" {
+  for_each = local.nat_gateway_subnets
+
+  subnet_id      = azurerm_subnet.this[each.key].id
+  nat_gateway_id = azurerm_nat_gateway.this[0].id
+
+  # Without this the association can be created before the gateway has its
+  # public IP, and egress silently falls back to the default outbound path.
+  depends_on = [azurerm_nat_gateway_public_ip_association.this]
+}
+
+resource "azurerm_network_watcher_flow_log" "this" {
+  count = var.enable_flow_logs ? 1 : 0
+
+  name                 = "${var.name}-vnet-flow-log"
+  network_watcher_name = var.network_watcher_name
+  resource_group_name  = var.network_watcher_resource_group_name
+  location             = var.location
+  target_resource_id   = azurerm_virtual_network.this.id
+  storage_account_id   = var.flow_log_storage_account_id
+  enabled              = true
+  version              = 2
+  tags                 = var.tags
+
+  retention_policy {
+    enabled = var.flow_log_retention_days > 0
+    days    = var.flow_log_retention_days
+  }
+}

deployment/terraform/modules/azure/vnet/outputs.tf

@@ -0,0 +1,56 @@
+output "vnet_id" {
+  description = "Resource ID of the virtual network"
+  value       = azurerm_virtual_network.this.id
+}
+
+output "vnet_name" {
+  description = "Name of the virtual network"
+  value       = azurerm_virtual_network.this.name
+}
+
+output "address_space" {
+  description = "Address space of the virtual network"
+  value       = azurerm_virtual_network.this.address_space
+}
+
+output "subnet_ids" {
+  description = "Subnet resource IDs, keyed by the same names as the subnets variable"
+  value       = { for key, subnet in azurerm_subnet.this : key => subnet.id }
+}
+
+output "subnet_address_prefixes" {
+  description = "Subnet address prefixes, keyed by the same names as the subnets variable"
+  value       = { for key, subnet in azurerm_subnet.this : key => subnet.address_prefixes }
+}
+
+# Convenience outputs for the subnets the other modules expect. Null when the
+# caller replaced the default subnet map and dropped that key.
+output "aks_subnet_id" {
+  description = "Resource ID of the AKS subnet"
+  value       = try(azurerm_subnet.this["aks"].id, null)
+}
+
+output "postgres_subnet_id" {
+  description = "Resource ID of the delegated PostgreSQL Flexible Server subnet"
+  value       = try(azurerm_subnet.this["postgres"].id, null)
+}
+
+output "private_endpoint_subnet_id" {
+  description = "Resource ID of the subnet that holds private endpoints"
+  value       = try(azurerm_subnet.this["private_endpoints"].id, null)
+}
+
+output "app_gateway_subnet_id" {
+  description = "Resource ID of the Application Gateway subnet"
+  value       = try(azurerm_subnet.this["app_gateway"].id, null)
+}
+
+output "nat_gateway_id" {
+  description = "Resource ID of the NAT gateway, null when disabled"
+  value       = try(azurerm_nat_gateway.this[0].id, null)
+}
+
+output "nat_gateway_public_ips" {
+  description = "Public IPs assigned to the NAT gateway. Egress from every attached subnet leaves from these."
+  value       = var.enable_nat_gateway ? [azurerm_public_ip.nat[0].ip_address] : []
+}

deployment/terraform/modules/azure/vnet/tests/vnet.tftest.hcl

@@ -0,0 +1,199 @@
+# Plans the module against a mocked provider, so these run without an Azure
+# subscription or credentials. Run with `terraform test` from the module directory.
+
+mock_provider "azurerm" {}
+
+variables {
+  name                = "onyx"
+  resource_group_name = "onyx-rg"
+  location            = "eastus"
+}
+
+run "default_subnets" {
+  command = plan
+
+  assert {
+    condition     = length(azurerm_subnet.this) == 4
+    error_message = "The default subnet map should create four subnets."
+  }
+
+  assert {
+    condition     = azurerm_subnet.this["aks"].name == "onyx-aks"
+    error_message = "Subnet names should be prefixed with the module name."
+  }
+
+  assert {
+    condition     = contains(azurerm_subnet.this["aks"].service_endpoints, "Microsoft.Storage")
+    error_message = "The AKS subnet needs the Microsoft.Storage service endpoint so the storage account can restrict access to it."
+  }
+
+  assert {
+    condition     = one(azurerm_subnet.this["postgres"].delegation).service_delegation[0].name == "Microsoft.DBforPostgreSQL/flexibleServers"
+    error_message = "The postgres subnet must be delegated to PostgreSQL Flexible Server."
+  }
+
+  assert {
+    condition     = length(azurerm_subnet.this["aks"].delegation) == 0
+    error_message = "Only the postgres subnet should be delegated."
+  }
+}
+
+run "nat_gateway_attaches_only_to_opted_in_subnets" {
+  command = plan
+
+  assert {
+    condition     = length(azurerm_subnet_nat_gateway_association.this) == 1
+    error_message = "Only the AKS subnet opts into the NAT gateway by default."
+  }
+
+  assert {
+    condition     = contains(keys(azurerm_subnet_nat_gateway_association.this), "aks")
+    error_message = "The AKS subnet is the one that needs egress."
+  }
+
+  assert {
+    condition     = azurerm_public_ip.nat[0].sku == "Standard"
+    error_message = "A NAT gateway requires a Standard SKU public IP."
+  }
+}
+
+run "nat_gateway_can_be_disabled" {
+  command = plan
+
+  variables {
+    enable_nat_gateway = false
+  }
+
+  assert {
+    condition     = length(azurerm_nat_gateway.this) == 0
+    error_message = "enable_nat_gateway = false should create no NAT gateway."
+  }
+
+  assert {
+    condition     = length(azurerm_subnet_nat_gateway_association.this) == 0
+    error_message = "Disabling the NAT gateway must also drop its subnet associations."
+  }
+}
+
+run "flow_logs_off_by_default" {
+  command = plan
+
+  assert {
+    condition     = length(azurerm_network_watcher_flow_log.this) == 0
+    error_message = "Flow logs are opt-in because they need a storage account and a Network Watcher."
+  }
+}
+
+run "flow_logs_require_a_storage_account" {
+  command = plan
+
+  variables {
+    enable_flow_logs = true
+  }
+
+  expect_failures = [var.enable_flow_logs]
+}
+
+run "flow_logs_require_a_network_watcher_too" {
+  command = plan
+
+  variables {
+    enable_flow_logs            = true
+    flow_log_storage_account_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/onyx-rg/providers/Microsoft.Storage/storageAccounts/onyxflowlogs"
+  }
+
+  expect_failures = [var.enable_flow_logs]
+}
+
+run "flow_logs_plan_when_both_destination_and_watcher_are_set" {
+  command = plan
+
+  variables {
+    enable_flow_logs            = true
+    flow_log_storage_account_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/onyx-rg/providers/Microsoft.Storage/storageAccounts/onyxflowlogs"
+    network_watcher_name        = "NetworkWatcher_eastus"
+  }
+
+  assert {
+    condition     = length(azurerm_network_watcher_flow_log.this) == 1
+    error_message = "With a destination and a watcher the flow log should be created."
+  }
+
+  assert {
+    condition     = azurerm_network_watcher_flow_log.this[0].network_watcher_name == "NetworkWatcher_eastus"
+    error_message = "The flow log should be owned by the supplied Network Watcher."
+  }
+
+  assert {
+    condition     = one(azurerm_network_watcher_flow_log.this[0].retention_policy).days == 365
+    error_message = "Retention should default to the Azure ceiling of 365 days."
+  }
+}
+
+run "a_custom_subnet_map_gets_no_nat_gateway_unless_it_asks" {
+  command = plan
+
+  # Opt-in: a caller writing their own map should not silently attach a NAT
+  # gateway to a subnet that cannot carry one.
+  variables {
+    subnets = {
+      aks = {
+        address_prefixes = ["10.0.0.0/20"]
+      }
+      appgw = {
+        address_prefixes = ["10.0.18.0/24"]
+      }
+    }
+  }
+
+  assert {
+    condition     = length(azurerm_subnet_nat_gateway_association.this) == 0
+    error_message = "A custom subnet map should attach no NAT gateway until a subnet asks for one."
+  }
+}
+
+run "rejects_a_blank_network_watcher_name" {
+  command = plan
+
+  variables {
+    enable_flow_logs            = true
+    flow_log_storage_account_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/onyx-rg/providers/Microsoft.Storage/storageAccounts/onyxflowlogs"
+    network_watcher_name        = "   "
+  }
+
+  expect_failures = [var.enable_flow_logs]
+}
+
+run "flow_log_retention_respects_the_azure_ceiling" {
+  command = plan
+
+  variables {
+    flow_log_retention_days = 400
+  }
+
+  expect_failures = [var.flow_log_retention_days]
+}
+
+run "nat_gateway_is_regional_or_single_zone" {
+  command = plan
+
+  variables {
+    nat_gateway_zones = ["1", "2"]
+  }
+
+  expect_failures = [var.nat_gateway_zones]
+}
+
+run "subnets_need_an_address_prefix" {
+  command = plan
+
+  variables {
+    subnets = {
+      aks = {
+        address_prefixes = []
+      }
+    }
+  }
+
+  expect_failures = [var.subnets]
+}