☁️ Azure Storage Sync Server Endpoint Terraform Module

The on-premises end of a sync group — a path on a registered server — targeting hashicorp/azurerm ~> 4.0.

• 🖧 Syncs a path on an already-registered server against the group's cloud endpoint.
• 🔴 Cloud tiering moves files OFF the server. With it on, cold files are replaced by pointers and the bytes live in the Azure file share — a relocation of data, not a replication. It defaults to false.
• 🔴 The server must already be registered, by installing the Azure File Sync agent on the server. That never happens through Azure Resource Manager, and no module in this library does it.
• 🔴 This resource and the cloud endpoint in the same group share almost nothing — a typed provider resource against a legacy one, four updatable arguments against none, four timeouts against three.
• ⚠️ name has no validator at all — not a pattern, not a length bound, not even a not-empty check — while the cloud endpoint's name has a real regex.
• ✅ One cross-field rule IS checkable offline and is enforced: the registered server and the sync group must belong to the same Storage Sync Service.
• ⚠️ volume_free_space_percent is sent even when tiering is off, and defaults to 20.
• 🏷️ Carries no tags and no location.

💡 Why it matters: the tiering switch is a boolean that decides whether your server keeps its files. Everything else here is plumbing; that one argument changes where the data physically is.

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"]
  SVC["terraform-azurerm-storage-sync"]
  GRP["terraform-azurerm-storage-sync-group"]
  THIS["terraform-azurerm-storage-sync-server-endpoint"]
  CLOUD["terraform-azurerm-storage-sync-cloud-endpoint"]
  REG["a REGISTERED SERVER, agent installed and registered ON the server"]
  PATH["a path on that server, never reached from here"]
  FILES["the files themselves, which TIERING moves off the server"]

  RG -->|"name and location"| SVC
  SVC -->|"id"| GRP
  GRP -->|"id"| THIS
  GRP -->|"id"| CLOUD
  SVC -->|"id, the server registers with the SERVICE not the group"| REG
  REG -->|"registered_server_id, checked to share a service with the group"| THIS
  THIS -.->|"server_local_path, stored verbatim"| PATH
  THIS -.->|"cloud tiering ON replaces cold files with pointers"| FILES
  CLOUD -.->|"where the tiered bytes actually live"| FILES

  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 FILES target
  class RG,SVC,GRP,CLOUD,REG,PATH sib

The registered server enters from the Storage Sync Service, not from the group — one registration carries endpoints in several groups. And the dotted edge into the files is the one that matters: with tiering on, they leave the server for the share the cloud endpoint points at.

flowchart TB
  GRP["storage_sync_group_id, force-new"]
  NM["name, force-new, NO provider validator at all"]
  REG["registered_server_id, force-new, must share a service with the group"]
  PATH["server_local_path, force-new, never reached"]
  TIER["cloud_tiering_enabled, UPDATABLE, default false"]
  POL["volume_free_space_percent and tier_files_older_than_days, UPDATABLE"]
  IDP["initial_download_policy, FORCE-NEW unlike the others"]
  LCM["local_cache_mode, UPDATABLE"]
  THIS["azurerm_storage_sync_server_endpoint.this"]
  OMOVE["cloud_tiering_moves_files_off_the_server"]
  OSTAGED["a_tiering_policy_is_configured_but_tiering_is_off"]
  ODIFF["this_resource_and_the_cloud_endpoint_share_almost_nothing"]
  OREG["the_server_must_already_be_registered"]

  GRP --> THIS
  NM --> THIS
  REG --> THIS
  PATH --> THIS
  TIER --> THIS
  POL --> THIS
  IDP --> THIS
  LCM --> THIS
  THIS --> OMOVE
  THIS --> OSTAGED
  THIS --> ODIFF
  THIS --> OREG

  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 OMOVE target
  class GRP,NM,REG,PATH,TIER,POL,IDP,LCM,OSTAGED,ODIFF,OREG sib

Resource inventory

/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.StorageSync/storageSyncServices/SERVICE/syncGroups/GROUP/serverEndpoints/NAME

Schema notes that bite

• 🔴 Cloud tiering moves files off the server, replacing them with pointers. It defaults to false and updates in place, so turning it on is an edit rather than a replacement. Turning it off does not automatically recall tiered files.
• 🔴 volume_free_space_percent is sent whether or not tiering is enabled, and defaults to 20. Setting it with tiering off is accepted and inert.
• 🔴 name has NO validator at all. The cloud endpoint in the same group validates its name with a real regex.
• 🔴 This resource and the cloud endpoint share almost no behaviour. Copying a timeouts tail from here to there loses the update key in silence, because that resource declares only three.
• ⚠️ initial_download_policy is force-new while the other three policy arguments update in place.
• ⚠️ server_local_path carries only a not-empty check — nothing verifies the path, its filesystem, or whether it already syncs elsewhere.
• ⚠️ The registered server hangs off the SERVICE, not the group.
• ⚠️ tier_files_older_than_days has an upper bound of the maximum 32-bit integer — mirrored, not narrowed — and the provider sends it only when set.
• ✅ Both enums are case-sensitive: initial_download_policy and local_cache_mode.
• ✅ The delete polls, and the create uses a custom poller that waits for the endpoint to come up.
• ✅ A requires-import guard is present, feature-flag-wrapped.
• ✅ All four timeouts exist — 30m create, 5m read, 30m update, 30m delete.

Least-privilege, at the smallest scope that works:

• Contributor on the Storage Sync Service, or a custom role granting write and delete on Microsoft.StorageSync/storageSyncServices/syncGroups/serverEndpoints. ARM management-plane calls.
• ⚠️ No permission on the server is involved, and none can be granted from Azure. The server's side of the trust comes from its registration, performed locally with the agent.
• 🔴 Deleting a server endpoint stops the sync for that path. It does not delete data on the server — but with tiering enabled, files already tiered exist there only as pointers, so removing the endpoint leaves the server without the data those pointers referenced. That is what withholding delete protects.

🔓 This module handles no credential and emits none.

• An existing sync group with a cloud endpoint already in it.
• A registered server — the Azure File Sync agent installed and registered from the server, against the same Storage Sync Service the group belongs to.
• The path on that server, existing and on a supported filesystem.
• The Microsoft.StorageSync resource provider registered on the subscription.
• The caller configures provider "azurerm" { features {} }, authentication, and the subscription.

terraform-azurerm-storage-sync-server-endpoint/
├── providers.tf     # required_version, pinned azurerm ~> 4.0, no provider block
├── variables.tf     # 10 typed inputs, 20 validations, a four-key timeouts tail
├── main.tf          # the keystone `this`, dynamic timeouts
├── outputs.tf       # 36 outputs: id first, then identity, then posture flags
├── README.md        # this file
├── SCOPE.md         # the cross-module contract
├── LICENSE          # MIT
└── .gitignore

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

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-server"

  registered_server_id = var.registered_server_id # registered ON the server
  server_local_path    = "D:\\shares\\documents"

  # Tiering defaults to false: the server keeps a full copy.
}

🔴 With cloud_tiering_enabled = false this is a replication — the server keeps everything. Turn tiering on and cold files move to Azure.

Consumes

✅ These two are checked against each other — both must name the same Storage Sync Service.

Emits

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

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-server"

  registered_server_id = var.registered_server_id
  server_local_path    = "D:\\shares\\documents"
}

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

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-server"

  registered_server_id = var.registered_server_id
  server_local_path    = "D:\\shares\\documents"

  cloud_tiering_enabled     = true
  volume_free_space_percent = 40
  tier_files_older_than_days = 30
}

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

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-server"

  registered_server_id = var.registered_server_id
  server_local_path    = "D:\\shares\\documents"

  # The policy is set; the switch is not.
  cloud_tiering_enabled     = false
  volume_free_space_percent = 40
}

# REJECTED at plan -- the server is registered with a DIFFERENT service.
module "mismatched" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-sync-server-endpoint.git?ref=v1.0.0"

  storage_sync_group_id = module.sync_group.id # .../storageSyncServices/sync-hq/syncGroups/...
  name                  = "hq-server"

  registered_server_id = var.branch_server_id   # .../storageSyncServices/sync-branch/registeredServers/...
  server_local_path    = "D:\\shares\\documents"
}

# ALL accepted here -- the provider applies NO validator to `name`:
name = "hq_server.01"
name = "HQ Server"
name = "a"

# This module refuses only what is certainly wrong:
name = "  "                       # REJECTED: whitespace
name = " hq "                     # REJECTED: never trimmed by the provider
name = "/subscriptions/x/y"       # REJECTED: a Resource ID

# initial_download_policy -- what happens ONCE, at creation. FORCE-NEW.
initial_download_policy = "NamespaceThenModifiedFiles" # default
initial_download_policy = "NamespaceOnly"              # namespace only; files arrive on open
initial_download_policy = "AvoidTieredFiles"           # skip files already tiered

# local_cache_mode -- ONGOING behaviour. Updatable.
local_cache_mode = "UpdateLocallyCachedFiles"    # default
local_cache_mode = "DownloadNewAndModifiedFiles"

# REJECTED -- both are compared case-sensitively:
initial_download_policy = "namespaceonly"
local_cache_mode        = "updatelocallycachedfiles"

volume_free_space_percent = 1    # keep 1% free -- almost nothing is tiered
volume_free_space_percent = 20   # the provider's default
volume_free_space_percent = 90   # keep 90% free -- most data lives in Azure

# REJECTED at plan:
volume_free_space_percent = 0    # the provider's range starts at 1
volume_free_space_percent = 101

variable "registered_server_id" {
  type        = string
  description = "Registered by installing the Azure File Sync agent ON the server."
}

output "server_endpoint_change_planning" {
  value = {
    force_new = module.server_endpoint.force_new_fields
    updatable = module.server_endpoint.updatable_fields
  }
}

force_new = ["name", "storage_sync_group_id", "registered_server_id",
             "server_local_path", "initial_download_policy"]
updatable = ["cloud_tiering_enabled", "volume_free_space_percent",
             "tier_files_older_than_days", "local_cache_mode"]

# Legal HERE -- this resource has an update function:
timeouts = {
  create = "30m"
  read   = "5m"
  update = "30m"
  delete = "30m"
}

# Paste that same block into terraform-azurerm-storage-sync-cloud-endpoint and
# the `update` key VANISHES -- no error, no warning, no plan diff.

locals {
  synced_paths = {
    documents = "D:\\shares\\documents"
    finance   = "D:\\shares\\finance"
  }
}

module "server_endpoints" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-sync-server-endpoint.git?ref=v1.0.0"
  for_each = local.synced_paths

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-${each.key}"

  registered_server_id = var.registered_server_id
  server_local_path    = each.value

  cloud_tiering_enabled = true
}

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

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

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

  name                = "sync-hq"
  resource_group_name = module.rg.name
  location            = module.rg.location
}

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

  storage_sync_id = module.sync_service.id
  name            = "hq-documents"
}

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

  name                = "stgsynchq01"
  resource_group_name = module.rg.name
  location            = module.rg.location # same region as the service

  shares = {
    hq = { name = "hq-share", quota = 100 }
  }
}

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

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-cloud"

  storage_account_id = module.storage.id
  file_share_name    = "hq-share"
}

# THE SERVER SIDE -- this module. The registration already exists.
module "server_endpoint" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-sync-server-endpoint.git?ref=v1.0.0"

  storage_sync_group_id = module.sync_group.id
  name                  = "hq-server"

  registered_server_id = var.registered_server_id
  server_local_path    = "D:\\shares\\documents"

  cloud_tiering_enabled     = true
  volume_free_space_percent = 40
}

output "file_sync" {
  value = {
    group      = module.sync_group.name
    share      = module.cloud_endpoint.file_share_name
    server_path = module.server_endpoint.server_local_path
    tiering    = module.server_endpoint.cloud_tiering_is_enabled
    staged     = module.server_endpoint.a_tiering_policy_is_configured_but_tiering_is_off
  }
}

Parent — storage_sync_group_id (required, force-new; the group, not the service). Identity — name (required, force-new; no provider validator at all). The server — registered_server_id (required, force-new, checked to share a service with the group), server_local_path (required, force-new). Tiering — cloud_tiering_enabled (default false), volume_free_space_percent (default 20), tier_files_older_than_days — all updatable. Policies — initial_download_policy (force-new), local_cache_mode (updatable). Tail — timeouts, with four keys. There is no tags argument and no location.

variable "cloud_tiering_enabled" {
  type    = bool # UPDATABLE. true means cold files LEAVE the server.
  default = false
}

variable "volume_free_space_percent" {
  type    = number # 1-100. The proportion kept FREE, so higher tiers MORE.
  default = 20     # Sent to the service even when tiering is off.
}

variable "initial_download_policy" {
  type    = string # FORCE-NEW, case-sensitive:
  default = "NamespaceThenModifiedFiles"
                   # | "NamespaceOnly" | "AvoidTieredFiles"
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
    # FOUR keys here. The cloud endpoint in the same group has THREE.
  })
  default = null
}

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

One boolean here decides whether the server keeps its files. With cloud_tiering_enabled on, cold files are removed from the server's disk and replaced by pointers; the namespace stays intact, so the directory still looks complete, and the bytes live in the Azure file share the group's cloud endpoint names. That is the point of Azure File Sync for most deployments and it is also a genuine relocation of data rather than a replication — a tiered file exists in one place, so the share is part of the live data path and not a copy of it. None of that is visible in a plan, which is why the module emits it as a constant alongside a computed flag for the current state.

The switch is updatable and the policy is sent regardless, which produces one legal-but-inert combination. volume_free_space_percent is written unconditionally by the provider, so configuring a tiering policy while tiering is off is accepted and does nothing until the switch is flipped. That is reported rather than refused, because staging a policy ahead of the change is a reasonable thing to do — and so is forgetting the switch, and only the author knows which. The direction of that percentage is worth repeating too: it is the proportion of the volume kept free, so a higher number tiers more data away, which reads backwards the first time.

This resource and the cloud endpoint in the same group look like a pair and share almost nothing. One is a typed provider resource, the other legacy. This one has four updatable arguments; that one has none. This one declares four timeouts; that one declares three, because it has no update function at all. Copying a timeouts tail between them therefore fails in one direction completely silently — Terraform's object-type conversion drops a key the declared type does not have, with no error and no plan diff. Both modules emit the difference, because a paste between two modules that look like siblings is the most available mistake across the pair.

Almost nothing about the two IDs this resource takes can be checked — except one thing, which is enforced. Both registered_server_id and storage_sync_group_id carry the Storage Sync Service in their path, and a server registered with one service structurally cannot host an endpoint in another's group. That makes it a configuration rule whose violation is impossible rather than merely unusual, so it is refused at validate rather than reported. It is placed on registered_server_id, since a validation may reference its own variable plus others only one way, which is why its message names an argument the caller may not have been editing. It is one of very few cross-field rules in this family that is checkable at all — the cloud endpoint's share/account pairing and its region requirement are not.

What this module cannot do at all is the part people expect it to. The registered server is created by installing the Azure File Sync agent on the server and registering it — there is no ARM call for that, no Terraform resource, and no module here. The path is stored verbatim: nothing checks that it exists, that its filesystem is supported, or that it is already syncing in another group. And name has no provider validator whatsoever, while the cloud endpoint's does — three different naming behaviours inside one small family, which is why each module states its own rather than implying a shared convention.

🔒 The security-relevant control is delete. Removing a server endpoint stops the sync — and where tiering is on, the server holds pointers rather than files, so the data those pointers referenced is no longer reachable from the server.

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 20 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.

20 negative fixtures fired the checks they targeted, and 10 positive fixtures passed clean. The negatives cover the group ID three ways including the Storage Sync Service's ID passed as the group's, three name rules, the registered server ID three ways, the local path two ways, both numeric ranges at both ends, and both enums in a wrong-value and a wrong-case form.

🔴 One negative exists for the cross-field rule: a registered server belonging to sync-branch paired with a group belonging to sync-hq, which fires the service-mismatch check. Its needle had to be kept short because the console wraps the message between "Storage" and "Sync" — the real message was printed before the needle was shortened, to confirm the right check had fired.

The positives prove the boundaries: volume_free_space_percent at 1 and at 100, tier_files_older_than_days at 1, both non-default values of each enum, a name containing a dot and an underscore — shapes the cloud endpoint would refuse — and a tiering policy set while tiering is off, which is reported rather than refused.

The computed outputs were driven through the same harness: the parsed service and registered-server names, and the tiering and staged-policy flags across all three combinations of switch and policy.

What only a real plan/apply exercises: whether the group, its cloud endpoint and the registered server exist, and the requires-import guard.

What nothing exercises: whether the path exists on the server, whether its filesystem is supported, or whether it is already syncing in another group.

id                                = ".../syncGroups/hq-documents/serverEndpoints/hq-server"
name                              = "hq-server"
sync_group_name                   = "hq-documents"
storage_sync_name                 = "sync-hq"
server_local_path                 = "D:\\shares\\documents"
cloud_tiering_enabled             = true
volume_free_space_percent         = 40
tier_files_older_than_days        = null
initial_download_policy           = "NamespaceThenModifiedFiles"
local_cache_mode                  = "UpdateLocallyCachedFiles"
cloud_tiering_is_enabled          = true
a_tiering_policy_is_configured_but_tiering_is_off = false
updatable_fields                  = ["cloud_tiering_enabled", "volume_free_space_percent", "tier_files_older_than_days", "local_cache_mode"]

• azurerm_storage_sync_server_endpoint
• azurerm_storage_sync_cloud_endpoint
• azurerm_storage_sync_group
• Azure File Sync cloud tiering
• Registering a server with Azure File Sync
• Sibling modules: terraform-azurerm-storage-sync, terraform-azurerm-storage-sync-group, terraform-azurerm-storage-sync-cloud-endpoint
• This module's SCOPE.md

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