☁️ Azure Storage Mover Agent Terraform Module

Registers an existing Azure Arc-enabled machine as the agent that performs a Storage Mover copy — targeting hashicorp/azurerm ~> 4.0.

• 🖥️ Registers an existing Arc-enabled machine against a storage mover, with an optional description.
• 🔴 It registers a machine; it does not create one. Both Arc fields identify a Hybrid Compute machine that must already exist, already be Arc-enabled, and already be running the agent software. This module provisions no hardware, onboards nothing to Arc, and installs nothing.
• 🔴 Four of the five arguments are force-new. Only description updates in place, so re-pointing an agent at a different machine is a destroy-and-create.
• 🔴 The two Arc fields are both strings, so transposing them type-checks perfectly. One takes a Microsoft.HybridCompute/machines Resource ID; the other takes that machine's SMBIOS UUID. Both are validated by shape here, and each message names the other field.
• 🔴 name has no pattern at all — only a not-empty check — while its azurerm_storage_mover_project sibling in the same service enforces a real regex. A name legal here can be illegal there.
• 🔗 A job definition references this agent by NAME, not by Resource ID, so name matters more than id in a composition.
• 🏷️ Carries no tags and no location, and exposes no computed attributes at all.

💡 Why it matters: this is a two-line resource with two easily-transposed opaque strings and a hard prerequisite it cannot see. Almost everything that goes wrong here goes wrong before Terraform is involved, so the module's job is to make the boundary explicit.

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"]
  MV["terraform-azurerm-storage-mover"]
  THIS["terraform-azurerm-storage-mover-agent"]
  PRJ["terraform-azurerm-storage-mover-project"]
  ARC["azurerm_arc_machine data source, an existing Arc-enabled machine"]
  ONBOARD["Arc onboarding and the agent software, installed OUTSIDE Terraform"]
  JOB["azurerm_storage_mover_job_definition"]
  SRC["terraform-azurerm-storage-mover-source-endpoint"]
  TGT["terraform-azurerm-storage-mover-target-endpoint"]

  RG -->|"name and location"| MV
  MV -->|"id"| THIS
  MV -->|"id"| PRJ
  MV -->|"id"| SRC
  MV -->|"id"| TGT
  ARC -->|"id and vm_uuid, both force-new here"| THIS
  ONBOARD -.->|"must already be done; this module installs nothing"| ARC
  PRJ -->|"id, as storage_mover_project_id"| JOB
  THIS -.->|"name, as agent_name, NOT the Resource id"| JOB
  SRC -.->|"name"| JOB
  TGT -.->|"name"| JOB

  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 MV target
  class RG,PRJ,ARC,ONBOARD,JOB,SRC,TGT sib

Two edges carry the point of this module. The Arc machine arrives from a data source, not from a sibling module — there is nothing in this library that creates one, and Arc onboarding plus the agent software install happen entirely outside Terraform. And the job definition consumes this agent's name, not its Resource ID, which is the opposite of how the project is consumed.

flowchart TB
  MV["storage_mover_id, force-new"]
  NM["name, force-new, NO pattern at all"]
  AID["arc_virtual_machine_id, force-new, Microsoft.HybridCompute machines only"]
  AUU["arc_virtual_machine_uuid, force-new, canonical 36-char UUID only"]
  DESC["description, the ONLY updatable argument"]
  THIS["azurerm_storage_mover_agent.this"]
  ONM["name, which is what a job definition takes"]
  OID["id"]
  OSWAP["the_two_arc_fields_are_both_strings_so_a_swap_type_checks"]
  OSUB["the_arc_machine_is_in_a_different_subscription"]
  OREG["this_resource_registers_a_machine_it_does_not_create_one"]

  MV --> THIS
  NM --> THIS
  AID --> THIS
  AUU --> THIS
  DESC --> THIS
  THIS --> ONM
  THIS --> OID
  THIS --> OSWAP
  THIS --> OSUB
  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 ONM target
  class MV,NM,AID,AUU,DESC,OID,OSWAP,OSUB,OREG sib

Resource inventory

/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.StorageMover/storageMovers/MOVER/agents/NAME

Schema notes that bite

• 🔴 Force-new: name, storage_mover_id, arc_virtual_machine_id, arc_virtual_machine_uuid — four of five. The update function tests exactly description and sends nothing else. All four are declared inline, so unlike the parent mover, searching the resource file finds the whole set.
• 🔴 arc_virtual_machine_id must be a Microsoft.HybridCompute/machines ID. An Azure VM ID under Microsoft.Compute/virtualMachines is a different resource type and is rejected — an Arc-enabled server is not an Azure VM.
• 🔴 arc_virtual_machine_uuid is parsed strictly: exactly 36 characters, hyphens at positions 8, 13, 18 and 23, hexadecimal elsewhere. Braces, a urn:uuid: prefix and the unhyphenated 32-character form are all rejected.
• 🔴 name carries no pattern, while the project and both endpoints share one regex — this resource is the only one of the mover's four children without a naming rule. None of them appears in the binary schema.
• ⚠️ A job definition names this agent through agent_name — the name, not the ID.
• ⚠️ The Arc machine is routinely in a different resource group or subscription from the mover.
• ✅ The update is a read-modify-write, so an out-of-band change is preserved rather than reverted.
• ✅ A requires-import guard is present, feature-flag-wrapped.
• ✅ The delete polls for completion, so a destroy does not race a following create of the same name.
• ✅ Every argument is read back on refresh, so drift here is detectable.
• ✅ All four timeouts exist — 30m create, 5m read, 30m update, 30m delete.

Least-privilege, at the smallest scope that works:

• Contributor on the storage mover, or a custom role granting write and delete on Microsoft.StorageMover/storageMovers/agents. These are ARM management-plane calls.
• 🔴 Read access in the Arc machine's subscription and resource group too, which are frequently not the mover's. A permission gap there tends to surface as a validation failure on the machine ID rather than as an access error.
• ⚠️ Registering an agent grants it nothing. What the agent may read and write is decided by the endpoints and by the agent's own identity on the machine.

🔓 This module handles no credential. The SMBIOS UUID identifies hardware; it does not authenticate to anything, which is why it is not marked sensitive.

• An existing storage mover.
• An existing Azure Arc-enabled machine, with the Storage Mover agent software installed and running. None of that happens here.
• The Microsoft.StorageMover and Microsoft.HybridCompute resource providers registered on their respective subscriptions.
• The caller configures provider "azurerm" { features {} }, authentication, and the subscription.

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

data "azurerm_arc_machine" "boston" {
  name                = "boston-host-01"
  resource_group_name = "rg-onprem"
}

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

  storage_mover_id = module.mover.id
  name             = "agent-boston-01"

  # Both come from the SAME data source -- never type the UUID by hand.
  arc_virtual_machine_id   = data.azurerm_arc_machine.boston.id
  arc_virtual_machine_uuid = data.azurerm_arc_machine.boston.vm_uuid

  description = "Boston datacentre agent"
}

💡 Wiring both fields from one data source removes the two most likely failures at once: a hand-copied UUID, and a UUID that belongs to a different machine than the ID does.

Consumes

Emits

data "azurerm_arc_machine" "boston" {
  name                = "boston-host-01"
  resource_group_name = "rg-onprem"
}

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

  storage_mover_id = module.mover.id
  name             = "agent-boston-01"

  arc_virtual_machine_id   = data.azurerm_arc_machine.boston.id
  arc_virtual_machine_uuid = data.azurerm_arc_machine.boston.vm_uuid
}

output "agent_readiness" {
  value = {
    registered = module.agent.id != null
    # Constant true. Registration is not readiness.
    creates_nothing = module.agent.this_resource_registers_a_machine_it_does_not_create_one
  }
}

# REJECTED at plan -- a different resource type entirely.
arc_virtual_machine_id = "/subscriptions/.../providers/Microsoft.Compute/virtualMachines/vm1"

# ACCEPTED -- Arc-enabled servers live under Microsoft.HybridCompute.
arc_virtual_machine_id = "/subscriptions/.../providers/Microsoft.HybridCompute/machines/boston-host-01"

# BOTH of these are strings, so Terraform's type checker is perfectly happy.
arc_virtual_machine_id   = "3bb2c024-eba9-4d18-9e7a-1d772fcc5fe9"                     # the UUID
arc_virtual_machine_uuid = "/subscriptions/.../machines/boston-host-01"               # the ID

# ACCEPTED -- the canonical 36-character form Azure returns. Case does not matter.
arc_virtual_machine_uuid = "3bb2c024-eba9-4d18-9e7a-1d772fcc5fe9"
arc_virtual_machine_uuid = "3BB2C024-EBA9-4D18-9E7A-1D772FCC5FE9"

# ALL REJECTED at plan:
arc_virtual_machine_uuid = "{3bb2c024-eba9-4d18-9e7a-1d772fcc5fe9}"        # braces
arc_virtual_machine_uuid = "urn:uuid:3bb2c024-eba9-4d18-9e7a-1d772fcc5fe9" # urn form
arc_virtual_machine_uuid = "3bb2c024eba94d189e7a1d772fcc5fe9"              # unhyphenated
arc_virtual_machine_uuid = "3bb2c024-eba9-4d18-9e7a-1d772fcc5fe"           # truncated

# All THREE are accepted here -- this resource applies no pattern to `name`.
name = "agent.boston.01"
name = "-agent"
name = "an-agent-name-longer-than-sixty-four-characters-aaaaaaaaaaaaaaaaaaa"

# All THREE are REJECTED by terraform-azurerm-storage-mover-project, whose regex is
# ^[0-9a-zA-Z][-_0-9a-zA-Z]{0,63}$ -- no dots, no leading separator, 64 characters max.

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

  storage_mover_id = module.mover.id
  name             = "agent-boston-01"

  arc_virtual_machine_id   = data.azurerm_arc_machine.boston.id
  arc_virtual_machine_uuid = data.azurerm_arc_machine.boston.vm_uuid

  # The ONLY argument on this resource that updates in place.
  description = "Boston datacentre agent -- phase 2"
}

output "agent_topology" {
  value = {
    mover_subscription = module.agent.storage_mover_subscription_id
    arc_subscription   = module.agent.arc_machine_subscription_id
    cross_subscription = module.agent.the_arc_machine_is_in_a_different_subscription
    cross_rg           = module.agent.the_arc_machine_is_in_a_different_resource_group
  }
}

data "azurerm_arc_machine" "hosts" {
  for_each = toset(["boston-host-01", "dublin-host-01"])

  name                = each.key
  resource_group_name = "rg-onprem"
}

module "agents" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-storage-mover-agent.git?ref=v1.0.0"
  for_each = data.azurerm_arc_machine.hosts

  storage_mover_id = module.mover.id
  name             = "agent-${each.key}"

  arc_virtual_machine_id   = each.value.id
  arc_virtual_machine_uuid = each.value.vm_uuid
}

resource "azurerm_storage_mover_job_definition" "archive" {
  name                     = "archive-nightly"
  storage_mover_project_id = module.project.id
  copy_mode                = "Additive"

  source_name = azurerm_storage_mover_source_endpoint.nfs.name
  target_name = azurerm_storage_mover_target_endpoint.blob.name

  # The agent by NAME -- not module.agent.id.
  agent_name = module.agent.name
}

terraform import 'module.agent.azurerm_storage_mover_agent.this' \
  "/subscriptions/SUB/resourceGroups/RG/providers/Microsoft.StorageMover/storageMovers/mover-exit/agents/agent-boston-01"

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

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

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

  name                = "mover-datacentre-exit"
  resource_group_name = module.rg.name
  location            = module.rg.location
}

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

  storage_mover_id = module.mover.id
  name             = "boston-exit"
}

# The machine already exists and is already Arc-enabled. Nothing here creates it.
data "azurerm_arc_machine" "boston" {
  name                = "boston-host-01"
  resource_group_name = "rg-onprem"
}

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

  storage_mover_id = module.mover.id
  name             = "agent-boston-01"

  arc_virtual_machine_id   = data.azurerm_arc_machine.boston.id
  arc_virtual_machine_uuid = data.azurerm_arc_machine.boston.vm_uuid

  description = "Boston datacentre agent"
}

output "migration_scaffold" {
  value = {
    mover      = module.mover.name
    project_id = module.project.id
    agent_name = module.agent.name
    cross_sub  = module.agent.the_arc_machine_is_in_a_different_subscription
    # Honest about what is still missing:
    moves_data = !module.mover.this_resource_moves_no_data_by_itself
  }
}

Parent — storage_mover_id (required, force-new). Identity — name (required, force-new, no pattern). The machine — arc_virtual_machine_id, arc_virtual_machine_uuid (both required, both force-new). Optional — description, the only argument that updates in place. Tail — timeouts. There is no tags argument and no location.

variable "arc_virtual_machine_id" {
  type = string # Microsoft.HybridCompute/machines ONLY -- an Azure VM is rejected
}

variable "arc_virtual_machine_uuid" {
  type = string # canonical 36-char UUID ONLY -- no braces, no urn:, no unhyphenated form
}

variable "name" {
  type = string # not-empty is the provider's ONLY rule here -- the project and both
                # endpoints share a regex this resource does not have
}

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
}

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

Everything difficult about this resource happens before Terraform is involved. The agent runs on a machine that must be built, onboarded to Azure Arc, and running the Storage Mover agent software — none of which this resource does, and none of which it can see. What it writes is a registration record: the mover now knows a machine by ID and by SMBIOS UUID. A successful apply is therefore a much weaker statement than it looks, which is why the module says so as a constant output rather than leaving the reader to infer it.

The two Arc fields are the sharpest edge, and the type system offers no help. One is a Resource ID under Microsoft.HybridCompute/machines, the other a UUID; both are strings, so transposing them is a perfectly valid configuration as far as Terraform is concerned. Both are validated by shape here, and each message names the other field, because "invalid format" would send someone to fix the wrong argument. The provider is genuinely strict on both: an Azure VM ID under Microsoft.Compute is refused because an Arc-enabled server is a different resource type, and the UUID parser accepts only the canonical 36-character form — braces, a urn:uuid: prefix and the unhyphenated form are all rejected. Both rules are mirrored exactly here, so the refusals happen at parse time.

Wiring the azurerm_arc_machine data source is worth more than any validation. It removes the failure rather than catching it: both fields come from one lookup, so they cannot disagree about which machine was meant, and nobody has to copy a UUID by hand. The distinction that matters is between a malformed UUID, which is caught offline, and a well-formed UUID belonging to the wrong machine, which is caught by nothing at all and either fails at apply or quietly registers an agent nobody intended.

The naming rule is where this family surprises people. This resource applies no pattern to name — only a not-empty check — while azurerm_storage_mover_project, in the same service package, enforces ^[0-9a-zA-Z][-_0-9a-zA-Z]{0,63}$. Names with dots, names beginning with a hyphen, and names longer than 64 characters are all legal here and illegal there. Both behaviours are proven by fixtures on both sides, and each module emits the asymmetry, because the natural assumption — that resources in one service share a naming convention — is wrong here and produces a failure only on the next resource you write. It is worse than a straight disagreement: the project and both endpoints share one regex and this resource alone has none, so three agreeing examples make the exception look like the rule.

In a composition, name matters more than id. A job definition names this agent through agent_name, so the name is the contract. That also makes a rename doubly disruptive: it replaces the agent, because name is force-new, and it breaks whatever referenced the old one. Four of the five arguments are force-new in total, so almost any change here is a destroy-and-create; only description updates in place, through a read-modify-write that preserves properties changed outside Terraform rather than reverting them.

🔒 There is no credential on this resource. The security-relevant point is scope: registering an agent grants it nothing, and what it may read and write is decided elsewhere entirely.

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

19 negative fixtures fired the checks they targeted, and 7 positive fixtures passed clean. The negatives cover the mover ID four ways, all three name rules, the Arc machine ID four ways — empty, an Azure VM ID, a storage mover ID, and a bare UUID in the swap position — and the UUID six ways, including braces, the urn:uuid: form, the unhyphenated 32-character form, a truncated value and a non-hex digit, each of which the provider's own parser also rejects.

The positives prove the naming asymmetry deliberately and in both directions: agent.boston.01, -agent and a 65-character name all pass here, and the same three values are negative fixtures in terraform-azurerm-storage-mover-project, where they fire. An upper-case UUID also passes, because the parser is case-insensitive on hex.

The computed outputs were driven through the same harness rather than assumed: the parsed mover and machine names, and both the cross-resource-group and cross-subscription flags, checked in a same-place case and a different-place case.

What only a real plan/apply exercises: whether the mover exists, whether the Arc machine exists, and the requires-import guard.

What nothing exercises: whether the UUID belongs to the machine the ID names. That pairing is why the data source is the recommended wiring rather than a convenience.

id                                     = ".../storageMovers/mover-exit/agents/agent-boston-01"
name                                   = "agent-boston-01"
storage_mover_name                     = "mover-exit"
arc_machine_name                       = "boston-host-01"
arc_machine_resource_group_name        = "rg-onprem"
arc_virtual_machine_uuid               = "3bb2c024-eba9-4d18-9e7a-1d772fcc5fe9"
the_arc_machine_is_in_a_different_resource_group = true
the_arc_machine_is_in_a_different_subscription   = true
force_new_fields                       = ["name", "storage_mover_id", "arc_virtual_machine_id", "arc_virtual_machine_uuid"]

• azurerm_storage_mover_agent
• azurerm_arc_machine data source
• azurerm_storage_mover_job_definition
• Azure Storage Mover agent overview
• Azure Arc-enabled servers
• Sibling modules: terraform-azurerm-storage-mover, terraform-azurerm-storage-mover-project, terraform-azurerm-resource-group
• This module's SCOPE.md

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