feat: Azure scalable Gateway module and docs (#5644)

Resolves #2603

docs/README.md

@@ -103,18 +103,27 @@ product documentation, organized as follows:
 - [kotlin/](../kotlin/android): Android / ChromeOS clients.
 - [website/](../website): Marketing website and product documentation.
 - [terraform/](../terraform): Terraform files for various example deployments.
-  - [terraform/examples/google-cloud/nat-gateway](../terraform/examples/google-cloud/nat-gateway):
-    Example Terraform configuration for deploying a cluster of Firezone Gateways
-    behind a NAT gateway on GCP with single egress IP.
   - [terraform/examples/aws/nat-gateway](../terraform/examples/aws/nat-gateway):
     Example Terraform configuration for deploying a cluster of Firezone Gateways
-    behind a NAT gateway on AWS with single egress IP.
+    behind a NAT gateway on AWS with a single egress IP.
+  - [terraform/examples/google-cloud/nat-gateway](../terraform/examples/google-cloud/nat-gateway):
+    Example Terraform configuration for deploying a cluster of Firezone Gateways
+    behind a NAT gateway on GCP with a single egress IP.
+  - [terraform/examples/azure/nat-gateway](../terraform/examples/azure/nat-gateway):
+    Example Terraform configuration for deploying a cluster of Firezone Gateways
+    behind a NAT gateway on Azure with a single egress IP.
+  - [terraform/modules/aws/firezone-gateway](../terraform/modules/aws/firezone-gateway):
+    Production-ready Terraform module for deploying Firezone Gateways to AWS
+    using Auto Scaling Groups.
   - [terraform/modules/google-cloud/apps/gateway-region-instance-group](../terraform/modules/google-cloud/apps/gateway-region-instance-group):
     Production-ready Terraform module for deploying regional Firezone Gateways
     to Google Cloud Compute using Regional Instance Groups.
   - [terraform/modules/aws/firezone-gateway](../terraform/modules/aws/firezone-gateway):
     Production-ready Terraform module for deploying Firezone Gateways to AWS
     using Auto Scaling Groups.
+  - [terraform/modules/azure/firezone-gateway](../terraform/modules/azure/firezone-gateway):
+    Production-ready Terraform module for deploying Firezone Gateways to Azure
+    using Azure Orchestrated Virtual Machine Scale Sets.
 
 ## Quickstart
 

terraform/examples/README.md

@@ -21,3 +21,10 @@ instructions on how to deploy the example.
   one or more Firezone Gateways in a single GCP VPC that is configured with a
   Cloud NAT for egress. Read this if you're looking to deploy Firezone Gateways
   behind a single, shared static IP address on GCP.
+
+### Azure
+
+- [NAT Gateway](./azure/nat-gateway): This example shows how to deploy one or
+  more Firezone Gateways in a single Azure Vnet that is configured with a NAT
+  gateway for egress. Read this if you're looking to deploy Firezone Gateways
+  behind a single, shared static IP address on Azure.

terraform/examples/aws/nat-gateway/.terraform.lock.hcl

@@ -1,24 +0,0 @@
-# This file is maintained automatically by "terraform init".
-# Manual edits may be lost in future updates.
-
-provider "registry.terraform.io/hashicorp/aws" {
-  version = "5.55.0"
-  hashes = [
-    "h1:vChl08zNYLVzuSzfxz3wp3wNSx+vjwl/jPuyPbg59Ks=",
-    "zh:06fbb1cc4b61b9d6370d391bf7538aa6ef8b60b91c67d125a6be60a70b1d49f0",
-    "zh:1d52acd2184f379433a0fce2c29d5ed8fc7958d6a9d1b403310dcc36b2a3f626",
-    "zh:290bbce092f8836a1db530ac86d933cfea27d52b827639974a81bc48dfba8c34",
-    "zh:3531f2822c2de3ba837381c4ee4816c5b437fd204c07d659526a04d9154a65e8",
-    "zh:56d70db4c8c6c0ec1b665380b87726275f4ab3665b4b78ac86dc90e1010c0fe3",
-    "zh:8251d713c0b2c8c51b6858e51c70d083b484342ff9782a88c39e7eaa966c3da2",
-    "zh:9a7d1f7207e51382a7dd139dfd5786e7e905edf9bf89bbee4b59ad41365e87be",
-    "zh:9b12af85486a96aedd8d7984b0ff811a4b42e3d88dad1a3fb4c0b580d04fa425",
-    "zh:a529c78dfc60063289524690af78794e99a768835b88e27cdfec15bc85439f7c",
-    "zh:b6da1843355db05c5d412126406fd97db2a6ff9edc166b81c1cea2994535b4eb",
-    "zh:bfc08cd23b1556b3287d1b28ac7f12c7d459471d97a0592bf2579ea68d11bae7",
-    "zh:c382088faf05894191636b57861069a21de10a5ff4eb8f7cc122e764ccf7a4a8",
-    "zh:e27f99f389921314ee428b24990d3a829057ce532b2beb33c69387458722edd9",
-    "zh:ef11285eedb45ffc3fb2ecdfefa206e64eb2760a87fff15c44dee42de9703436",
-    "zh:fedc4ebee0d6fe196691127004db5d1ff8bd22e3b667a74026bb92c607589b6c",
-  ]
-}

terraform/examples/aws/nat-gateway/main.tf

@@ -1,4 +1,10 @@
-module "gateway_aws_example" {
+# Change these to match your environment
+locals {
+  region         = "us-east-1"
+  firezone_token = "YOUR_FIREZONE_TOKEN"
+}
+
+module "aws_firezone_gateway" {
   source = "github.com/firezone/firezone/terraform/modules/aws/firezone-gateway"
 
   ###################
@@ -7,7 +13,7 @@ module "gateway_aws_example" {
 
   # Generate a token from the admin portal in Sites -> <site> -> Deploy Gateway.
   # Only one token is needed for the cluster.
-  firezone_token = "YOUR_FIREZONE_TOKEN"
+  firezone_token = local.firezone_token
 
   # Pick an AMI to use. We recommend Ubuntu LTS or Amazon Linux 2.
   base_ami = data.aws_ami_ids.ubuntu.ids[0]
@@ -51,7 +57,7 @@ data "aws_ami_ids" "ubuntu" {
 
 provider "aws" {
   # Change this to your desired region
-  region = "us-east-1"
+  region = local.region
 }
 
 resource "aws_vpc" "main" {

terraform/examples/azure/nat-gateway/README.md

@@ -0,0 +1,4 @@
+# Deploy Firezone on Azure with Terraform
+
+See [our docs for a detailed guide](/kb/automate/terraform/azure) on deploying
+Firezone on Azure with Terraform using this example.

terraform/examples/azure/nat-gateway/main.tf

@@ -0,0 +1,213 @@
+# Change these to match your environment
+locals {
+  location       = "East US"
+  admin_ssh_key  = file("~/.ssh/id_rsa.azure.pub")
+  firezone_token = "YOUR_FIREZONE_TOKEN"
+}
+
+module "azure_firezone_gateway" {
+  source = "github.com/firezone/firezone/terraform/modules/azure/firezone-gateway"
+
+  ###################
+  # Required inputs #
+  ###################
+
+  # Azure resource group information
+  resource_group_location = azurerm_resource_group.firezone.location
+  resource_group_name     = azurerm_resource_group.firezone.name
+
+  # Generate a token from the admin portal in Sites -> <site> -> Deploy Gateway.
+  # Only one token is needed for the cluster.
+  firezone_token = local.firezone_token
+
+  # Attach the Gateways to your subnet.
+  private_subnet = azurerm_subnet.private.id
+
+  # Admin SSH public key. Must be RSA.
+  admin_ssh_key = local.admin_ssh_key
+
+  # Attach the Gateways to your NSG.
+  network_security_group_id = azurerm_network_security_group.firezone.id
+
+  # Attach the NAT Gateway
+  nat_gateway_id = azurerm_nat_gateway.firezone.id
+
+  ###################
+  # Optional inputs #
+  ###################
+
+  # Pick an image to use. Defaults to Ubuntu 22.04 LTS.
+  # source_image_reference {
+  #   publisher = "Canonical"
+  #   offer     = "0001-com-ubuntu-server-jammy"
+  #   sku       = "22_04-lts"
+  #   version   = "latest"
+  # }
+
+  # Deploy a specific version of the Gateway. Generally, we recommend using the latest version.
+  # firezone_version    = "latest"
+
+  # Override the default API URL. This should almost never be needed.
+  # firezone_api_url = "wss://api.firezone.dev"
+
+  # Gateways are very lightweight. In general it's preferable to deploy
+  # more smaller Gateways than fewer larger Gateways if you need to scale
+  # horizontally.
+  # See https://www.firezone.dev/kb/deploy/gateways#sizing-recommendations.
+  # instance_type       = "Standard_B1ls"
+
+  # We recommend a minimum of 3 instances for high availability.
+  # desired_capacity    = 3
+}
+
+# Configure the Azure provider
+provider "azurerm" {
+  features {}
+}
+
+# Create a resource group in your preferred region
+resource "azurerm_resource_group" "firezone" {
+  name     = "firezone-resources"
+  location = local.location
+}
+
+# Create a virtual network
+resource "azurerm_virtual_network" "firezone" {
+  name                = "firezone-vnet"
+  address_space       = ["172.16.0.0/16"]
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+}
+
+# Create a public subnet
+resource "azurerm_subnet" "public" {
+  name                 = "firezone-public-subnet"
+  resource_group_name  = azurerm_resource_group.firezone.name
+  virtual_network_name = azurerm_virtual_network.firezone.name
+  address_prefixes     = ["172.16.0.0/24"]
+}
+
+# Create a private subnet
+resource "azurerm_subnet" "private" {
+  name                 = "firezone-private-subnet"
+  resource_group_name  = azurerm_resource_group.firezone.name
+  virtual_network_name = azurerm_virtual_network.firezone.name
+  address_prefixes     = ["172.16.1.0/24"]
+}
+
+# Create a public IP for the NAT gateway
+resource "azurerm_public_ip" "firezone" {
+  name                = "firezone-pip"
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+  allocation_method   = "Static"
+  sku                 = "Standard"
+}
+
+# OPTIONAL: Create a bastion to allow SSH access to the VMs which
+# can be helpful for debugging when setting up the Gateways.
+# After you're sure this configuration works, you can remove the bastion.
+resource "azurerm_bastion_host" "firezone" {
+  name                = "firezone-bastion"
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+  sku                 = "Standard"
+  tunneling_enabled   = true
+
+  ip_configuration {
+    name                 = "firezone-bastion-ip"
+    subnet_id            = azurerm_subnet.bastion.id
+    public_ip_address_id = azurerm_public_ip.firezone-bastion.id
+  }
+}
+resource "azurerm_public_ip" "firezone-bastion" {
+  name                = "firezone-bastion-pip"
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+  allocation_method   = "Static"
+  sku                 = "Standard"
+}
+resource "azurerm_subnet" "bastion" {
+  name                 = "AzureBastionSubnet"
+  resource_group_name  = azurerm_resource_group.firezone.name
+  virtual_network_name = azurerm_virtual_network.firezone.name
+  address_prefixes     = ["172.16.2.0/24"]
+}
+
+# Create a NAT gateway
+resource "azurerm_nat_gateway" "firezone" {
+  name                = "firezone-nat-gateway"
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+}
+
+# Create a NAT gateway association
+resource "azurerm_nat_gateway_public_ip_association" "firezone" {
+  nat_gateway_id       = azurerm_nat_gateway.firezone.id
+  public_ip_address_id = azurerm_public_ip.firezone.id
+}
+
+# Associate the NAT gateway with the public subnet
+resource "azurerm_subnet_nat_gateway_association" "public" {
+  nat_gateway_id = azurerm_nat_gateway.firezone.id
+  subnet_id      = azurerm_subnet.public.id
+}
+
+# Associate the NAT gateway with the private subnet
+resource "azurerm_subnet_nat_gateway_association" "private" {
+  nat_gateway_id = azurerm_nat_gateway.firezone.id
+  subnet_id      = azurerm_subnet.private.id
+}
+
+# Create a network security group
+resource "azurerm_network_security_group" "firezone" {
+  name                = "firezone-nsg"
+  location            = azurerm_resource_group.firezone.location
+  resource_group_name = azurerm_resource_group.firezone.name
+
+  security_rule {
+    name                       = "allow-ssh"
+    priority                   = 1001
+    direction                  = "Inbound"
+    access                     = "Allow"
+    protocol                   = "Tcp"
+    source_port_range          = "*"
+    destination_port_range     = "22"
+    source_address_prefix      = "172.16.0.0/24"
+    destination_address_prefix = "*"
+  }
+
+  security_rule {
+    name                       = "allow-all-outbound"
+    priority                   = 1002
+    direction                  = "Outbound"
+    access                     = "Allow"
+    protocol                   = "*"
+    source_port_range          = "*"
+    destination_port_range     = "0-65535"
+    source_address_prefix      = "*"
+    destination_address_prefix = "0.0.0.0/0"
+  }
+}
+
+# Attach the NSG to the public subnet
+resource "azurerm_subnet_network_security_group_association" "public" {
+  subnet_id                 = azurerm_subnet.public.id
+  network_security_group_id = azurerm_network_security_group.firezone.id
+}
+
+# Attach the NSG to the private subnet
+resource "azurerm_subnet_network_security_group_association" "private" {
+  subnet_id                 = azurerm_subnet.private.id
+  network_security_group_id = azurerm_network_security_group.firezone.id
+}
+
+output "nat_public_ip" {
+  description = "The public IP of the NAT gateway"
+  value       = azurerm_public_ip.firezone.ip_address
+}
+
+output "bastion_public_ip" {
+  description = "The public IP of the bastion host"
+  value       = azurerm_public_ip.firezone-bastion.ip_address
+}

terraform/examples/google-cloud/nat-gateway/main.tf

@@ -1,4 +1,4 @@
-module "gateway_gcp_example" {
+module "google_firezone_gateway" {
   source = "github.com/firezone/firezone/terraform/modules/google-cloud/apps/gateway-region-instance-group"
   # If you are changing this example along with the module, you should use the local path:
   # source = "../../../modules/google-cloud/apps/gateway-region-instance-group"

terraform/modules/azure/firezone-gateway/main.tf

@@ -0,0 +1,61 @@
+resource "azurerm_orchestrated_virtual_machine_scale_set" "firezone" {
+  name                        = "firezone-vmss"
+  location                    = var.resource_group_location
+  resource_group_name         = var.resource_group_name
+  sku_name                    = var.instance_type
+  instances                   = var.desired_capacity
+  platform_fault_domain_count = var.platform_fault_domain_count
+
+  source_image_reference {
+    publisher = var.source_image_reference.publisher
+    offer     = var.source_image_reference.offer
+    sku       = var.source_image_reference.sku
+    version   = var.source_image_reference.version
+  }
+
+  network_interface {
+    name    = "firezone-nic"
+    primary = true
+
+    # Required to egress traffic
+    enable_ip_forwarding = true
+
+    network_security_group_id = var.network_security_group_id
+
+    ip_configuration {
+      name      = "internal"
+      primary   = true
+      subnet_id = var.private_subnet
+    }
+  }
+
+  os_profile {
+    linux_configuration {
+      admin_username = var.admin_username
+
+      admin_ssh_key {
+        username   = var.admin_username
+        public_key = var.admin_ssh_key
+      }
+    }
+
+    custom_data = base64encode(<<-EOF
+    #!/bin/bash
+    set -e
+
+    sudo apt-get update
+    sudo apt-get install -y curl uuid-runtime
+
+    FIREZONE_TOKEN="${var.firezone_token}" \
+    FIREZONE_VERSION="${var.firezone_version}" \
+    FIREZONE_NAME="${var.firezone_name}" \
+    FIREZONE_ID="$(uuidgen)" \
+    FIREZONE_API_URL="${var.firezone_api_url}" \
+    bash <(curl -fsSL https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-systemd-install.sh)
+
+    EOF
+    )
+  }
+
+  tags = var.extra_tags
+}

terraform/modules/azure/firezone-gateway/variables.tf

@@ -0,0 +1,100 @@
+variable "resource_group_location" {
+  description = "The location for the resource group"
+  type        = string
+}
+
+variable "resource_group_name" {
+  description = "The name of the resource group"
+  type        = string
+}
+
+variable "source_image_reference" {
+  description = "The source image reference for the instances"
+  type = object({
+    publisher = string
+    offer     = string
+    sku       = string
+    version   = string
+  })
+
+  default = {
+    publisher = "Canonical"
+    offer     = "0001-com-ubuntu-server-jammy"
+    sku       = "22_04-lts"
+    version   = "latest"
+  }
+}
+
+variable "instance_type" {
+  description = "The instance type"
+  type        = string
+  default     = "Standard_B1ls"
+}
+
+variable "desired_capacity" {
+  description = "The desired number of instances"
+  type        = number
+  default     = 3
+}
+
+variable "admin_username" {
+  description = "The admin username"
+  type        = string
+  default     = "firezone"
+}
+
+variable "admin_ssh_key" {
+  description = "The admin SSH public key"
+  type        = string
+}
+
+variable "firezone_token" {
+  description = "The Firezone token"
+  type        = string
+  sensitive   = true
+}
+
+variable "firezone_version" {
+  description = "The Gateway version to deploy"
+  type        = string
+  default     = "latest"
+}
+
+variable "firezone_name" {
+  description = "Name for the Gateways used in the admin portal"
+  type        = string
+  default     = "$(hostname)"
+}
+
+variable "firezone_api_url" {
+  description = "The Firezone API URL"
+  type        = string
+  default     = "wss://api.firezone.dev"
+}
+
+variable "private_subnet" {
+  description = "The private subnet ID"
+  type        = string
+}
+
+variable "network_security_group_id" {
+  description = "The network security group id to attach to the instances"
+  type        = string
+}
+
+variable "extra_tags" {
+  description = "Extra tags to attach to the instances"
+  type        = map(string)
+  default     = { "Name" = "firezone-gateway-instance" }
+}
+
+variable "platform_fault_domain_count" {
+  description = "The number of fault domains"
+  type        = number
+  default     = 3
+}
+
+variable "nat_gateway_id" {
+  description = "The NAT gateway ID"
+  type        = string
+}

website/src/app/kb/administer/troubleshooting/readme.mdx

@@ -13,7 +13,25 @@ If you're trying to deploy a new Gateway and it's not connecting, try running
 some of the troubleshooting commands below to diagnose the issue.
 
 <TabsGroup>
-<TabsItem title="Docker" active>
+<TabsItem title="Terraform" active>
+
+If you deployed the Gateway using one of our [Terraform examples](/kb/automate),
+the Gateways are configured using the systemd deployment method.
+
+Obtain a shell on the affected Gateway and check the status of the service:
+
+```bash
+sudo systemctl status firezone-gateway
+```
+
+Check the logs with:
+
+```bash
+sudo journalctl -u firezone-gateway.service
+```
+
+</TabsItem>
+<TabsItem title="Docker">
 
 Check that the container is running:
 

website/src/app/kb/automate/readme.mdx

@@ -45,6 +45,19 @@ Firezone on your infrastructure.
 
   </KbCard>
   <KbCard
+    title="Deploy Firezone on Azure"
+    href="/kb/automate/terraform/azure"
+    logo={
+    <div>
+      <Image width={200} height={200} alt="Terraform" src="/images/kb/automate/terraform-logo.svg" className="mx-auto mb-8" />
+      <FaPlus size={32} className="mx-auto mb-8" />
+      <Image width={150} height={150} alt="Azure" src="/images/kb/automate/azure-logo.svg" className="mx-auto mb-8" />
+    </div>
+    }>
+    Deploy a scalable cluster of Firezone Gateways behind a NAT gateway on Azure
+    with a single egress IP.
+    </KbCard>
+    <KbCard
     title="Deploy with Compose"
     href="/kb/automate/docker-compose"
     logo={

website/src/app/kb/automate/terraform/aws/readme.mdx

@@ -1,5 +1,6 @@
 import SupportOptions from "@/components/SupportOptions";
 import Alert from "@/components/DocsAlert";
+import Image from "next/image";
 
 # Deploy Firezone on AWS with Terraform
 
@@ -13,6 +14,8 @@ Use this guide to give your Firezone Clients a static, public IP address for
 egress traffic to particular Resource(s). Here are some common use cases for
 this example:
 
+- Access your AWS resources using more cost-effective, higher performance
+  alternative to AWS Client VPN.
 - Use an IP allowlist to access a third-party or partner application such as a
   client's DB or third-party API.
 - Use an IP allowlist with your identity provider to lock down access to a
@@ -33,10 +36,10 @@ load balance for each other.
 1. A [Firezone Site](https://www.firezone.dev/kb/deploy/sites) dedicated to use
    for this example. This Site should contain **only** the Firezone Gateway(s)
    deployed in this example and any associated Resources.
-1. A Firezone Gateway token. See
-   [Multiple Gateways](/kb/deploy/gateways#deploy-multiple-gateways) for
-   instructions on how to obtain a Firezone Gateway token that can be used
-   across multiple instances.
+1. A Firezone Gateway token. This can be obtained by viewing your Site in the
+   admin portal, clicking the `Deploy Gateway` button, and navigating to the
+   instructions for the `AWS` tab. Gateway tokens support multi-use, so only a
+   single token is needed to provision the Firezone Gateways in this guide.
 
 ## Sizing
 
@@ -65,11 +68,35 @@ You can see the IP addresses assigned to the NAT Gateway in the Terraform
 output. These are the IP addresses that your Firezone Gateway(s) will share to
 egress traffic.
 
+<Image
+  src="/images/kb/automate/terraform/azure/gateways.png"
+  alt="Firezone Gateways in the Azure portal"
+  width={800}
+  height={600}
+/>
+
+<Alert color="info">
+  It can take a few minutes for the Firezone Gateway(s) to provision and connect
+  to the portal. If you suspect the Gateway(s) are not connecting, follow the
+  instructions in the [troubleshooting guide](/kb/administer/troubleshooting) to
+  diagnose the issue.
+</Alert>
+
+After a few minutes, you should see the Firezone Gateway(s) appear in the
+Firezone admin portal. You can now configure your Resources to use the new
+Firezone Gateway(s) you just provisioned.
+
 ## Upgrading
 
-To upgrade the Firezone Gateway(s) to the latest version, simply update the
-`token` and issue a `terraform apply` which will trigger a redeployment of the
-Firezone Gateway(s).
+To upgrade the Firezone Gateway(s) to the latest version, we recommend setting a
+version to deploy with the `firezone_version` variable. Then, whenever you want
+to upgrade, update this variable and run `terraform apply`, which will trigger a
+new deployment of the Firezone Gateway(s) with the new version.
+
+<Alert color="info">
+  You can follow the latest releases of the Gateway at our [changelog
+  page](https://www.firezone.dev/changelog).
+</Alert>
 
 This will incur a few minutes of downtime as Terraform destroys the existing
 Firezone Gateway(s) and deploys new ones in their place.

website/src/app/kb/automate/terraform/azure/_page.tsx

@@ -0,0 +1,6 @@
+"use client";
+import Content from "./readme.mdx";
+
+export default function _Page() {
+  return <Content />;
+}

website/src/app/kb/automate/terraform/azure/page.tsx

@@ -0,0 +1,17 @@
+import { Metadata } from "next";
+import _Page from "./_page";
+import LastUpdated from "@/components/LastUpdated";
+
+export const metadata: Metadata = {
+  title: "Deploy Firezone on Azure • Firezone Docs",
+  description: "Example Terraform configuration to deploy Firezone on Azure.",
+};
+
+export default function Page() {
+  return (
+    <>
+      <_Page />
+      <LastUpdated dirname={__dirname} />
+    </>
+  );
+}

website/src/app/kb/automate/terraform/azure/readme.mdx

@@ -0,0 +1,123 @@
+import SupportOptions from "@/components/SupportOptions";
+import Alert from "@/components/DocsAlert";
+import Image from "next/image";
+
+# Deploy Firezone on Azure with Terraform
+
+In this guide, we'll deploy a cluster of Firezone Gateways in a private subnet
+on Azure that are configured to egress traffic to the internet through an
+[Azure NAT Gateway](https://azure.microsoft.com/en-us/products/azure-nat-gateway).
+
+## Common use cases
+
+Use this guide to give your Firezone Clients a static, public IP address for
+egress traffic to particular Resource(s). Here are some common use cases for
+this example:
+
+- Access your protected Azure workloads using with scalable, high-performance
+  WireGuard tunnels.
+- Use an IP allowlist to access a third-party or partner application such as a
+  client's DB or third-party API.
+- Use an IP allowlist with your identity provider to lock down access to a
+  public application.
+- Enabling a team of remote contractors access to a regionally-locked
+  application or service.
+
+## High availability
+
+All Firezone Gateways deployed in this example will automatically failover and
+load balance for each other.
+
+## Prerequisites
+
+1. [Terraform](https://www.terraform.io/downloads.html)
+1. [Azure account](https://portal.azure.com) with the necessary permissions to
+   create the resources.
+1. Set up your Terraform environment to work with Azure. See
+   [this tutorial](https://developer.hashicorp.com/terraform/tutorials/azure-get-started/azure-build)
+   if you haven't yet done so.
+1. A [Firezone Site](https://www.firezone.dev/kb/deploy/sites) dedicated to use
+   for this example. This Site should contain **only** the Firezone Gateway(s)
+   deployed in this example and any associated Resources.
+1. A Firezone Gateway token. This can be obtained by viewing your Site in the
+   admin portal, clicking the `Deploy Gateway` button, and navigating to the
+   instructions for the `Azure` tab. Gateway tokens support multi-use, so only a
+   single token is needed to provision the Firezone Gateways in this guide.
+
+## Sizing
+
+Simply update the number of `desired_capacity` to deploy more or fewer Firezone
+Gateways. There's no limit to the number of Firezone Gateways you can deploy in
+a single Vnet. A basic Azure Autoscale configuration is provisioned as part of
+the linked module.
+
+We've tested with `Standard_B1ls` instances which still work quite well for most
+applications. However, you may want to consider a larger instance type if you
+have a high volume of traffic or lots of concurrent connections.
+
+## Deployment
+
+1. [Download](https://raw.githubusercontent.com/firezone/firezone/main/terraform/examples/azure/nat-gateway/main.tf)
+   the `main.tf` from the example module.
+1. Customize it as desired. At a minimum, you will need to set the
+   `firezone_token` and change `admin_ssh_key` to match your environment.
+1. Run `terraform init` to initialize the working directory and download the
+   required providers.
+1. Run `terraform apply` to deploy the Firezone Gateway(s) into your AWS
+   project.
+
+You can see the IP address assigned to the NAT Gateway in the Terraform output.
+These are the IP address that your Firezone Gateway(s) will share to egress
+traffic.
+
+<Image
+  src="/images/kb/automate/terraform/azure/gateways.png"
+  alt="Firezone Gateways in the Azure portal"
+  width={800}
+  height={600}
+/>
+
+<Alert color="info">
+  It can take a few minutes for the Firezone Gateway(s) to provision and connect
+  to the portal. If you suspect the Gateway(s) are not connecting, follow the
+  instructions in the [troubleshooting guide](/kb/administer/troubleshooting) to
+  diagnose the issue.
+</Alert>
+
+<Alert color="warning">
+  Azure disables ICMP for VMs without a public IP attached, so you won't be able
+  to ping internet hosts from the Firezone Gateway(s) or vice versa. This is
+  normal and expected. TCP and UDP traffic will work as expected using the
+  example configuration in this guide.
+</Alert>
+
+After a few minutes, you should see the Firezone Gateway(s) appear in the
+Firezone admin portal. You can now configure your Resources to use the new
+Firezone Gateway(s) you just provisioned.
+
+## Upgrading
+
+To upgrade the Firezone Gateway(s) to the latest version, we recommend setting a
+version to deploy with the `firezone_version` variable. Then, whenever you want
+to upgrade, update this variable and run `terraform apply`, which will trigger a
+new deployment of the Firezone Gateway(s) with the new version.
+
+<Alert color="info">
+  You can follow the latest releases of the Gateway at our [changelog
+  page](https://www.firezone.dev/changelog).
+</Alert>
+
+This will incur a few minutes of downtime as Terraform destroys the existing
+Firezone Gateway(s) and deploys new ones in their place.
+
+## Output
+
+`nat_public_ip` will contain the public IP address of the NAT Gateway you can
+use to whitelist your Firezone Gateway(s) in your third-party or partner
+application.
+
+# Cleanup
+
+To clean up the resources created by this example, run `terraform destroy`.
+
+<SupportOptions />

website/src/app/kb/automate/terraform/gcp/readme.mdx

@@ -38,10 +38,10 @@ load balance for each other. No other configuration is necessary.
 1. A [Firezone Site](/kb/deploy/sites) dedicated to use for this example. This
    Site should contain **only** the Firezone Gateway(s) deployed in this example
    and any associated Resources.
-1. A Firezone Gateway token. See
-   [Multiple Gateways](/kb/deploy/gateways#deploy-multiple-gateways) for
-   instructions on how to obtain a Firezone Gateway token that can be used
-   across multiple instances.
+1. A Firezone Gateway token. This can be obtained by viewing your Site in the
+   admin portal, clicking the `Deploy Gateway` button, and navigating to the
+   instructions for the `GCP` tab. Gateway tokens support multi-use, so only a
+   single token is needed to provision the Firezone Gateways in this guide.
 
 ## Sizing
 
@@ -94,12 +94,18 @@ listed as `Online`.
 
 ## Upgrading
 
-To upgrade the Firezone Gateway(s) to the latest version, simply update the
-`token` and issue a `terraform apply` which will trigger a redeployment of the
-Firezone Gateway(s).
+To upgrade the Firezone Gateway(s) to the latest version, we recommend setting a
+version to deploy with the `vsn` variable. Then, whenever you want to upgrade,
+update this variable and run `terraform apply`, which will trigger a new
+deployment of the Firezone Gateway(s) with the new version.
 
-This will incur about a minute or two of downtime as Terraform destroys the
-existing Firezone Gateway(s) and deploys new ones in their place.
+<Alert color="info">
+  You can follow the latest releases of the Gateway at our [changelog
+  page](https://www.firezone.dev/changelog).
+</Alert>
+
+This will incur a few minutes of downtime as Terraform destroys the existing
+Firezone Gateway(s) and deploys new ones in their place.
 
 ## Output
 

website/src/app/kb/use-cases/saas-app-access/readme.mdx

@@ -27,9 +27,8 @@ into an **app connector** for SaaS applications that support IP allowlists.
   haven't already.
 - One or more Gateways deployed within the Site in a NAT Gateway configuration.
   See [Route traffic through a public IP](/kb/use-cases/nat-gateway) for how to
-  deploy a single NAT Gateway, or see our
-  [Terraform examples](https://www.github.com/firezone/firezone/tree/main/terraform/examples)
-  for examples on how to automate deploying multiple Gateways to various cloud
+  deploy a single NAT Gateway, or see our [Terraform examples](/kb/automate) for
+  examples on how to automate deploying multiple Gateways to various cloud
   providers.
 - Any SaaS app that supports IP allowlists, configured to allow the public IP
   address(es) of the Gateway(s) you want to use.

website/src/app/kb/use-cases/scale-vpc-access/readme.mdx

@@ -31,10 +31,8 @@ balanced across multiple Gateways for high availability.
   [Deploy a Gateway](/kb/deploy/gateways) if you haven't done so yet.
 
 <Alert color="info">
-  See our [Terraform
-  examples](https://www.github.com/firezone/firezone/tree/main/terraform/examples)
-  for examples on how to automate deploying multiple Gateways to various cloud
-  providers.
+  See our [Terraform examples](/kb/automate) to learn how to automate
+  deployments to various cloud providers.
 </Alert>
 
 ## Step 1: Create a Resource

website/src/components/KbSidebar/index.tsx

@@ -68,6 +68,9 @@ export default function KbSidebar() {
             <SidebarItem href="/kb/automate/terraform/gcp">
               Terraform + GCP
             </SidebarItem>
+            <SidebarItem href="/kb/automate/terraform/azure">
+              Terraform + Azure
+            </SidebarItem>
             <SidebarItem href="/kb/automate/docker-compose">
               Docker Compose
             </SidebarItem>