☁️ Azure Synapse Linked Service Terraform Module

module "lake_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-curated"
  synapse_workspace_id = module.workspace.id
  description          = "Curated zone of the analytics data lake"

  type = "AzureBlobFS"
  type_properties_json = jsonencode({
    url = module.lake.primary_dfs_endpoint
  })
}

# 1. A linked service that IS the vault.
module "vault_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-keyvault"
  synapse_workspace_id = module.workspace.id

  type = "AzureKeyVault"
  type_properties_json = jsonencode({
    baseUrl = module.kv.vault_uri
  })
}

# 2. A connection that NAMES it, rather than embedding the password.
module "sql_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-sql-reporting"
  synapse_workspace_id = module.workspace.id

  type = "AzureSqlDatabase"
  type_properties_json = jsonencode({
    connectionString = "Server=tcp:sqlsrv.database.windows.net;Database=reporting;User ID=svc_reporting;"
    password = {
      type       = "AzureKeyVaultSecret"
      secretName = "sql-reporting-password"
      store = {
        referenceName = module.vault_connection.name
        type          = "LinkedServiceReference"
      }
    }
  })
}

module "lake_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-curated"
  synapse_workspace_id = module.workspace.id

  type = "AzureBlobFS"

  # A FRAGMENT, not an object. The provider interpolates this raw text into a
  # JSON wrapper, so the second key escapes into the PARENT object.
  type_properties_json = "{}, \"type\": \"AzureKeyVault\""
}

module "lake_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-curated"
  synapse_workspace_id = module.workspace.id

  type                 = "AzureBlobFS"
  type_properties_json = jsonencode({ url = module.lake.primary_dfs_endpoint })

  additional_properties = {
    type = "AzureKeyVault" # <-- merged LAST, so it wins
  }
}

module "sql_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-sql-reporting"
  synapse_workspace_id = module.workspace.id

  type                 = "AzureSQLDatabase" # <-- rejected
  type_properties_json = jsonencode({ connectionString = "Server=x" })
}

module "self_hosted_runtime" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-integration-runtime-self-hosted.git?ref=v1.0.0"

  name                 = "ir-onprem-selfhosted"
  synapse_workspace_id = module.workspace.id
}

module "onprem_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-onprem-sql"
  synapse_workspace_id = module.workspace.id

  type = "SqlServer"
  type_properties_json = jsonencode({
    connectionString = "Server=onprem-sql01;Database=erp;Integrated Security=False;User ID=svc_synapse;"
  })

  integration_runtime = {
    name = module.self_hosted_runtime.name
  }
}

module "parameterised_lake" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-parameterised"
  synapse_workspace_id = module.workspace.id

  type = "AzureBlobFS"
  type_properties_json = jsonencode({
    url = "https://@{linkedService().accountName}.dfs.core.windows.net"
  })

  # name => DEFAULT VALUE. Every parameter is typed as a string.
  parameters = {
    accountName = "stanalyticsprod01"
  }
}

module "lake_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-curated"
  synapse_workspace_id = module.workspace.id

  type                 = "AzureBlobFS"
  type_properties_json = jsonencode({ url = module.lake.primary_dfs_endpoint })

  # Studio labels. No Azure Policy, cost report or tag inheritance sees these.
  annotations = ["prod", "curated-zone", "owner:analytics-platform"]
}

locals {
  connections = {
    lake  = module.lake_connection
    sql   = module.sql_connection
    vault = module.vault_connection
  }

  # A connection that looks like it needs a credential and does not reference one.
  credential_bearing_types = ["AzureSqlDatabase", "SqlServer", "Snowflake", "Odbc", "RestService"]

  secrets_possibly_inline = [
    for k, m in local.connections : k
    if contains(local.credential_bearing_types, m.type) && !m.references_a_key_vault_linked_service
  ]

  overridden = [for k, m in local.connections : k if !m.type_was_not_overridden]
}

output "linked_service_review" {
  value = {
    types                    = { for k, m in local.connections : k => m.type }
    property_names           = { for k, m in local.connections : k => m.type_properties_keys }
    default_runtime          = [for k, m in local.connections : k if m.uses_the_default_integration_runtime]
    secrets_possibly_inline  = local.secrets_possibly_inline
    types_that_do_not_match  = local.overridden
  }
}

check "linked_service_types_are_what_we_asked_for" {
  assert {
    condition     = alltrue([for k, m in local.connections : m.type_was_not_overridden])
    error_message = "A Synapse linked service was recorded with a different type than its configuration requested. This module rejects both override routes, so this means the artifact was written by something else -- an earlier configuration, a Studio edit, or a provider feature toggle that let a create overwrite it."
  }
}

# WRONG on a live workspace. `name` is force-new, and every pipeline, dataset
# and notebook references a linked service BY NAME.
#
#   name = "ls-adls-curated-v2"   # <-- destroys the old artifact
#
# The Terraform plan reads as a clean replacement. The workspace's artifacts
# do not: each one still names "ls-adls-curated", which no longer exists.
#
# RIGHT: create the new linked service alongside, repoint the artifacts, then
# remove the old module block on a later apply.

locals {
  linked_services = {
    lake_curated = { type = "AzureBlobFS", props = { url = "https://stanalyticsprod01.dfs.core.windows.net" } }
    lake_raw     = { type = "AzureBlobFS", props = { url = "https://strawprod01.dfs.core.windows.net" } }
    keyvault     = { type = "AzureKeyVault", props = { baseUrl = "https://kv-analytics-prod.vault.azure.net/" } }
  }
}

module "linked_services" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"
  for_each = local.linked_services

  name                 = "ls-${each.key}"
  synapse_workspace_id = module.workspace.id

  type                 = each.value.type
  type_properties_json = jsonencode(each.value.props)

  annotations = ["managed-by-terraform"]
}

provider "azurerm" {
  features {}
}

data "azurerm_client_config" "current" {}

module "rg" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"
  name     = "rg-analytics-prod"
  location = "eastus2"
}

module "lake" {
  source                   = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-account.git?ref=v1.0.0"
  name                     = "stanalyticsprod01"
  resource_group_name      = module.rg.name
  location                 = module.rg.location
  account_tier             = "Standard"
  account_replication_type = "ZRS"
  is_hns_enabled           = true
}

resource "azurerm_storage_data_lake_gen2_filesystem" "root" {
  name               = "synapse-root"
  storage_account_id = module.lake.id
}

module "kv" {
  source              = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault.git?ref=v1.0.0"
  name                = "kv-analytics-prod"
  resource_group_name = module.rg.name
  location            = module.rg.location
  tenant_id           = data.azurerm_client_config.current.tenant_id
}

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

  name                                 = "synw-analytics-prod"
  resource_group_name                  = module.rg.name
  location                             = module.rg.location
  storage_data_lake_gen2_filesystem_id = azurerm_storage_data_lake_gen2_filesystem.root.id

  azuread_authentication_only     = true
  managed_virtual_network_enabled = true

  identity = { type = "SystemAssigned" }

  tags = {
    environment = "prod"
    workload    = "analytics"
  }
}

module "runtime" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-integration-runtime-azure.git?ref=v1.0.0"

  name                 = "ir-managed-eastus2"
  synapse_workspace_id = module.workspace.id
  location             = module.rg.location
}

# The vault connection. Nothing secret passes through Terraform.
module "vault_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-keyvault"
  synapse_workspace_id = module.workspace.id
  description          = "Resolves connection secrets at run time"

  type = "AzureKeyVault"
  type_properties_json = jsonencode({
    baseUrl = module.kv.vault_uri
  })

  annotations = ["managed-by-terraform"]
}

# The lake connection.
module "lake_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-adls-curated"
  synapse_workspace_id = module.workspace.id
  description          = "Curated zone of the analytics data lake"

  type = "AzureBlobFS"
  type_properties_json = jsonencode({
    url = module.lake.primary_dfs_endpoint
  })

  integration_runtime = {
    name = module.runtime.name
  }

  annotations = ["managed-by-terraform", "curated-zone"]
}

# The SQL connection -- password resolved through the vault connection above.
module "sql_connection" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-linked-service.git?ref=v1.0.0"

  name                 = "ls-sql-reporting"
  synapse_workspace_id = module.workspace.id
  description          = "Reporting database, credential resolved from Key Vault"

  type = "AzureSqlDatabase"
  type_properties_json = jsonencode({
    connectionString = "Server=tcp:sqlsrv.database.windows.net;Database=reporting;User ID=svc_reporting;"
    password = {
      type       = "AzureKeyVaultSecret"
      secretName = "sql-reporting-password"
      store = {
        referenceName = module.vault_connection.name
        type          = "LinkedServiceReference"
      }
    }
  })

  integration_runtime = {
    name = module.runtime.name
  }

  annotations = ["managed-by-terraform"]
}

output "linked_service_review" {
  value = {
    for k, m in {
      lake  = module.lake_connection
      sql   = module.sql_connection
      vault = module.vault_connection
      } : k => {
      name            = m.name
      type            = m.type
      property_names  = m.type_properties_keys
      resolves_secret = m.references_a_key_vault_linked_service
      type_intact     = m.type_was_not_overridden
      runtime         = m.integration_runtime_name
    }
  }
}

variable "name" {
  type = string
  # Validated by NOTHING in the provider. This module rejects an empty value, a
  # slash and control characters. Force-new, and the string every artifact in
  # the workspace references.
}

variable "synapse_workspace_id" {
  type = string
  # Anchored at both ends. Rejects this module's own linked service ID and any
  # pool ID.
}

variable "type" {
  type = string
  # One of 101 case-sensitive values, GENERATED from the provider's source
  # because eleven of them differ from the constants that name them.
}

variable "type_properties_json" {
  type = string
  # Must parse as a JSON OBJECT on its own -- which is exactly the condition a
  # wrapper-escaping fragment fails. NOT force-new; NOT marked sensitive by the
  # provider, so keep credentials out of it.
}

variable "description" {
  type    = string
  default = null
  # Non-empty when supplied -- mirrors the provider's own check.
}

variable "integration_runtime" {
  type = object({
    name       = string
    parameters = optional(map(string), {})
  })
  default = null
  # At most one. Omit it for Synapse's auto-resolve runtime. Referenced by
  # NAME, and nothing verifies that the runtime exists.
}

variable "parameters" {
  type    = map(string)
  default = {}
  # name => DEFAULT VALUE. Every parameter is typed as a string by the
  # provider; an int or bool cannot be expressed.
}

variable "annotations" {
  type    = list(string)
  default = []
  # Artifact labels, NOT Azure tags. A list, so order matters. Rejects an empty
  # entry and a duplicate.
}

variable "additional_properties" {
  type    = map(string)
  default = {}
  # Merged at the TOP level and LAST. The six reserved names -- type,
  # typeProperties, connectVia, description, parameters, annotations -- are
  # rejected, because each would silently overwrite the argument.
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
  # Provider defaults: create 30m, read 5m, update 30m, delete 30m.
}