☁️ Azure SSH Public Key Terraform Module

module "platform_key" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-ssh-public-key.git?ref=v1.0.0"

  name                = "platform-team-key"
  resource_group_name = module.rg.name
  location            = module.rg.location
  public_key          = file("${path.module}/keys/platform-team.pub")
}

module "nic_vm" {
  source              = "git::https://github.com/microsoftexpert/terraform-azurerm-network-interface.git?ref=v1.0.0"
  name                = "nic-vm"
  resource_group_name = module.rg.name
  location            = module.rg.location

  ip_configurations = [{
    name      = "internal"
    subnet_id = var.vm_subnet_id
  }]
}

module "nic_vm" {
  source              = "git::https://github.com/microsoftexpert/terraform-azurerm-network-interface.git?ref=v1.0.0"
  name                = "nic-vm"
  resource_group_name = module.rg.name
  location            = module.rg.location

  ip_configurations = [{
    name      = "internal"
    subnet_id = module.vnet.subnet_ids["app"]
  }]
}

module "vm" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-linux-virtual-machine.git?ref=v1.0.0"

  network_interface_ids = [module.nic_vm.id]

  size                  = "Standard_D2s_v5"

  name                = "vm-app-01"
  resource_group_name = module.rg.name
  location            = module.rg.location

  # ✅ Key-based auth, password auth off — this suite's secure default.
  admin_username                  = "azureuser"
  disable_password_authentication = true

  admin_ssh_keys = [{
      username   = "azureuser"
      public_key = module.platform_key.public_key
    }]
}

ℹ️ The VM reads the key as a VALUE. There is no reference, no dependency the provider tracks beyond Terraform's own graph, and — crucially — no ongoing link (example 2).

💡 The point of this resource is reuse. One key object, referenced by every machine, beats the same file() call pasted into twenty configurations — and it gives you one place to look when asking "which key is on our machines?".

✅ Note disable_password_authentication = true on the VM. An SSH key resource is only worth having if password auth is off; this suite defaults it that way.

# Looks like a rotation. Is not one.
public_key = file("${path.module}/keys/platform-team-NEW.pub")

  ~ resource "azurerm_ssh_public_key" "this" {
      ~ public_key = "ssh-rsa AAAAB3...old" -> "ssh-rsa AAAAB3...new"
    }

🔴 That clean in-place update changes nothing on any existing machine. A VM copies the key into ~/.ssh/authorized_keys when it is provisioned. Afterwards the machine has its own copy and never consults this resource again.

⚠️ So after that apply: existing VMs still trust the OLD key, do not trust the NEW one, and the Terraform state looks entirely healthy. Anyone reading the plan would reasonably conclude the fleet had been re-keyed.

✅ What actually rotates a key, in increasing order of reliability:

1. Update this resource, so NEW machines get the new key.       <- what this module does
2. Push the new key to existing machines' authorized_keys,
   via a configuration-management tool or the VM run-command.
3. Remove the old key from those machines.
4. Rebuild the machines. The only step that is certainly complete.

💡 Step 1 without steps 2–4 is the failure mode, and it is a comfortable one to fall into because Terraform reports success. The module emits a constant flag to keep the fact in front of you:

output "rotation" { value = module.platform_key.rotation_requires_vm_change } # always true

ℹ️ A for_each over VMs referencing this key does not help either — changing the key value does not change the VMs' admin_ssh_key, because Azure treats that field as provisioning-time data.

public_key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@host" # ✅ preferred

public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB... user@host"      # ✅ also fine, use 4096 bits

ssh-keygen -t ed25519 -C "platform-team"          # preferred
ssh-keygen -t rsa -b 4096 -C "platform-team"      # if RSA is required elsewhere

🔴 AN EARLIER REVISION OF THIS MODULE REFUSED Ed25519 AND SAID AZURE DID NOT SUPPORT IT. Both were wrong. The provider's key validator explicitly handles ssh-ed25519 alongside ssh-rsa, and its own error message for anything else reads "Only RSA and ED25519 SSH keys are supported by Azure". The module was therefore refusing legal input — and because a failed validation {} blocks terraform destroy as well as apply, a caller who already held an Ed25519 key could not manage that resource through this module at all. It also steered people towards RSA, which is the weaker choice.

✅ The 2048-bit RSA floor IS enforced, at terraform validate. The provider does not merely pattern-match the prefix: it base64-decodes the key body, parses it into an SSH public key object, switches on the algorithm, and for RSA computes the modulus size and refuses anything under 2048 bits — all offline, before any credential is needed. An earlier revision of this module said the floor was "documented and not enforced", which was true of the module and false of the provider.

Error: Invalid value for variable

  public_key must be an OpenSSH public key beginning "ssh-rsa " or "ssh-ed25519 "
  followed by the base64 key body. ... An OpenSSH PRIVATE key block, a PEM
  certificate, or an ECDSA key are rejected.

ℹ️ key_body_length remains a rough proxy for eyeballing relative size. It is not the check — the provider's parser is — and it never needed to be.

output "size_hint" { value = module.platform_key.key_body_length } # a proxy, NOT a bit count

# ✅ The public half. Not secret, not marked sensitive.
public_key = file("${path.module}/keys/platform-team.pub")

🔒 This module deliberately does NOT mark public_key sensitive, and the reasoning is worth stating rather than assuming. A public key exists to be distributed — it goes on every machine you want to reach. Redacting it would hide it from plan review and protect nothing at all, while making the derived outputs unusable.

🔴 The private half must never come near this module. If you paste one by accident, the module catches it with its own message rather than a generic format error:

public_key = file("${path.module}/keys/platform-team") # ❌ no .pub — the PRIVATE key

Error: Invalid value for variable

  public_key appears to contain a PRIVATE key block. Stop: treat that key as
  compromised and generate a new pair. This resource takes only the public half, and
  anything passed here is written to Terraform state.

⚠️ That message says "treat it as compromised" for a reason. Depending on how far the plan got, the private key may already be in a state file, a CI log, or a plan artifact. "Fix the filename and re-run" is not sufficient; reissue the pair.

💡 Where the private half belongs: with the human or the CI system that authenticates, ideally generated on the machine that will use it and never transmitted at all. If it must be stored centrally, a Key Vault secret is the place — never a Terraform variable, and never this resource.

locals {
  keys = {
    platform = { file = "platform-team.pub", owner = "platform" }
    dba      = { file = "dba-team.pub", owner = "data" }
  }
}

module "ssh_keys" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-ssh-public-key.git?ref=v1.0.0"
  for_each = local.keys

  name                = "${each.key}-key"
  resource_group_name = module.rg.name
  location            = module.rg.location
  public_key          = file("${path.module}/keys/${each.value.file}")

  tags = { owner = each.value.owner }
}

ℹ️ for_each lives in the caller — the resource is one key per object, and the module reflects that.

💡 Separate keys per team beats one shared key, for the ordinary reason: revoking access for one team should not require re-keying everyone. And because rotation is genuinely awkward here (example 2), the narrower the blast radius of any single key, the better.

⚠️ Do not use one key across environments. A key that opens production and development means a development compromise is a production compromise, and the cost of separate keys is one extra module block.

✅ A VM can accept several admin_ssh_key entries, so per-team keys compose without forcing a choice.

data "azurerm_key_vault_secret" "platform_pub" {
  name         = "platform-team-public-key"
  key_vault_id = var.kv_id
}

module "platform_key" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-ssh-public-key.git?ref=v1.0.0"

  name                = "platform-team-key"
  resource_group_name = module.rg.name
  location            = module.rg.location
  public_key          = data.azurerm_key_vault_secret.platform_pub.value
}

ℹ️ A reasonable pattern when the key file should not live in the repository — for instance when it is generated by a process the repository does not own.

⚠️ But note what it costs. azurerm_key_vault_secret.value is a sensitive attribute, so Terraform marks it sensitive, and that mark propagates: public_key becomes redacted in plan output and the derived outputs become unusable. Sensitivity is contagious, and here it is contagion from a value that is not actually secret.

💡 So prefer a committed .pub file where you reasonably can. A public key in version control is not a leak — it is the normal way public keys are distributed, and it keeps plan output readable.

✅ If you do read from a vault, nonsensitive() is available — and is honest here, because the value genuinely is not secret:

public_key = nonsensitive(data.azurerm_key_vault_secret.platform_pub.value)

output "platform_key_review" {
  value = {
    id        = module.platform_key.id
    algorithm = module.platform_key.key_algorithm            # ssh-rsa or ssh-ed25519, parsed
    size_hint = module.platform_key.key_body_length          # a proxy, not a bit count
    rotation  = module.platform_key.rotation_requires_vm_change # always true
  }
}

⚠️ rotation is the line that matters, and it is a constant. It is in the outputs because the misunderstanding it guards against — "we rotated the key" — is one somebody reaches by reading a perfectly clean plan (example 2).

ℹ️ size_hint is a proxy and says so. A value in the low hundreds suggests 2048-bit; roughly double that suggests 4096. It is useful for spotting an obviously undersized key and useless as an assurance.

💡 What no output can tell you is which machines currently trust this key. That is a question for the machines, and it is exactly the question rotation depends on.

terraform import 'module.platform_key.azurerm_ssh_public_key.this' \
  "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-platform/providers/Microsoft.Compute/sshPublicKeys/platform-team-key"

✅ Importing is comfortable — only name, resource_group_name and location are force-new, and those three are all visible in the Resource ID itself.

⚠️ Restate public_key to match before the first plan, or the first apply will overwrite the stored key with whatever the configuration says. That is an in-place change rather than a replacement, so it is easy to miss in a plan — and it means new machines get a different key from the one you imported.

What a destroy removes

terraform destroy on this module:
  removes the stored key object  ->  every existing VM is COMPLETELY UNAFFECTED
                                 ->  they keep their copy in authorized_keys
                                 ->  and keep accepting that key indefinitely
                                 ->  only NEW machines lose the reference

🔴 Deleting this resource revokes nothing. It is the same asymmetry as example 2, in the other direction: the machines hold their own copies, so removing the stored key does not remove access.

⚠️ Which makes "delete the key object" the wrong response to a compromised key. The right response is on the machines — remove it from authorized_keys, or rebuild.

💡 To stop managing the object without deleting it, use terraform state rm.

This resource IS:      a stored public key, for machines to copy at provisioning time
This resource is NOT:  an access-control plane
                       an inventory of who can reach your machines
                       a revocation mechanism
                       a record of which machines trust which key

⚠️ The gap between the first line and the rest is where the trouble lives. A named key object in a resource group looks like a managed credential, and the natural assumption — that changing or deleting it changes access — is wrong in both directions (examples 2 and 8).

💡 So treat it as a distribution convenience, and keep the authority elsewhere. For real, auditable, revocable access to Linux machines, the mechanisms that actually work are:

Microsoft Entra ID login for Linux VMs   -> central identity, real revocation, RBAC
Azure Bastion + just-in-time access      -> no exposed SSH at all
a configuration-management tool           -> authoritative authorized_keys

✅ This module composes happily with all three. An SSH key for break-glass access plus Entra ID login for day-to-day is a reasonable design; an SSH key as the only access mechanism is the design that becomes hard to unwind.

ℹ️ None of this is a criticism of the resource, which does exactly what it says. It is a caution about what a reader infers from the words "SSH public key" sitting in an Azure resource group.

tags = {
  owner       = "platform"
  environment = "prod"
  rotation    = "2026-Q4" # when this key is next due to be replaced
}

✅ These are real Azure resource tags — a map(string) — which is worth saying explicitly if you have been working in the Sentinel part of this library, where the provider exposes no tags at all and one resource uses the name for a list of labels.

💡 A rotation-due tag is a genuinely useful convention here, precisely because nothing else tracks it. There is no expiry on an SSH key object, no warning, and no field for one — so a tag plus a report over tags is the cheapest thing that will ever remind you.

ℹ️ Tags update in place, so maintaining them costs nothing structural.

⚠️ They are metadata only. A tag saying rotation = "2026-Q4" does not rotate anything, and given example 2, neither does updating the key.

terraform init -backend=false
terraform validate
terraform fmt -check

✅ What that actually proves here: the key is ssh-rsa or ssh-ed25519 shaped, is not a private key, and the three force-new identity fields are non-empty. Everything else needs Azure.

💡 The validations were proved by evaluating them in terraform console inside the module, which does fire root-module variable validations — unlike terraform validate on a calling configuration. A pasted OpenSSH private key fired both checks at once: the format check and the private-key check.

ℹ️ An ssh-ed25519 key fires only the format check, which is the correct behaviour — it is a valid public key, just not one this resource accepts (example 3).

⚠️ No cloud apply happens in this flow. Everything here is plan-only static analysis until a human applies from CI.

provider "azurerm" {
  features {}
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-platform-prod"
  location = "eastus"
}

# ── Per-team keys, so revoking one team does not re-key everyone (example 5) ──
locals {
  keys = {
    platform = "platform-team.pub"
    dba      = "dba-team.pub"
  }
}

module "ssh_keys" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-ssh-public-key.git?ref=v1.0.0"
  for_each = local.keys

  name                = "${each.key}-key"
  resource_group_name = module.rg.name
  location            = module.rg.location

  # A committed .pub file: readable plans, and a public key in git is not a leak (example 6).
  public_key = file("${path.module}/keys/${each.value}")

  tags = {
    owner    = each.key
    rotation = "2026-Q4" # nothing else tracks this (example 10)
  }
}

module "vnet" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-virtual-network.git?ref=v1.0.0"

  name                = "vnet-platform-prod"
  resource_group_name = module.rg.name
  location            = module.rg.location
  address_space       = ["10.10.0.0/16"]

  subnets = {
    app = { address_prefixes = ["10.10.1.0/24"] }
  }
}

module "vm" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-linux-virtual-machine.git?ref=v1.0.0"

  network_interface_ids = [module.nic_vm.id]

  name                = "vm-app-01"
  resource_group_name = module.rg.name
  location            = module.rg.location
  size                = "Standard_D2s_v5"
  # ✅ No public IP, password auth off, keys only — this suite's secure defaults.
  admin_username                  = "azureuser"
  disable_password_authentication = true

  # Both team keys. A VM accepts several (example 5).
  admin_ssh_keys = [for k, m in module.ssh_keys : {
      username   = "azureuser"
      public_key = m.public_key
    }]
}

output "key_posture" {
  value = {
    ids = { for k, m in module.ssh_keys : k => m.id }
    # Always true, for every key. Read it before planning a rotation (example 2).
    rotation_needs_vm_change = [for k, m in module.ssh_keys : k if m.rotation_requires_vm_change]
  }
}

🔒 What the composition gets right: per-team keys rather than one shared key, committed .pub files so plans stay readable and nothing sensitive is contaminated, password authentication disabled on the VM, no public IP, a rotation-due tag because nothing else tracks it, and the private halves nowhere in sight.

⚠️ What no plan will tell you: which keys the running machines currently trust. That is the only fact rotation depends on, and it lives on the machines (examples 2, 8 and 9).

💡 rotation_needs_vm_change lists every key — always, by construction. It is there to be read by whoever is about to change a .pub file and believe they have re-keyed the fleet.