☁️ Azure IoT Hub File Upload Terraform Module

Configures the storage account, blob container, authentication and notification behaviour that back an IoT Hub's device file-upload feature, targeting hashicorp/azurerm ~> 4.0.

• 📦 Points an IoT Hub at the storage account and blob container that receive device file uploads.
• 🔐 Selects how the hub authenticates to that storage account — account key, or a managed identity.
• 🔔 Configures the optional file-upload notification queue: lifetime, lock duration, delivery attempts.
• ⏱️ Bounds the SAS URI lifetime handed to each uploading device.
• 🧾 Emits the configuration as data plus a set of derived flags for the traps that no plan reveals.

💡 Why it matters: file upload is the one IoT Hub feature where a storage account key is unavoidable, where terraform destroy does not undo what was applied, and where rotating that key produces no diff. This module cannot remove those properties — the provider and the platform decide them — so it names each one in an output rather than letting it be discovered in production.

If this module saves you time, a little support goes a long way:

• ⭐ Star the repository on GitHub.
• 🔗 Connect on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Every module in the IoT Hub family hangs off one hub. This module is the ...-iothub-file-upload node — and note it is the only one joining the hub by Resource ID rather than by name.

flowchart TB
  RG["terraform-azurerm-resource-group"]
  HUB["terraform-azurerm-iothub"]
  SA["terraform-azurerm-storage-account"]
  UAI["terraform-azurerm-user-assigned-identity"]
  RA["terraform-azurerm-role-assignments"]
  EPEH["terraform-azurerm-iothub-endpoint-eventhub"]
  ROUTE["terraform-azurerm-iothub-route"]
  FBROUTE["terraform-azurerm-iothub-fallback-route"]
  ENRICH["terraform-azurerm-iothub-enrichment"]
  FUPLOAD["terraform-azurerm-iothub-file-upload"]

  RG -->|"name feeds resource_group_name"| HUB
  UAI -->|"id feeds the hubs identity"| HUB
  HUB -->|"name feeds iothub_name"| ROUTE
  HUB -->|"name feeds iothub_name"| FBROUTE
  HUB -->|"name feeds iothub_name"| ENRICH
  HUB -->|"id feeds iothub_id, an ID not a name"| FUPLOAD
  EPEH -->|"name feeds endpoint_names"| ROUTE
  EPEH -->|"name feeds endpoint_names"| ENRICH
  SA -->|"container name and connection string"| FUPLOAD
  RA -->|"Storage Blob Data Contributor on the account"| FUPLOAD
  HUB -.->|"its inline inputs conflict with all four"| ENRICH

  classDef batch fill:#0078D4,stroke:#004578,color:#ffffff
  classDef anchor fill:#004578,stroke:#002d4d,color:#ffffff
  classDef ext fill:#f0f3f7,stroke:#9aa7b5,color:#1b2733
  class ENRICH,FUPLOAD batch
  class HUB anchor
  class RG,SA,UAI,RA,EPEH,ROUTE,FBROUTE ext

flowchart TB
  PARENT["iothub_id<br/>a RESOURCE ID, force new, and the only one that is"]
  SECRET["connection_string<br/>required, sensitive, a storage account key"]
  CONT["container_name"]
  AUTH["authentication_type<br/>identity_id"]
  NOTIF["notifications_enabled<br/>default_ttl, lock_duration, max_delivery_count"]
  SAS["sas_ttl<br/>the device leg, never inert"]
  T["azurerm_iothub_file_upload.this"]
  OUT["id, which IS the hubs own id<br/>iothub_name<br/>uses_identity_based_authentication"]
  SILENT["destroy_leaves_the_configuration_live_on_the_hub<br/>a_rotated_storage_key_produces_no_plan_diff"]
  CRED["plan_access_is_credential_access<br/>identity_based_authentication_does_not_remove_the_storage_key"]
  INERT["notification_settings_configured_but_inert"]

  PARENT --> T
  SECRET --> T
  CONT --> T
  AUTH --> T
  NOTIF --> T
  SAS --> T
  T --> OUT
  T --> SILENT
  SECRET --> CRED
  AUTH --> CRED
  NOTIF --> INERT

  classDef keystone fill:#004578,stroke:#002d4d,color:#ffffff
  classDef io fill:#0078D4,stroke:#004578,color:#ffffff
  classDef note fill:#f0f3f7,stroke:#9aa7b5,color:#1b2733
  class T keystone
  class PARENT,SECRET,CONT,AUTH,NOTIF,SAS,OUT io
  class SILENT,CRED,INERT note

Schema notes that bite — each verified against the live provider schema and source:

• 🔴 The record's Resource ID is the hub's Resource ID, unchanged. There is no /fileUpload segment. Two blocks against one hub collide on one object with nothing to conflict on, and the plan never settles.
• 🔴 terraform destroy is a no-op against Azure. The delete path reads the hub and writes it back unmodified; the file-upload configuration stays live.
• 🔴 A rotated storage key produces no plan diff. Azure masks the key and the provider suppresses the diff on that portion.
• 🔴 connection_string is required even when authentication_type is identityBased. Devices always receive a SAS URI generated from it.
• ⚠️ identity_id may only be set with identityBased — enforced by the provider at apply time, and by this module at parse time.
• ⚠️ The first-apply guard is conditional. It is skipped by a provider feature flag, and does not trip on a half-configured hub.
• ⚠️ iothub_id is the only force-new argument. Everything else updates in place.
• ⚠️ No tags, no location.

🔴 None of IoT Hub's four built-in roles grants the management-plane write. IoT Hub Data Contributor, Data Reader, Registry Contributor and Twin Contributor are all data-plane — Microsoft states they "grant access to resources like devices and twin but they don't grant access to the IoT Hub resource".

🔴 Microsoft is explicit about which storage role to use: "select Storage Blob Data Contributor. (Don't select Contributor or Storage Account Contributor.)" The broader roles do not grant the blob data-plane access the hub actually needs.

🔴 Plan access is credential access here. connection_string is a required input carrying a storage account key. It sits in state in plaintext; sensitive = true redacts plan output and does not encrypt state. Grant plan rights only to principals you would hand the storage key to, and keep state in an encrypted, access-controlled backend — never a local file in a repository.

⚠️ The permission is broader than the operation. Microsoft.Devices/iotHubs/write is hub-level, so the same grant also permits changing the hub's SKU, routing, network rules and identity.

• Microsoft.Devices registered on the subscription.
• An existing IoT Hub, referenced by its Resource ID.
• 🔴 That hub's file_upload input left unset. Choose one model per hub.
• An existing storage account and blob container. This module creates neither.
• 🔴 The storage account in the same subscription as the hub. Microsoft documents this requirement; nothing here can check it.
• 🔴 For identityBased: the hub's identity already holding Storage Blob Data Contributor on the storage account, assigned before the first apply, with a few minutes allowed for propagation.
• No resource group or region to choose for this record.

terraform-azurerm-iothub-file-upload/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # 11 typed inputs, 14 validations
├── main.tf         # derived locals + the single azurerm_iothub_file_upload.this
├── outputs.tf      # 29 outputs: configuration, derived flags, and the traps
├── README.md       # this file
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string # provisioned out of band
  container_name    = "device-uploads"
}

🔒 The caller configures provider "azurerm" { features {} }, authentication, and the state backend. connection_string carries a storage account key — pass a reference, never a literal.

Consumes

Emits

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  authentication_type = "identityBased"
  identity_id         = module.upload_identity.id
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  authentication_type = "identityBased"
}

output "using_system_identity" {
  value = module.file_upload.uses_the_hubs_system_assigned_identity
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  notifications_enabled = true
  default_ttl           = "P1D"
  lock_duration         = "PT30S"
  max_delivery_count    = 25
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  max_delivery_count = 25 # notifications_enabled is still false
}

check "notification_settings_take_effect" {
  assert {
    condition     = !module.file_upload.notification_settings_configured_but_inert
    error_message = "Notification settings were tuned but notifications_enabled is false, so they do nothing."
  }
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  sas_ttl = "PT15M"
}

check "file_upload_uses_identity" {
  assert {
    condition     = module.file_upload.uses_identity_based_authentication
    error_message = "Hub-to-storage authentication must use a managed identity."
  }
}

check "sas_uri_is_short_lived" {
  assert {
    condition     = contains(["PT15M", "PT30M"], module.file_upload.sas_ttl)
    error_message = "SAS URIs must expire within 30 minutes."
  }
}

output "storage_key_still_present" {
  value = module.file_upload.identity_based_authentication_does_not_remove_the_storage_key
}

output "plan_access_is_credential_access" {
  value = module.file_upload.plan_access_is_credential_access
}

output "rotation_needs_its_own_step" {
  value = module.file_upload.a_rotated_storage_key_produces_no_plan_diff
}

output "destroy_is_a_no_op" {
  value = module.file_upload.destroy_leaves_the_configuration_live_on_the_hub
}

output "id_is_the_hub_id" {
  value = module.file_upload.id == module.iothub.id # true
}

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

  name                = "iot-plant-eastus"
  resource_group_name = module.resource_group.name
  location            = module.resource_group.location
  sku                 = { name = "S1", capacity = 1 }

  file_upload = null # managed by the module below instead
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"
}

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

  name     = "rg-iot-eastus"
  location = "eastus"
}

module "upload_identity" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-user-assigned-identity.git?ref=v1.0.0"

  name                = "uai-iot-uploads"
  resource_group_name = module.resource_group.name
  location            = module.resource_group.location
}

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

  name                = "stiotuploadseastus"
  resource_group_name = module.resource_group.name
  location            = module.resource_group.location
}

# The identity needs blob DATA access - not Contributor, not Storage Account Contributor.
module "upload_role" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.storage.id

  role_assignments = {
    "hub-to-uploads" = {
      role_definition_name = "Storage Blob Data Contributor"
      principal_id         = module.upload_identity.principal_id
    }
  }
}

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

  name                = "iot-plant-eastus"
  resource_group_name = module.resource_group.name
  location            = module.resource_group.location
  sku                 = { name = "S1", capacity = 1 }

  identity = {
    type         = "UserAssigned"
    identity_ids = [module.upload_identity.id]
  }

  file_upload = null # this composition uses the dedicated module below
}

module "file_upload" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-iothub-file-upload.git?ref=v1.0.0"

  iothub_id         = module.iothub.id
  connection_string = var.storage_connection_string
  container_name    = "device-uploads"

  authentication_type = "identityBased"
  identity_id         = module.upload_identity.id

  notifications_enabled = true
  sas_ttl               = "PT15M"

  depends_on = [module.upload_role]
}

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

  name                = "telemetry-to-events"
  iothub_name         = module.file_upload.iothub_name
  resource_group_name = module.resource_group.name
  routing_source      = "DeviceMessages"
  endpoint_names      = ["events"]
  enabled             = true
}

# Deliberately NOT re-emitted: the connection string. Consumers read it from the
# same secret store this configuration read it from.
output "file_upload_id" {
  value = module.file_upload.id
}

Required (3): iothub_id, connection_string (sensitive), container_name. Authentication (2): authentication_type, identity_id. Notifications (4): notifications_enabled, default_ttl, lock_duration, max_delivery_count. Device leg (1): sas_ttl. Tail (1): timeouts.

No output is sensitive, because no output is derived from the secret. Presence is not emitted either — connection_string is required, so a presence flag would be a constant true dressed up as information.

The identity of this resource is the identity of its parent. The provider sets the record's Terraform ID to the hub's Resource ID with no child segment. Everything awkward about this module follows from that: there is exactly one per hub, there is nothing to for_each over, import takes the hub's ID, and two blocks pointed at one hub produce an alternating diff instead of an error.

Three legs, and this resource configures one and a half of them. Device-to-hub is the hub's own authentication. Hub-to-storage is authentication_type. Device-to-storage is always a SAS URI generated from connection_string. That third leg is why the connection string is required in every configuration and why choosing identityBased is a real improvement that is nonetheless not the improvement it appears to be.

Two operations this module cannot make visible. Rotating the storage key produces no diff, because Azure masks the key and the provider excludes it from comparison. Destroying the resource produces no change on Azure, because the delete path writes the hub back unmodified. Both are silent, both are consequential, and both get a constant output rather than a sentence in a description.

The cross-field rule is enforced at parse time, one-directionally. A validation condition may only reference its own variable, so the identity_id / authentication_type pairing is carried on identity_id and the error message names both fields. The provider enforces the same rule in its create path, at apply time; this module simply moves the failure earlier.

Sensitivity is contained by deriving nothing from the secret. connection_string is marked sensitive, and no local, no other input and no output reads it. That is why none of the 29 outputs is sensitive and why no nonsensitive() call appears anywhere in the module.

🔴 The empty call is not the safe call, and this module says so rather than implying otherwise. The provider makes a credential-bearing argument required, so there is no configuration of this resource without a storage key in state. Where the secure-by-default rule cannot apply, this suite states it plainly and compensates: the value set is validated, the probable mistake is rejected by name, and the residual exposure is emitted as plan_access_is_credential_access.

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

Pin ?ref=v1.0.0, never a branch. Plan-only — a human applies from CI.

terraform validate proves the configuration parses and the types line up. terraform fmt -check proves formatting. Neither fires a root-module variable validation — terraform console with a .tfvars file does, and that is how all 14 validations here were exercised, each confirmed by the line number it reported.

What only a real plan against Azure can exercise: that the hub exists, that the storage container exists, that the identity holds Storage Blob Data Contributor, that the storage account shares the hub's subscription, and whether the first-apply guard trips.

id                                                = "/subscriptions/.../resourceGroups/rg-iot-eastus/providers/Microsoft.Devices/IotHubs/iot-plant-eastus"
iothub_name                                       = "iot-plant-eastus"
container_name                                    = "device-uploads"
authentication_type                               = "identityBased"
uses_identity_based_authentication                = true
uses_the_hubs_system_assigned_identity            = false
notifications_enabled                             = true
sas_ttl                                           = "PT15M"
notification_settings_are_inert                   = false
notification_settings_configured_but_inert        = false
destroy_leaves_the_configuration_live_on_the_hub  = true
a_rotated_storage_key_produces_no_plan_diff       = true
plan_access_is_credential_access                  = true

• Provider resource: azurerm_iothub_file_upload
• Configure IoT Hub file uploads
• IoT Hub support for managed identities
• Sibling modules: terraform-azurerm-iothub, terraform-azurerm-iothub-route, terraform-azurerm-iothub-fallback-route, terraform-azurerm-storage-account, terraform-azurerm-user-assigned-identity, terraform-azurerm-role-assignments
• This module's SCOPE.md

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