☁️ Azure File Share Directory Terraform Module

A directory inside an Azure file share, with its metadata — targeting hashicorp/azurerm ~> 4.0.

• 📁 Creates one directory inside an Azure file share, with its data-plane metadata.
• 🔴 It takes a data-plane URL, not an ARM Resource ID. storage_share_url is https://<account>.file.core.windows.net/<share> — the opposite of nearly every other module in this library, which makes passing a Resource ID the natural mistake. This module refuses one by name.
• 🔴 The provider will not catch that for you offline. Its own validator on this argument only parses the URL properly once the provider has been configured; terraform validate never configures one, so a Resource ID, a wrong-cloud suffix and an unrelated host all pass the provider's check at validate. This module's check is the only one that fires offline.
• 🔴 A deprecated alternative argument exists and is not exposed here. storage_share_id is still accepted by the provider on this line and its own notice says it will be removed in version 5.0.
• 🔴 The provider marks storage_share_url Optional on 4.x, not Required — it is Required only inside a 5.0 branch gated behind a feature helper that is off by default. Reading the base schema gives the wrong answer for the pinned line.
• 🔴 A forward slash in name builds a hierarchy, deliberately — so reports/2026/01 is one record standing in for three directories, two of which Terraform does not own.
• ⚠️ These are DATA-PLANE calls against the file endpoint; an ARM role does not authorise them.
• ⚠️ name may not be only dots, and there is no maximum length in the provider's check.
• 🏷️ Carries no tags and no location; metadata is data-plane metadata, not Azure tags.

💡 Why it matters: this is a two-argument resource whose first argument is the one thing this library never asks for anywhere else — a URL — and whose second can quietly describe a tree.

If this module saved you time:

• ⭐ Star the repository — it helps other people find it.
• 💼 Connect on LinkedIn — linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee — buymeacoffee.com/microsoftexpert

flowchart TB
  RG["terraform-azurerm-resource-group"]
  SA["terraform-azurerm-storage-account, whose shares map creates the share"]
  SHARE["a file share, addressed here by its data-plane URL"]
  THIS["terraform-azurerm-storage-share-directory"]
  FILE["terraform-azurerm-storage-share-file"]
  MID["the intermediate levels of a slashed name, NOT managed here"]
  RBAC["terraform-azurerm-role-assignments, scoped to the ACCOUNT"]

  RG -->|"name and location"| SA
  SA -->|"shares map"| SHARE
  SHARE -->|"URL, NOT an ARM Resource id"| THIS
  THIS -.->|"a slashed name leaves these unowned"| MID
  THIS -->|"path, so the directory exists before the file"| FILE
  SA -->|"the ACCOUNT is the usable RBAC scope, not this record"| RBAC
  RBAC -.->|"a file data role, or a shared key"| THIS

  classDef me fill:#0078D4,stroke:#004578,stroke-width:2px,color:#ffffff
  classDef target fill:#004578,stroke:#00243d,stroke-width:2px,color:#ffffff
  classDef sib fill:#eef3f8,stroke:#9db4c9,color:#1a2733

  class THIS me
  class SHARE target
  class RG,SA,FILE,MID,RBAC sib

The share arrives as a URL, not a Resource ID — and it is created through the storage-account module's shares map, because this library has no standalone module for a file SHARE. The FILES in it are a different matter: terraform-azurerm-storage-share-file owns those, and takes this module's name as its path, which is why that edge is solid. The dotted edges are what nothing owns — the intermediate levels of a slashed name — and the access path that makes the calls possible.

flowchart TB
  URL["storage_share_url, force-new, a DATA-PLANE URL not a Resource id"]
  NM["name, force-new, a slash builds a hierarchy"]
  MD["metadata, the ONLY updatable argument"]
  DEP["storage_share_id, DEPRECATED, removed in 5.0, NOT rendered here"]
  THIS["azurerm_storage_share_directory.this"]
  OURL["this_resource_takes_a_data_plane_url_not_a_resource_id"]
  ODEP["a_deprecated_alternative_argument_is_not_exposed_here"]
  ODEPTH["name_depth and parent_name"]
  OMID["intermediate_directories_are_not_managed_by_this_module"]
  ORENAME["renaming_this_directory_destroys_its_contents"]

  URL --> THIS
  NM --> THIS
  MD --> THIS
  DEP -.->|"deliberately omitted"| THIS
  THIS --> OURL
  THIS --> ODEP
  THIS --> ODEPTH
  THIS --> OMID
  THIS --> ORENAME

  classDef me fill:#0078D4,stroke:#004578,stroke-width:2px,color:#ffffff
  classDef target fill:#004578,stroke:#00243d,stroke-width:2px,color:#ffffff
  classDef sib fill:#eef3f8,stroke:#9db4c9,color:#1a2733

  class THIS me
  class OURL target
  class URL,NM,MD,DEP,ODEP,ODEPTH,OMID,ORENAME sib

Resource inventory

ℹ️ The Terraform ID is a data-plane identifier built from the file endpoint — not an ARM Resource ID, and not usable as the scope of a role assignment.

Schema notes that bite

• 🔴 storage_share_url is a DATA-PLANE URL, not an ARM Resource ID.
• 🔴 The provider's validator on it is weaker offline than it looks. It parses against the configured cloud's storage domain suffix only after the provider is configured, and falls back to a bare non-empty-path check until then — so at terraform validate an Azure Resource ID, a wrong-cloud suffix and https://example.com/x are all accepted by the provider. The strict parse needs credentials.
• 🔴 A deprecated storage_share_id still exists on this line, paired with the URL in an ExactlyOneOf, and is removed in 5.0. This module renders only the replacement.
• 🔴 storage_share_url is Optional and Computed on 4.x, Required only in the provider's 5.0 branch — which is gated behind a feature helper that is off by default.
• ⚠️ ExactlyOneOf tests PRESENCE, not truth. Rendering only the URL satisfies it; rendering both breaks it.
• 🔴 A forward slash in name is legal and intended — the provider's source says so. A leading slash is refused.
• ⚠️ name may not consist only of dots, and the forbidden characters are " \ : | < > * ?.
• 🔴 A metadata key must match ^[a-z_][a-z0-9_]+$ — lowercase, and at least two characters, so a is rejected along with Owner and owner-team.
• 🔴 A metadata key may not be a C# keyword, matched case-insensitively — class, default, object, string, event, lock, null and this are all refused. The provider enforces both rules; this module mirrors them so the message names the key.
• ⚠️ No maximum name length is set by the provider, so an over-long name fails at the service.
• 🔴 Data-plane calls, and the Terraform ID cannot scope a role assignment.
• ✅ Force-new: name, storage_share_url. Only metadata updates in place.
• ✅ A requires-import guard is present, feature-flag-wrapped; all four timeouts exist.
• No tags, no location — metadata is data-plane metadata, which Azure Policy does not see.

Least-privilege, at the smallest scope that works:

• 🔴 These are DATA-PLANE calls. Contributor on the account does not authorise them.
• Storage File Data SMB Share Contributor on the storage account, or a shared key — depending on which authentication the caller's provider configuration negotiates for the file endpoint.
• ⚠️ Scope the role to the storage account, not to this module's id.
• ⚠️ Network reachability to the file endpoint — a firewall that excludes the caller consumes the whole timeout before failing.

🔓 This module handles no credential and emits none.

• An existing storage account and, in it, an existing file share — created through the account module's shares map.
• Network reachability from the caller to the account's file endpoint.
• The caller configures provider "azurerm" { features {} }, authentication, and the subscription.

terraform-azurerm-storage-share-directory/
├── providers.tf     # required_version, pinned azurerm ~> 4.0, no provider block
├── variables.tf     # 4 typed inputs, 9 validations, the universal timeouts tail
├── main.tf          # the keystone `this`, dynamic timeouts
├── outputs.tf       # 27 outputs: id first, then identity, then posture flags
├── README.md        # this file
├── SCOPE.md         # the cross-module contract
├── LICENSE          # MIT
└── .gitignore

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

  # A URL -- NOT a Resource ID.
  storage_share_url = "https://stgfiles01.file.core.windows.net/reports"
  name              = "2026"
}

🔴 Passing module.storage.id here is refused, with a message saying which value is wanted — it is the mistake this module is most likely to catch.

Consumes

Emits

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

  storage_share_url = "https://stgfiles01.file.core.windows.net/reports"
  name              = "2026"
}

# REJECTED at plan:
storage_share_url = module.storage.id
# "/subscriptions/.../storageAccounts/stgfiles01"

# CORRECT -- the share's data-plane endpoint:
storage_share_url = "https://stgfiles01.file.core.windows.net/reports"

# The provider ALSO accepts this on the pinned 4.x line:
#   storage_share_id = "https://stgfiles01.file.core.windows.net/reports"
#
# Its own deprecation notice: "will be removed in version 5.0 of the Provider."

# The provider's base schema marks storage_share_url REQUIRED.
# The 4.x branch then OVERWRITES it as Optional + Computed, because of the
# deprecated pairing -- and that branch is the one in force on this pinned line.

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

  storage_share_url = "https://stgfiles01.file.core.windows.net/reports"
  name              = "reports/2026/01"
}

name_depth  = 3
parent_name = "reports/2026"

module "tree" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-share-directory.git?ref=v1.0.0"
  for_each = toset(["reports", "reports/2026", "reports/2026/01"])

  storage_share_url = "https://stgfiles01.file.core.windows.net/reports"
  name              = each.key

  metadata = { managed_by = "terraform" }
}

# Before:
name = "2026"

# After -- this DESTROYS the directory and its contents, then creates a new one.
name = "2026-archive"

# ACCEPTED:
name = "2026"
name = "reports/2026/01"   # a hierarchy
name = "reports.2026"      # dots are fine
name = ".hidden"           # a leading dot is fine
name = "<300 characters>"  # no length limit is set by the provider

# REJECTED at plan:
name = "."                 # only dots
name = ".."                # only dots
name = "/reports"          # a LEADING slash
name = "reports:2026"      # forbidden character
name = "a|b"               # forbidden character

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

  storage_share_url = "https://stgfiles01.file.core.windows.net/reports"
  name              = "2026"

  metadata = {
    owner_team = "finance"
    retention  = "7y"
  }
}

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

  storage_share_url = "https://stgfiles01.file.core.usgovcloudapi.net/reports"
  name              = "2026"
}

terraform import 'module.reports_dir.azurerm_storage_share_directory.this' \
  "https://stgfiles01.file.core.windows.net/reports/2026"

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

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

# The share is created through the ACCOUNT module -- there is no standalone
# file share module in this library.
module "storage" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-account.git?ref=v1.0.0"

  name                = "stgfiles01"
  resource_group_name = module.rg.name
  location            = module.rg.location

  shares = {
    reports = { name = "reports", quota = 100 }
  }
}

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

  # Composed from the account name and the share name -- NOT module.storage.id.
  storage_share_url = "https://${module.storage.name}.file.core.windows.net/reports"
  name              = "2026"

  metadata = { owner_team = "finance" }
}

# The role that makes the calls above possible -- scoped to the ACCOUNT.
module "files_rbac" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.storage.id

  role_assignments = {
    pipeline = {
      role_definition_name = "Storage File Data SMB Share Contributor"
      principal_id         = var.pipeline_identity_object_id
    }
  }
}

output "share_layout" {
  value = {
    account    = module.reports_2026.storage_account_name
    share      = module.reports_2026.share_name
    directory  = module.reports_2026.name
    depth      = module.reports_2026.name_depth
    rbac_scope = module.storage.id
  }
}

Target — storage_share_url (required by this module, force-new; a URL, not a Resource ID). Identity — name (required, force-new; slashes build a hierarchy). Optional — metadata, the only argument that updates in place. Tail — timeouts. There is no tags argument and no location.

variable "storage_share_url" {
  type = string # https://<account>.file.core.windows.net/<share>
                # NOT an ARM Resource ID. The provider marks this Optional on
                # 4.x because of a deprecated pairing; this module requires it.
}

variable "name" {
  type = string # A slash BUILDS A HIERARCHY. Forbidden: " \ : | < > * ?
                # and a name made only of dots. No maximum length.
}

variable "metadata" {
  type    = map(string) # data-plane metadata, NOT Azure resource tags.
  default = {}          # Keys: ^[a-z_][a-z0-9_]+$ -- lowercase, 2+ chars, and
}                       # NOT a C# keyword (class, default, object, string, ...)

There is no secret on this resource, so nothing is redacted.

The first argument is the one thing this library never asks for anywhere else. storage_share_url is a data-plane endpoint, not an ARM Resource ID, and nearly every other module here takes an ID in the equivalent position. That makes reaching for module.storage.id the natural instinct and the wrong one, so the module refuses a Resource ID explicitly and says which value it wants. There is also no standalone file share module in this library — shares come from the storage-account module's shares map — so in practice the URL is composed from the account name and the share name rather than read from an output.

The provider's schema reads backwards for the pinned line, and that is worth understanding rather than working around. The base schema marks storage_share_url Required; a branch guarded by a features.FivePointOh() helper then overwrites it as Optional and Computed and adds a deprecated storage_share_id beside it, the two paired in an ExactlyOneOf. That helper is off by default, so the Optional version is the one in force on 4.x. This module requires the argument of its caller regardless — rendering neither would produce a resource with no share — and emits the discrepancy so nobody comparing the module against the schema concludes it is gratuitously strict.

The deprecated argument is not exposed at all, per this suite's rule against deprecated names. That works cleanly because ExactlyOneOf tests whether an argument is present rather than what it contains: a module rendering only the replacement satisfies the pairing, and needs no change when the deprecated one is removed in 5.0. Offering the caller a choice would mean rendering one conditionally, which is a lot of machinery to support an argument that is going away.

A forward slash in the name is intended, and it is the quiet one. The provider's source explicitly declines to forbid a slash in a non-leading segment, because that is how nested directories are addressed. So reports/2026/01 is legal and describes three directories — of which this record is one. The other two are not owned by Terraform, so their metadata is whatever the service produced. name_depth and parent_name are computed and emitted to make that visible in a review rather than something a reader has to notice by counting slashes, and both ignore empty segments so a stray slash does not distort them.

Almost nothing here updates. name and storage_share_url are both force-new, so metadata is the whole of what an in-place change can touch — and a rename is a destroy-and-create that takes the directory's contents with it, including files this module never created. Azure Files does support renaming a directory as a service operation; this resource does not expose it.

🔒 The security-relevant control is delete: destroying this record, or changing name, removes the directory and everything inside it.

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 from a workstation; a human applies from CI.

terraform validate and terraform fmt -check are the offline proof gate. All 9 validation {} blocks fire at plan. Each was exercised with a negative fixture that fires it and a positive fixture that does not, driven from .tfvars files through terraform console — which, unlike terraform validate on a calling configuration, does evaluate root-module variable validations. A parse guard runs first, because a fixture that fails to parse reports exactly like a check that did not fire.

15 negative fixtures fired the checks they targeted, and 8 positive fixtures passed clean. The negatives cover the share URL five ways — including 🔴 an ARM Resource ID, the mistake this module exists to catch — and the name nine ways: empty, ., .., a leading slash, and each of the forbidden characters.

The positives prove the boundaries, and several pin behaviour rather than checking a rule:

• 🔴 reports/2026/01 passes, because a slash builds a hierarchy — that is the provider's documented intent, not a leniency.
• A 300-character name passes, because the provider sets no length limit and inventing one would reject legal input.
• .hidden and reports.2026 pass, since only a name made entirely of dots is refused.
• 🔴 A US Gov endpoint passes, proving the URL check does not hard-code the public-cloud domain suffix.

The computed outputs were driven through the same harness across four cases, one of which exists purely to pin behaviour: reports//2026/ yields a depth of 2 and a parent of reports, so a doubled or trailing slash does not distort either derived value. A sovereign-cloud case confirms the account name is taken from the host's leading label rather than by stripping a known suffix.

What only a real plan/apply exercises: whether the account and share exist, whether the caller can reach the file endpoint, and the requires-import guard.

id                     = "https://stgfiles01.file.core.windows.net/reports/2026"
name                   = "2026"
storage_share_url      = "https://stgfiles01.file.core.windows.net/reports"
share_name             = "reports"
storage_account_name   = "stgfiles01"
share_host             = "stgfiles01.file.core.windows.net"
name_depth             = 1
parent_name            = null
metadata               = { "owner_team" = "finance" }
force_new_fields       = ["name", "storage_share_url"]
updatable_fields       = ["metadata"]

• azurerm_storage_share_directory
• azurerm_storage_share_file
• azurerm_storage_account
• Naming and referencing shares, directories and files
• Sibling modules: terraform-azurerm-storage-account, terraform-azurerm-role-assignments. Files inside a share are owned by terraform-azurerm-storage-share-file, which takes this module's name output as its path.
• This module's SCOPE.md

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