☁️ Azure SQL Server DNS Alias Terraform Module

A stable hostname that points at an Azure SQL logical server, so the server behind it can change without touching a connection string. Targets hashicorp/azurerm ~> 4.0.

• 🔗 Publishes <alias>.database.windows.net, pointing at a SQL logical server.
• 🌍 The name is globally unique across Azure, sharing a namespace with server names — so a first apply can fail for reasons outside your subscription.
• 🔴 This module cannot repoint an alias without dropping it. Both arguments are force-new, so a change is a delete and a create.
• 📏 Mirrors the provider's name rule including a two-character minimum its own error message does not mention.
• 🔁 No update function exists, so only three timeouts are real — and delete defaults to 10 minutes, not 30.

💡 Why it matters: the point of an alias is to survive a server change. But mssql_server_id is force-new here, so repointing it in Terraform destroys the alias and recreates it — the hostname stops resolving in between, during exactly the cutover the alias was meant to smooth. Azure has an acquire operation that moves an alias without dropping it; the provider does not expose it.

If this module saved you time:

• ⭐ Star the repository
• 💼 Connect on LinkedIn
• ☕ Buy me a coffee

flowchart TB
    SRV["terraform-azurerm-mssql-server"]
    THIS["terraform-azurerm-mssql-server-dns-alias"]
    OFR["terraform-azurerm-mssql-outbound-firewall-rule"]
    DB["terraform-azurerm-mssql-database"]
    SAP["terraform-azurerm-mssql-server-security-alert-policy"]

    SRV -->|"id as mssql_server_id"| THIS
    SRV -->|"id as server_id"| OFR
    SRV -->|"id"| DB
    SRV -->|"name and resource_group_name"| SAP
    THIS -.->|"applications connect here instead of the server"| SRV

    style THIS fill:#0078D4,stroke:#004578,color:#ffffff
    style SRV fill:#004578,stroke:#004578,color:#ffffff
    style OFR fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style DB fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style SAP fill:#F3F2F1,stroke:#8A8886,color:#201F1E

The two edges from the server are labelled with the argument names because they differ: mssql_server_id here, server_id on the outbound firewall rule — same server, same provider release. The dotted edge back is the whole purpose of the resource: applications connect through the alias rather than to the server, which is what lets the server be replaced underneath them.

flowchart TB
    NAME["name (force-new) -- a GLOBAL DNS label"]
    SID["mssql_server_id (force-new)"]

    ALIAS["azurerm_mssql_server_dns_alias.this"]

    OID["id"]
    OREC["dns_record, read back from Azure"]
    OHOST["server_hostname, what the alias replaces"]
    ONOMOVE["this_module_cannot_repoint_an_alias_without_dropping_it"]

    NAME --> ALIAS
    SID --> ALIAS
    ALIAS --> OID
    ALIAS --> OREC
    ALIAS --> OHOST
    ALIAS --> ONOMOVE

    style ALIAS fill:#0078D4,stroke:#004578,color:#ffffff
    style NAME fill:#004578,stroke:#004578,color:#ffffff
    style SID fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style OID fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style OREC fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style OHOST fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style ONOMOVE fill:#F3F2F1,stroke:#8A8886,color:#201F1E

Schema notes that bite:

• 🔴 Both arguments are force-new, so repointing the alias is a delete-then-create and the hostname stops resolving in between. Azure's acquire operation, which moves an alias without dropping it, is not exposed by the provider.
• 🔴 The name is a GLOBAL DNS label, in the same namespace as SQL server names — a name taken by anyone else's server or alias fails at apply, and nothing in a plan can foresee it.
• 🔴 The name rule enforces a two-character minimum the provider's own error message does not mention: its regex requires a leading and a trailing alphanumeric.
• 🔴 There is no update function. The schema exposes only create, read and delete timeouts — timeouts.update is a non-existent attribute, not an ignored one, and Terraform would discard it silently.
• ⚠️ The parent argument is mssql_server_id here and server_id on the sibling outbound firewall rule.
• ⚠️ The delete timeout defaults to 10 minutes, not the 30 used by most neighbours in this family.
• ℹ️ There IS a requires-import guard on create, so a clean apply is evidence the alias did not exist in your subscription — but not that the global name was free.
• ℹ️ dns_record is computed, read back from the service.
• ℹ️ No tags, no location.

⚠️ Whoever can delete this resource can break every connection string pointed at the alias, instantly. The permission reads like a naming concern and behaves like an availability one.

ℹ️ No permission outside the subscription is involved, even though the name is globally scoped — the uniqueness check happens at apply, not through RBAC.

• The Microsoft.Sql resource provider registered on the subscription.
• An existing Azure SQL logical server.
• A globally available alias name. It shares a namespace with every SQL server name in Azure.
• The caller configures provider "azurerm" { features {} }, auth and subscription.

terraform-azurerm-mssql-server-dns-alias/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # 3 inputs, deeply typed, with the global-name rule
├── main.tf         # the single keystone `this`
├── outputs.tf      # id first, then both hostnames, then the posture facts
├── README.md       # this file
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore

provider "azurerm" {
  features {}
}

module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id
}

Applications now connect to orders-db.database.windows.net. Read example 3 before planning a migration around it — this module cannot move the alias to a different server without dropping it.

Consumes

Emits

module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id
}

output "connection_hosts" {
  value = {
    connect_here     = module.sql_alias.dns_record      # orders-db.database.windows.net
    instead_of_here  = module.sql_alias.server_hostname # sql-platform-eus2.database.windows.net
  }
}

output "sanity_check" {
  value = {
    reported = module.sql_alias.dns_record        # read back from Azure
    expected = module.sql_alias.expected_hostname # derived from `name`
  }
}

# Changing `mssql_server_id` DESTROYS the alias and recreates it.
module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id # <-- pointing this elsewhere: delete then create
}

output "warning" {
  value = module.sql_alias.this_module_cannot_repoint_an_alias_without_dropping_it # true
}

# REFUSED -- the provider's regex requires a leading AND a trailing alphanumeric:
#   name = "a"
#
# ACCEPTED:
module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "ab"
  mssql_server_id = module.sql_server.id
}

module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "sql" # almost certainly taken by someone, somewhere
  mssql_server_id = module.sql_server.id
}

# GOOD -- survives the server being replaced:
#   name = "orders-db"
#
# SELF-DEFEATING -- names the thing the alias exists to hide:
#   name = "sql-platform-eus2-alias"
module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id
}

# Editing `name` destroys one alias and creates another.

module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id

  timeouts = {
    create = "45m"
    delete = "15m" # the provider's default here is 10, not 30
  }
}

module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id # <-- mssql_server_id
}

module "sql_outbound_storage" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-outbound-firewall-rule.git?ref=v1.0.0"

  name      = "stsqlaudit0001.blob.core.windows.net"
  server_id = module.sql_server.id # <-- server_id
}

module "sql_alias" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"
  for_each = module.sql_servers

  name            = "${each.key}-db"
  mssql_server_id = each.value.id
}

output "connection_hosts" {
  value = { for k, m in module.sql_alias : k => m.dns_record }
}

output "audit" {
  value = {
    should_connect_to  = module.sql_alias.dns_record
    must_not_appear_in_config = module.sql_alias.server_hostname
    point_of_the_alias = module.sql_alias.connecting_through_the_alias_is_the_whole_point
  }
}

provider "azurerm" {
  features {}
}

module "sql_server" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server.git?ref=v1.0.0"

  name                = "sql-platform-eus2"
  resource_group_name = "rg-data-platform"
  location            = "eastus2"

  azuread_administrator = {
    login_username = "sql-admins"
    object_id      = var.sql_admin_group_object_id
  }
}

module "orders_db" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-database.git?ref=v1.0.0"

  name      = "orders"
  server_id = module.sql_server.id
}

# The stable hostname applications use. Named for the application, so it
# survives the server being replaced.
module "sql_alias" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-server-dns-alias.git?ref=v1.0.0"

  name            = "orders-db"
  mssql_server_id = module.sql_server.id
}

# Outbound rules govern traffic FROM the server; the alias governs how clients
# reach it. Orthogonal, and both usually needed.
module "sql_outbound_audit" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-mssql-outbound-firewall-rule.git?ref=v1.0.0"

  name      = "stsqlaudit0001.blob.core.windows.net"
  server_id = module.sql_server.id
}

output "application_connection" {
  value = {
    host     = module.sql_alias.dns_record
    database = module.orders_db.name
    # Deliberately emitted so a reviewer can confirm it appears NOWHERE else.
    do_not_use = module.sql_alias.server_hostname
  }
}

Identity — name (required, force-new, globally unique), mssql_server_id (required, force-new). Tail — timeouts, with three keys. (There is no tags: the resource exposes none.)

🔒 No secret is accepted or emitted.

The alias exists to outlive a server, and this resource cannot move it. That tension is the module's central fact. mssql_server_id is force-new, so repointing the alias in Terraform destroys it and creates it again — and the hostname stops resolving in between, during precisely the cutover the alias was meant to make invisible. Azure's acquire operation moves an alias between servers without dropping it; the provider does not expose it, so that move belongs outside Terraform and is reconciled into state afterwards. The module emits this rather than letting it be discovered by a plan showing -/+.

The name is global, and a plan cannot see that. The alias shares a namespace with every SQL server name in Azure, so a first apply can fail because of a resource in someone else's subscription. The requires-import guard checks your subscription only — a clean plan is not evidence the name is free.

One rule is stricter than its own error message. The provider's regex requires a leading and a trailing alphanumeric, which makes a one-character alias illegal — while the message it prints talks only about permitted characters and hyphen placement. This module mirrors the regex exactly and says the minimum out loud, because otherwise the failure reads as being about something else.

There is genuinely no update. Both arguments are force-new, so the schema carries three timeouts rather than four. timeouts.update is not ignored here — it is not an attribute of the type, and an undeclared key is discarded silently by Terraform's object-type conversion. The module declares three and emits their real defaults, including a delete deadline of 10 minutes rather than the family's usual 30.

Two hostnames are emitted on purpose. dns_record is what the service says; server_hostname is what the alias replaces. Putting both in the outputs makes the substitution greppable — the server hostname should appear in no application configuration anywhere.

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

Pin the module with ?ref=v1.0.0 — never a branch. This module is plan-only in this repository; a human applies from CI.

terraform validate proves, offline and with no credentials: the name rule in both directions — uppercase, underscores, leading and trailing hyphens, a dotted hostname and the undocumented one-character case are all refused, while two-character, hyphenated and digit-bearing names pass — and that mssql_server_id is an anchored SQL server ID rather than a managed instance.

Only terraform plan and apply exercise: whether the server exists, whether the alias already exists in your subscription, and whether the name is available globally.

Nothing at either stage tells you that repointing will drop the hostname, or that the alias is not actually being used. That is what the constant outputs and the paired hostnames are for.

Note the asymmetry: a validation failure blocks terraform destroy as well as apply, which is why the name check mirrors the provider's regex exactly rather than adding to it.

id                = "/subscriptions/.../resourceGroups/rg-data-platform/providers/Microsoft.Sql/servers/sql-platform-eus2/dnsAliases/orders-db"
name              = "orders-db"
dns_record        = "orders-db.database.windows.net"
expected_hostname = "orders-db.database.windows.net"
server_hostname   = "sql-platform-eus2.database.windows.net"
server_name       = "sql-platform-eus2"
force_new_fields  = ["name", "mssql_server_id"]

• azurerm_mssql_server_dns_alias
• Microsoft.Sql/servers/dnsAliases template reference
• Azure SQL Database connectivity architecture
• Sibling modules: terraform-azurerm-mssql-server, terraform-azurerm-mssql-outbound-firewall-rule, terraform-azurerm-mssql-database, terraform-azurerm-mssql-server-security-alert-policy
• This module's SCOPE.md

💙 "Infrastructure as Code should be standardized, consistent, and secure."