☁️ Azure Deployment Script (Azure PowerShell) Terraform Module

Runs an Azure PowerShell script as part of a deployment, in a container instance Azure creates and then cleans up, and returns whatever the script emits. Targets hashicorp/azurerm ~> 4.0.

• 🖥️ Runs an Azure PowerShell script during a deployment, in a transient container instance.
• 🪪 Executes as one or more user-assigned managed identities — which is the real blast radius, not the script text.
• 📤 Returns the script's outputs as a JSON string.
• 🔒 Marks the environment-variable set and the storage-account block sensitive, and unwraps the reviewable parts back out.
• 🚧 Rejects the environment_variable name collisions the provider's set hash silently resolves in your favour or against it.
• 🧹 Defaults to omitting your storage account entirely, so no storage key exists in configuration or state.

💡 Why it matters: this is the one resource in the library that executes code you wrote. Everything else declares desired state; this runs a shell. That changes what review means — a change here is an execution, and the identity it runs as decides what that execution can reach.

If this module saved you time:

• ⭐ Star the repository — it genuinely 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"]
    UAI["terraform-azurerm-user-assigned-identity"]
    RA["terraform-azurerm-role-assignments"]
    SA["terraform-azurerm-storage-account"]
    subgraph scripts["The two deployment-script modules, one per shell"]
        CLI["terraform-azurerm-resource-deployment-script-azure-cli"]
        PS["terraform-azurerm-resource-deployment-script-azure-power-shell"]
    end
    TARGET["whatever the script touches"]
    RG -->|"resource_group_name"| CLI
    RG -->|"resource_group_name"| PS
    RG -->|"resource_group_name"| UAI
    UAI -->|"identity_ids: the script runs as this"| CLI
    UAI -->|"identity_ids: the script runs as this"| PS
    UAI -->|"principal_id"| RA
    RA -->|"grants the permissions the script will actually have"| TARGET
    SA -.->|"optional: supplying a key is the WEAKER choice"| CLI
    SA -.->|"optional: supplying a key is the WEAKER choice"| PS
    CLI -->|"runs arbitrary code against"| TARGET
    PS -->|"runs arbitrary code against"| TARGET
    style CLI fill:#0078D4,stroke:#004578,color:#ffffff
    style PS fill:#0078D4,stroke:#004578,color:#ffffff
    style UAI fill:#004578,stroke:#004578,color:#ffffff
    style RG fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style RA fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style SA fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style TARGET fill:#F3F2F1,stroke:#8A8886,color:#201F1E

The resource group and the managed identity are the two real upstreams. Note the storage-account edge is dotted and optional in the weaker direction: supplying your own account means supplying its key, and omitting the block is the stronger default.

flowchart TB
    SCRIPT["script_content OR primary_script_uri, exactly one"]
    VER["version_number: one of only two places the twins differ"]
    IDIN["identity_ids: the real blast radius"]
    ENVIN["environment_variable set, SENSITIVE as a whole"]
    SAIN["storage_account, SENSITIVE, and better omitted"]
    THIS["azurerm_resource_deployment_script_azure_power_shell.this"]
    ACI["a container instance plus a file share, created and then cleaned up"]
    OUT["outputs: whatever the script wrote, NOT redacted"]
    FACTS["names, counts and posture flags, unwrapped"]
    TAGS["tags: the only field that can ever be updated"]
    SCRIPT --> THIS
    VER --> THIS
    IDIN -->|"the script runs with THESE permissions, not yours"| THIS
    ENVIN -->|"names unwrapped back out; values never"| THIS
    SAIN -.->|"omit it and Azure makes a temporary one, so no key exists"| THIS
    THIS --> ACI
    THIS --> OUT
    THIS --> FACTS
    TAGS --> THIS
    style THIS fill:#0078D4,stroke:#004578,color:#ffffff
    style ACI fill:#004578,stroke:#004578,color:#ffffff
    style ENVIN fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style SAIN fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style IDIN fill:#8A2B06,stroke:#5C1D04,color:#ffffff
    style SCRIPT fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style VER fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style OUT fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style FACTS fill:#F3F2F1,stroke:#8A8886,color:#201F1E
    style TAGS fill:#F3F2F1,stroke:#8A8886,color:#201F1E

This diagram is shared with terraform-azurerm-resource-deployment-script-azure-cli, deliberately and with no distinction invented. The two resources are implemented from a single file upstream and their schemas are byte-identical; only the version_number grammar and the script's output convention differ, and both are called out where they apply.

Schema notes that bite, each confirmed against the provider's own source at the pinned version:

• 🔴 tags is the only mutable field. The update path decodes a patch model containing tags and nothing else; every other argument is force-new, so every other change replaces the resource and re-runs the script.
• 🔴 The environment_variable set hash is strings.ToLower(name) and nothing else. Two entries whose names differ only in case collide and one is silently discarded. This module rejects that.
• 🔴 Neither secure_value nor storage_account.key is read back from Azure. The provider repopulates both from prior state, matching secure values by variable name — so renaming a variable silently drops its secure value.
• ⚠️ ExactlyOneOf binds primary_script_uri and script_content, and the binary schema does not carry that fact. It is enforced upstream regardless; this module re-expresses it to fail earlier and in its own words.
• ⚠️ The name regex is looser than its own error message. Its character class contains an unintended range that also admits *, + and ,. Azure publishes no naming rule for deploymentScripts, so this module follows the documented set — its own judgement, stated as such.
• ⚠️ timeout defaults to P1D, the maximum. A hung script holds a container instance for a full day and is billed for it.
• ⚠️ Identity is user-assigned only — commonschema.UserAssignedIdentityOptionalForceNew(). There is no system-assigned option, so this module takes the IDs directly rather than a type field with one legal value.
• ⚠️ outputs is documented as "List of script outputs" but the schema declares a plain string. jsondecode it.
• ✅ cleanup_preference already defaults to the closed choice, Always. This module keeps it rather than diverging.

🔴 The permission that matters most is not in this table. The script runs with the permissions of the identities in identity_ids, and those are granted elsewhere — by a role assignment on whatever the script touches. A reviewer approving a change to this module is approving an execution with that identity's rights, so the script text and the identity's role assignments have to be read together. Neither half is sufficient alone.

✅ Plan access is not credential access. Neither secret on this resource is fetched from Azure during a refresh.

🔒 The exposure is the state file, which no Azure role governs.

• Microsoft.Resources registered, plus Microsoft.ContainerInstance and Microsoft.Storage for the transient resources the service creates.
• A region that supports Azure Container Instances.
• A user-assigned managed identity, if the script needs to touch Azure at all, with role assignments granting exactly what it needs.
• 🔒 An encrypted, access-controlled remote backend, as a stated prerequisite — secure_value and any storage key land in state in plaintext.
• Quota for a container instance in the target region. A script cannot start without one.

terraform-azurerm-resource-deployment-script-azure-power-shell/
├── providers.tf    # required_version + pinned azurerm; no provider block
├── variables.tf    # 5 required inputs, 13 optional, 39 validations
├── main.tf         # the keystone `this` + dynamic blocks + derived locals
├── outputs.tf      # 25 outputs; id first; none sensitive
├── README.md       # this file
├── SCOPE.md        # the cross-module contract
├── LICENSE         # MIT
└── .gitignore      # the canonical library ignore set

provider "azurerm" {
  features {}
}

module "migration_script" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-deployment-script-azure-power-shell.git?ref=v1.0.0"

  name                = "run-migration"
  resource_group_name = module.rg.name
  location            = "eastus2"
  version_number      = "9.7"
  retention_interval  = "PT6H"

  script_content = "$DeploymentScriptOutputs = @{ status = 'ok' }"
}

The caller configures the provider, its authentication and the mandatory features {} block. The module declares none of them.

Consumes

Emits

module "hello" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-deployment-script-azure-power-shell.git?ref=v1.0.0"

  name                = "hello"
  resource_group_name = module.rg.name
  location            = "eastus2"
  version_number      = "9.7"
  retention_interval  = "PT1H"

  script_content = "$DeploymentScriptOutputs = @{ greeting = 'hello' }"
}

output "greeting" {
  value = jsondecode(module.hello.outputs).greeting
}

module "tagger" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-deployment-script-azure-power-shell.git?ref=v1.0.0"

  name                = "bulk-tagger"
  resource_group_name = module.rg.name
  location            = "eastus2"
  version_number      = "9.7"
  retention_interval  = "PT2H"

  identity_ids = [module.script_identity.id]

  script_content = "Get-AzResource -Tag @{ env = 'dev' } | Select-Object -ExpandProperty ResourceId"
}

environment_variable = [
  { name = "TARGET_ENV", value = "staging" },
  { name = "API_TOKEN", secure_value = var.api_token },
]

# REJECTED by this module:
environment_variable = [
  { name = "PATH", value = "/a" },
  { name = "path", value = "/b" },
]

primary_script_uri = "https://raw.githubusercontent.com/contoso/scripts/v3/migrate.ps1"

supporting_script_uris = [
  "https://raw.githubusercontent.com/contoso/scripts/v3/lib.ps1",
]

force_update_tag = "2026-08-01T09:00:00Z"

cleanup_preference = "OnSuccess"

timeout_duration   = "PT30M"
retention_interval = "PT6H"

timeouts = {
  create = "45m"
}

storage_account = {
  name = "mydeployscripts"
  key  = var.storage_account_key
}

container = {
  container_group_name = "cg-migration-runner"
}

check "deployment_script_posture" {
  assert {
    condition     = !module.migration_script.uses_own_storage_account
    error_message = "This deployment script supplies a storage account key; let Azure create a temporary account instead."
  }

  assert {
    condition     = !module.migration_script.retains_scratch_after_failure
    error_message = "cleanup_preference is not Always, so the script body and its variables outlive the run."
  }

  assert {
    condition     = module.migration_script.runs_with_identity
    error_message = "This script has no managed identity, so any Azure call inside it will fail."
  }
}

check "token_is_secure" {
  assert {
    condition     = contains(module.migration_script.secure_environment_variable_names, "API_TOKEN")
    error_message = "API_TOKEN must be passed as secure_value, not as a plain value or on the command line."
  }
}

# Updates in place -- the only thing that does:
tags = { owner = "platform" }

# Everything else REPLACES the resource, which re-runs the script:
script_content     = "..."
version_number     = "9.8"
identity_ids       = [var.replacement_identity_id]
timeout_duration   = "PT10M"

provider "azurerm" {
  features {}
}

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

  name     = "rg-platform-tools"
  location = "eastus2"
}

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

  name                = "id-deployment-script"
  resource_group_name = module.rg.name
  location            = "eastus2"
}

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

  scope = module.rg.id

  role_assignments = {
    reader = {
      principal_id         = module.script_identity.principal_id
      role_definition_name = "Reader"
      principal_type       = "ServicePrincipal"
    }
  }
}

module "inventory_script" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-deployment-script-azure-power-shell.git?ref=v1.0.0"

  name                = "rg-inventory"
  resource_group_name = module.rg.name
  location            = "eastus2"
  version_number      = "9.7"
  retention_interval  = "PT6H"
  timeout_duration    = "PT10M"

  identity_ids = [module.script_identity.id]

  environment_variable = [
    { name = "TARGET_RG", value = module.rg.name },
  ]

  script_content = <<-SCRIPT
    $count = (Get-AzResource -ResourceGroupName $env:TARGET_RG).Count
    $DeploymentScriptOutputs = @{ count = $count }
  SCRIPT
}

output "resource_count" {
  value = jsondecode(module.inventory_script.outputs).count
}

No output is sensitive. No secret is emitted: both secrets on this resource are inputs the caller already holds.

This resource executes code, and that reframes what a plan means. Everywhere else in this library a plan describes desired state. Here a non-tag change is an execution: the provider's update path carries tags and nothing else, so altering the script, its version, its variables, its identity or its timeout replaces the resource and runs the script again. There is no edit, and force_update_tag — the field whose whole purpose is triggering a re-run — is itself force-new. Reviewers should read a diff on this module as "we are about to run this", not "we are about to change this".

The identity is the blast radius, and it is granted somewhere else. The script runs with the permissions of whatever is in identity_ids, which this module consumes but does not create or empower. A change here and a role assignment over there combine into the actual capability, and neither file shows the whole picture. That is why the module emits identity_ids and identity_count — so a policy check can at least assert the script runs as an approved identity — and why the end-to-end example puts the role assignment in the same frame.

Two secrets, both inputs, neither read back. environment_variable.secure_value and storage_account.key are supplied by the caller and never returned by Azure; the provider repopulates them from prior state on every read. The trade cuts both ways and both directions are worth stating: plan access is not credential access, because a refresh fetches neither from Azure; and drift is invisible, because nothing will ever notice if either changes outside Terraform. There is a sharper corollary in the flatten: secure values are matched to variables by name, so renaming a variable silently drops its secure value.

Collection-level sensitivity costs different amounts in different places, and both cases appear here. Marking environment_variable protects the secure values but redacts the variable names and plain values with them, so the names are unwrapped back out — the reviewable part restored, the secrets left alone. Marking storage_account protects the key but redacts the account name, which is public, so that is unwrapped too. In both cases the unwrap needs two levels: each element drawn from a sensitive collection carries a mark, and the list a comprehension builds from those elements carries another that propagates into length(). A third trap sits alongside them — var.storage_account != null is itself a sensitive bool, and a ternary's condition contaminates its result, so even a plain presence flag needs unwrapping.

The defaults were examined one at a time rather than flipped as a group. cleanup_preference already defaults to the closed choice and is left alone. timeout_duration defaults to the maximum, which is genuinely unhelpful, but lowering it would silently kill legitimate long-running scripts and the risk is cost rather than exposure — so it is reported through uses_maximum_timeout instead of changed. storage_account defaults to absent, which is the strongest available position because it means no key exists at all rather than a key protected well.

Three clocks, easily confused. timeout_duration bounds the script, retention_interval bounds how long Azure keeps the record — deleting it, and its outputs, when it expires — and timeouts.create bounds how long Terraform waits. The last must exceed the first, or Terraform gives up while the script is still running.

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

Pin the module with ?ref=v1.0.0, never a branch. This library is plan-only: a human applies from CI.

What the offline gate covers:

• terraform validate proves the configuration parses and every type is satisfied.
• terraform fmt -check proves the HCL is canonically formatted.
• Feeding deliberately bad .tfvars through terraform console fires the input validations — all 39 validation blocks in this module have been proven reachable, each by a fixture that triggers it, with zero condition-evaluation errors.
• All 14 derived locals have been driven to more than one value across the good fixtures, including both the sensitive-collection unwraps.

What only a real plan or apply can exercise:

• Whether the Azure PowerShell version exists — the module checks the shape and cannot know the catalogue.
• Whether the region has container-instance quota.
• Whether the script's identity holds the permissions the script assumes.
• The script itself, which is the part that actually matters and which no static check can evaluate.

id                                = "/subscriptions/.../resourceGroups/rg-platform-tools/providers/Microsoft.Resources/deploymentScripts/rg-inventory"
name                              = "rg-inventory"
location                          = "eastus2"
outputs                           = "{\"count\":17}"
has_outputs                       = true
script_is_inline                  = true
script_is_remote                  = false
environment_variable_names        = ["TARGET_RG"]
secure_environment_variable_names = []
environment_variable_count        = 1
secure_variable_count             = 0
uses_secure_variables             = false
runs_with_identity                = true
identity_count                    = 1
storage_account_name              = null
uses_own_storage_account          = false
uses_maximum_timeout              = false
retains_scratch_after_failure     = false
tags_are_the_only_mutable_field   = true

• azurerm_resource_deployment_script_azure_power_shell — provider resource reference.
• Deployment scripts in ARM templates — what the service does and how outputs are returned.
• Azure PowerShell image tags — the canonical version list.
• Sibling modules: terraform-azurerm-resource-deployment-script-azure-power-shell, terraform-azurerm-user-assigned-identity, terraform-azurerm-role-assignments, terraform-azurerm-resource-group.
• This module's SCOPE.md.

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