☁️ Azure Synapse Azure Integration Runtime Terraform Module

Registers one Azure (fully managed) integration runtime on a Synapse workspace — the Microsoft-hosted compute a data flow or a copy activity runs on. Targets hashicorp/azurerm ~> 4.0.

• 🧩 Creates one azurerm_synapse_integration_runtime_azure — a named, Microsoft-hosted runtime on the workspace.
• 🚩 Leads with a defect in the provider itself: its name error message states a rule its regular expression does not enforce. The message says "no consecutive dashes"; the pattern permits them, verified against the pattern.
• ⚖️ Documents the mirror-image defect on the self-hosted sibling — same message text, different pattern, wrong about the opposite half.
• 🔢 States that core_count is a closed set, not a range: 8, 16, 32, 48, 80, 144 or 272, with large steps between them.
• ❄️ Explains that time_to_live_min defaults to 0, which means no cluster reuse at all — every data flow pays a cold start — and that the provider validates this field with nothing.
• 🎯 Warns that the three compute settings govern data flows only, so tuning them changes nothing for a copy-only pipeline.
• 🌍 Notes that AutoResolve moves the data-residency decision out of your Terraform and into run time.
• 🏷️ Carries no tags — the resource has none. The universal tail is timeouts only.

💡 Why it matters: a managed runtime is easy to create and easy to misjudge. The default is a cluster that is torn down after every activity, so the first thing people notice is that data flows are slow; the fix is one field the provider does not validate at all. Meanwhile the compute settings that look like the tuning surface are ignored entirely by a copy activity, so a cost investigation that starts here finds nothing to explain.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart TB
  rg["terraform-azurerm-resource-group"]
  ws["terraform-azurerm-synapse-workspace"]
  this["terraform-azurerm-synapse-integration-runtime-azure"]
  shir["terraform-azurerm-synapse-integration-runtime-self-hosted"]
  sqlp["terraform-azurerm-synapse-sql-pool"]
  spark["terraform-azurerm-synapse-spark-pool"]
  aad["terraform-azurerm-synapse-workspace-aad-admin"]

  rg -->|"name"| ws
  ws -->|"id"| this
  ws -->|"id"| shir
  ws -->|"id"| sqlp
  ws -->|"id"| spark
  ws -->|"id"| aad
  this -->|"name, selected by a pipeline activity"| ws
  shir -->|"the other runtime type, for data Azure cannot reach"| ws

  classDef me fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef keystone fill:#004578,stroke:#002b4d,color:#ffffff;
  classDef sib fill:#eef3f8,stroke:#b9c7d6,color:#1b2a3a;
  class this me;
  class ws keystone;
  class rg,shir,sqlp,spark,aad sib;

The edge back to the workspace is not a Terraform reference: a pipeline activity selects a runtime by name, as a string in its own definition. Nothing here reports that no activity uses this runtime, and nothing reports that one names a runtime that does not exist.

flowchart TB
  subgraph inputs["Inputs"]
    ident["name plus synapse_workspace_id, both force-new"]
    loc["location, force-new, AutoResolve or a region"]
    compute["compute_type, core_count, time_to_live_min -- data flows only"]
    desc["description"]
  end

  this["azurerm_synapse_integration_runtime_azure.this"]

  subgraph outputs["Outputs"]
    oid["id, name, synapse_workspace_id, synapse_workspace_name, resource_group_name"]
    oloc["location, region_is_resolved_at_run_time"]
    ocomp["compute_type, core_count, time_to_live_min, cluster_is_torn_down_after_every_activity"]
    ofact["name_uses_consecutive_dashes, the_two_runtime_types_do_not_share_a_name_rule, creating_this_starts_no_compute"]
  end

  ident --> this
  loc -->|"AutoResolve defers the residency decision to run time"| this
  compute -->|"ignored entirely by a copy activity"| this
  desc --> this
  this --> oid
  this --> oloc
  this --> ocomp
  this --> ofact

  classDef me fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef sib fill:#eef3f8,stroke:#b9c7d6,color:#1b2a3a;
  class this me;
  class ident,loc,compute,desc,oid,oloc,ocomp,ofact sib;

Resource inventory

Schema notes that bite

• 🔴 The provider's name error message states a rule its regular expression does not enforce. The message says "no consecutive dashes"; the pattern permits them. The three-character minimum the same message claims is enforced. This module mirrors the pattern and reports the gap.
• 🔴 The self-hosted sibling carries the same message and a different pattern, wrong about the opposite half: it forbids consecutive dashes and accepts a one-character name.
• core_count is a closed set — 8, 16, 32, 48, 80, 144, 272 — not a range. An intermediate value is rejected rather than rounded, and 80 to 144 is nearly double.
• time_to_live_min is validated by nothing at all and defaults to 0, which means no cluster reuse.
• compute_type is case-sensitive PascalCase: General, ComputeOptimized, MemoryOptimized.
• location accepts the literal AutoResolve or a region, and the region half falls back to a plain non-empty check when the provider has not fetched Azure's location list — so the same value can pass in one run and fail in another. A region is normalised and diff-suppressed on the normalised form.
• The three compute settings are sent inside the data-flow properties, so a copy-only pipeline uses this runtime without touching any of them.
• Three force-new fields, all declared on the resource itself: name, synapse_workspace_id, location.
• This resource does have an existence check on create — an apply over an existing runtime fails and tells you to import.
• No tags. The location here is where the compute runs, not an ARM resource location.

Least-privilege, at the smallest scope that works:

• Microsoft.Synapse/workspaces/integrationRuntimes/write and .../integrationRuntimes/delete on the target workspace. A custom role scoped to the workspace is enough; Contributor on the workspace, or on its resource group, covers this more broadly than necessary.
• Microsoft.Synapse/workspaces/integrationRuntimes/read on the workspace, for the existence check before creating and for every refresh.

ℹ️ Plan access is not credential access on this resource. A managed runtime holds no key, and the provider marks nothing on it sensitive. That is not true of the self-hosted sibling, whose refresh reads two authorization keys — see example 11.

• An existing Synapse workspace (the synapse-workspace module).
• A region that can host the requested compute, if location is pinned rather than left at AutoResolve. Nothing here checks that a region can supply the requested core_count, and the failure arrives when an activity runs rather than at apply.
• A pipeline or data flow that selects this runtime by name, if it is to do anything. The registration alone runs nothing and costs nothing.
• The caller configures the provider "azurerm" { features {} } block, auth, and subscription.

terraform-azurerm-synapse-integration-runtime-azure/
├── providers.tf    # required_version and the pinned azurerm; no provider block
├── variables.tf    # identity, location, the three compute settings, description, timeouts
├── main.tf         # the single keystone azurerm_synapse_integration_runtime_azure.this
├── outputs.tf      # id first, then identity and compute, then the quiet facts
├── README.md       # this file
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore

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

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"
}

⚠️ The caller configures provider "azurerm" { features {} }, its authentication, and its subscription. This module declares no provider block.

❄️ This call gives you a cluster that is torn down after every activity, because time_to_live_min defaults to 0. That is the provider's default and it is rarely what you want. See example 4.

Consumes

Emits

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

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"
}

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

  name                 = "ir-dataflow-auto"
  synapse_workspace_id = var.synapse_workspace_id

  location = "AutoResolve" # exact casing; see example 3
}

output "residency_decided_elsewhere" {
  value = module.dataflow_runtime.region_is_resolved_at_run_time
}

# REJECTED at terraform plan, offline and without credentials:
#   location = "autoresolve"
#
#   Error: location must be spelled "AutoResolve" in exactly that casing.

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

  name                 = "ir-dataflow-auto"
  synapse_workspace_id = var.synapse_workspace_id

  location = "AutoResolve"
}

# ACCEPTED -- a region may be written any way you like:
#   location = "East US 2"   -> normalised to "eastus2" by the provider

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

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"

  # Keep the cluster warm between activities. The provider's default is 0.
  time_to_live_min = 15
}

output "cold_start_every_time" {
  value = module.dataflow_runtime.cluster_is_torn_down_after_every_activity
}

# REJECTED at terraform plan, offline and without credentials:
#   core_count = 64
#
#   Error: core_count must be one of 8, 16, 32, 48, 80, 144 or 272.

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

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"

  core_count       = 48 # 8, 16, 32, 48, 80, 144, 272 -- nothing between
  time_to_live_min = 15
}

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

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"

  compute_type     = "MemoryOptimized" # PascalCase; "memoryoptimized" is rejected
  core_count       = 32
  time_to_live_min = 20
}

output "these_settings_are_data_flow_only" {
  value = module.dataflow_runtime.compute_settings_govern_data_flows_only
}

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

  # ACCEPTED here, even though the provider's own error message says
  # "no consecutive dashes" -- its regular expression permits them.
  name                 = "ir--dataflow"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"
}

output "relying_on_a_provider_gap" {
  value = module.dataflow_runtime.name_uses_consecutive_dashes
}

# The AZURE runtime: minimum 3 characters ENFORCED, consecutive dashes PERMITTED.
#   "ir--dataflow"  accepted
#   "ab"            rejected

# The SELF-HOSTED runtime: consecutive dashes REJECTED, one-character name ACCEPTED.
#   "ir--onprem"    rejected
#   "i"             accepted

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

  name                 = "ir-dataflow-prod" # legal on both
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"
}

output "do_not_assume_one_convention" {
  value = module.dataflow_runtime.the_two_runtime_types_do_not_share_a_name_rule
}

locals {
  runtimes = {
    "ir-dataflow-heavy" = { compute_type = "MemoryOptimized", core_count = 80, ttl = 30 }
    "ir-dataflow-light" = { compute_type = "General", core_count = 8, ttl = 10 }
    "ir-copy-only"      = { compute_type = "General", core_count = 8, ttl = 0 }
  }
}

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

  name                 = each.key
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"

  compute_type     = each.value.compute_type
  core_count       = each.value.core_count
  time_to_live_min = each.value.ttl
}

output "which_runtimes_cold_start" {
  value = { for k, m in module.dataflow_runtimes : k => m.cluster_is_torn_down_after_every_activity }
}

output "what_replaces_this_runtime" {
  value = module.dataflow_runtime.force_new_fields
}

# All three of these are force-new:
#   name                 -- and pipelines name the runtime by this string
#   synapse_workspace_id -- a runtime belongs to one workspace
#   location             -- the compute region cannot be moved in place
#
# The compute settings and the description all update in place, which is what
# makes tuning safe and renaming not.

# THIS module -> azurerm_synapse_integration_runtime_azure
#   Microsoft-hosted compute, with a region and a core count. No credentials.
module "dataflow_runtime" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-integration-runtime-azure.git?ref=v1.0.0"

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = var.synapse_workspace_id
  location             = "eastus2"
}

# The SIBLING -> azurerm_synapse_integration_runtime_self_hosted
#   A REGISTRATION for compute you run yourself, to reach data Azure cannot.
#   No location, no core count -- and two authorization keys that the provider
#   reads on EVERY refresh and marks sensitive on NEITHER.
module "onprem_runtime" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-integration-runtime-self-hosted.git?ref=v1.0.0"

  name                 = "ir-onprem-sql"
  synapse_workspace_id = var.synapse_workspace_id
}

output "runtime_review" {
  value = {
    workspace       = module.dataflow_runtime.synapse_workspace_name
    resource_group  = module.dataflow_runtime.resource_group_name
    region          = module.dataflow_runtime.location
    auto_region     = module.dataflow_runtime.region_is_resolved_at_run_time
    compute         = module.dataflow_runtime.compute_type
    cores           = module.dataflow_runtime.core_count
    warm_minutes    = module.dataflow_runtime.time_to_live_min
    cold_start_each = module.dataflow_runtime.cluster_is_torn_down_after_every_activity
  }
}

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

  name     = "rg-data-platform"
  location = "eastus2"

  tags = {
    environment = "prod"
    owner       = "data-platform-team"
  }
}

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

  name                                 = "syn-platform-prod"
  resource_group_name                  = module.data_rg.name
  location                             = module.data_rg.location
  storage_data_lake_gen2_filesystem_id = var.filesystem_id

  azuread_authentication_only   = true
  public_network_access_enabled = false

  tags = module.data_rg.tags
}

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

  synapse_workspace_id = module.synapse.id

  login     = "Synapse Platform Admins"
  object_id = var.platform_admins_group_object_id
  tenant_id = var.tenant_id
}

# Managed compute, pinned to the workspace's region and kept warm.
module "dataflow_runtime" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-synapse-integration-runtime-azure.git?ref=v1.0.0"

  name                 = "ir-dataflow-prod"
  synapse_workspace_id = module.synapse.id
  location             = module.data_rg.location

  compute_type     = "MemoryOptimized"
  core_count       = 32
  time_to_live_min = 20

  description = "Data-flow compute for the nightly warehouse load. Cost owner: data-platform-team."
}

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

  name                 = "dwmain"
  synapse_workspace_id = module.synapse.id
  sku_name             = "DW100c"

  tags = module.data_rg.tags
}

output "runtime_name_for_pipeline_definitions" {
  value = module.dataflow_runtime.name
}

output "runtime_keeps_a_warm_cluster" {
  value = !module.dataflow_runtime.cluster_is_torn_down_after_every_activity
}

Identity — name and synapse_workspace_id, both required and both force-new.

Placement — location, required and force-new. AutoResolve or a region.

Compute — compute_type, core_count and time_to_live_min, all optional, all in-place, and all data-flow only.

Universal tail — timeouts only. This resource has no tags.

🔒 No secret is emitted, because this resource holds none.

The provider misdocuments its own name rule, and this module mirrors the rule rather than the documentation. The error message on name states that consecutive dashes are not allowed. Its regular expression permits them — that was checked against the pattern itself rather than taken on trust. This module reproduces the pattern character for character and reports the condition through name_uses_consecutive_dashes instead of adding the missing check, because a rule the provider does not enforce may be one Azure does not enforce either, and a validation {} failure blocks terraform destroy as well as apply. The same message on the self-hosted sibling is wrong about the opposite half, which is why neither runtime's name rule can be inferred from the other's.

The default is a cluster that never survives an activity. time_to_live_min defaults to 0, so a data flow starts a cluster, runs, and tears it down. For a pipeline of many short data flows, most of the wall-clock time is cluster startup. The fix is a single field — and the provider applies no validation to it at all, no minimum and no maximum, so nothing pushes back on a value of 0 or 6000. This module rejects a negative value because none is meaningful and deliberately does not invent a ceiling: the upper bound is a cost decision, and a warm cluster is billed for every minute it stays warm.

Two of the three compute settings look like general tuning and are not. compute_type, core_count and time_to_live_min are all sent inside the runtime's data-flow properties. A copy activity assigned to this runtime uses none of them. That makes a whole class of investigation dead-ended from the start: raising core_count to speed up a slow copy changes nothing, and a bill attributed to this runtime is a data-flow bill or nothing at all.

core_count is a set with large gaps. 8, 16, 32, 48, 80, 144, 272. There is no intermediate value to reach for, so the decision is always which step, and the steps near the top nearly double. The module mirrors the provider's set exactly rather than approximating it as a range.

AutoResolve is a residency decision, made elsewhere. It is a legitimate and convenient choice, and it means the compute region is selected per run from the sink's location rather than fixed by this configuration. Where residency is a requirement rather than a preference, pin the region — and region_is_resolved_at_run_time exists so that a review can tell the two apart without reading the value.

Creating this record starts nothing. It is a definition. The cluster starts when an activity runs, which makes an apply here fast and free — and also means an apply proves nothing about whether the compute can actually start. A region that cannot supply the requested core count fails at run time.

🔒 There is no secret on this resource and no secure-by-default toggle to set. The one governance-relevant choice is location, and the module's position is to report whether the residency decision was made here or deferred to run time, rather than to pick for you.

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

Pin the module at a tag — ?ref=v1.0.0 — never a branch. Everything above is plan-only static analysis; a human applies from CI.

What terraform validate covers, offline, with no credentials:

• Every validation {} block in this module — the name pattern and its Resource-ID lookalike check, the anchored synapse_workspace_id shape, the three on location (non-empty, the AutoResolve near miss, and not a Resource ID), the compute_type enum, the core_count closed set, the two on time_to_live_min (non-negative and whole), the description non-empty check, and the timeouts duration shapes.
• Type conversion of the timeouts object — with the caveat that undeclared keys are discarded silently rather than reported.

What only terraform plan reaches (credentials required):

• That the workspace exists and that its ID parses.
• That the caller's identity holds Microsoft.Synapse/workspaces/integrationRuntimes/write on it.
• That no runtime of this name already exists — this resource does have an existence check.
• The provider's own region check for location, and only when it has fetched Azure's location list.

What neither reaches, at any stage:

• Whether the chosen region can supply the requested core_count. That fails when an activity runs.
• Whether any pipeline or data flow selects this runtime. The reference is a string Terraform cannot see.
• Whether the time-to-live is right for the workload. That is a wall-clock and cost measurement, not a check.

Outputs:

id                                        = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-data-platform/providers/Microsoft.Synapse/workspaces/syn-platform-prod/integrationRuntimes/ir-dataflow-prod"
name                                      = "ir-dataflow-prod"
synapse_workspace_id                      = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-data-platform/providers/Microsoft.Synapse/workspaces/syn-platform-prod"
synapse_workspace_name                    = "syn-platform-prod"
resource_group_name                       = "rg-data-platform"
location                                  = "eastus2"
region_is_resolved_at_run_time            = false
compute_type                              = "MemoryOptimized"
core_count                                = 32
time_to_live_min                          = 20
cluster_is_torn_down_after_every_activity = false
name_uses_consecutive_dashes              = false
force_new_fields                          = [
  "name",
  "synapse_workspace_id",
  "location",
]

• azurerm_synapse_integration_runtime_azure — the provider resource this module wraps.
• azurerm_synapse_integration_runtime_self_hosted — the self-hosted runtime, a different resource.
• Integration runtime in Azure Data Factory and Synapse Analytics — Microsoft's platform documentation for the runtime types and what each one is for.
• Data flow performance and tuning — Microsoft's guidance on compute size and time-to-live.
• terraform-azurerm-synapse-workspace — the parent workspace.
• terraform-azurerm-synapse-integration-runtime-self-hosted — the self-hosted runtime.
• terraform-azurerm-synapse-linked-service — names this runtime so a connection is made through it rather than through Synapse's auto-resolve runtime.
• terraform-azurerm-synapse-sql-pool and terraform-azurerm-synapse-spark-pool — the other workloads in the workspace.
• This module's SCOPE.md — the cross-module contract.

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