Azure Resource Manager Skill

Agent Summary

Use this skill when an agent needs an ARM-scoped token and a safe REST wrapper for Azure management-plane work. Create a context with Connect-AzureApi.ps1, then pass that context to Invoke-AzureRestMethod.ps1 for Azure subscriptions, resource groups, providers, or async operation polling.

When to Use

• List, read, create, update, or delete Azure resources through ARM.
• Work in Azure commercial, US Gov, or China without rewriting endpoints.
• Capture Azure-AsyncOperation, Operation-Location, or Location headers for long-running operations.

Required Parameters

Connect-AzureApi.ps1

Invoke-AzureRestMethod.ps1

Example Agent Prompts

• "List all resource groups in this Azure subscription."
• "Create a storage account through ARM and capture the async operation URL."
• "Call an Azure REST endpoint directly when there is no SDK wrapper."

Example Agent Workflow

$ctx = ./skills/azure/Connect-AzureApi.ps1 -AuthenticationType ManagedIdentity -Environment AzureCloud -SubscriptionId $env:SUBSCRIPTION_ID

$groups = ./skills/azure/Invoke-AzureRestMethod.ps1 -Uri "/subscriptions/$($ctx.SubscriptionId)/resourcegroups" -ApiVersion "2021-04-01" -AuthContext $ctx -Paginate

Security Caveats

• Prefer ManagedIdentity or Federated authentication; never default to client secrets.
• Scope RBAC as narrowly as possible at the subscription, resource group, or resource level.
• Treat async completion as incomplete until the returned operation endpoint reports success.

Overview

This skill set covers Azure Resource Manager (ARM) authentication and REST calls for sovereign cloud aware automation. Use Connect-AzureApi.ps1 to build an ARM context, then Invoke-AzureRestMethod.ps1 to execute and track ARM operations.

Authentication

• Auth types for ARM: ManagedIdentity, Federated (OIDC), Certificate, ClientCredentials (client secret).
• Token audience: https://management.azure.com/ (use the environment's ARM endpoint, for example https://management.usgovcloudapi.net or https://management.chinacloudapi.cn).
• Notes on service principal vs managed identity for ARM
  • Service principal (certificate or client secret) uses Entra ID app authentication and must have appropriate RBAC permissions on the target scope.
  • Managed identity avoids credential material and relies on the platform to obtain the ARM token via IMDS or the local identity endpoint.

Endpoints

Skills

Toolchain

Patterns & Caveats

• Async operations (Azure-AsyncOperation header)
• Subscription scoping
• api-version requirements
• ARM template deployment vs direct REST

Examples

1. List resource groups (GET, with pagination)

$ctx = ./skills/azure/Connect-AzureApi.ps1 -AuthenticationType ManagedIdentity -Environment AzureCloud -SubscriptionId $env:SUBSCRIPTION_ID

$result = ./skills/azure/Invoke-AzureRestMethod.ps1 `
  -Uri "/subscriptions/$($ctx.SubscriptionId)/resourcegroups" `
  -ApiVersion '2021-04-01' `
  -AuthContext $ctx `
  -Paginate

$result.Value | Select-Object -First 10

2. Run a PUT that returns async metadata (capture operation URLs)

$ctx = ./skills/azure/Connect-AzureApi.ps1 -AuthenticationType Certificate -Environment AzureCloud -TenantId $env:TENANT_ID -ClientId $env:CLIENT_ID -CertificatePath "/secure/certs/automation.pfx" -SubscriptionId $env:SUBSCRIPTION_ID

$payload = @{
  location = 'eastus'
  kind      = 'StorageV2'
  sku       = @{ name = 'Standard_LRS' }
}

$resp = ./skills/azure/Invoke-AzureRestMethod.ps1 `
  -Method PUT `
  -Uri "/subscriptions/$($ctx.SubscriptionId)/resourceGroups/$env:RG/providers/Microsoft.Storage/storageAccounts/$env:STORAGEACCOUNTNAME" `
  -ApiVersion '2023-05-01' `
  -Body $payload `
  -AuthContext $ctx

# Use one of these for polling, depending on what the service returns
$resp.OperationLocation
$resp.AzureAsyncOperation
$resp.Location

3. Poll async status using the captured Azure-AsyncOperation URL

$ctx = ./skills/azure/Connect-AzureApi.ps1 -AuthenticationType Federated -Environment AzureCloud -TenantId $env:TENANT_ID -ClientId $env:CLIENT_ID -FederatedToken $env:AZURE_FEDERATED_TOKEN -SubscriptionId $env:SUBSCRIPTION_ID

$put = ./skills/azure/Invoke-AzureRestMethod.ps1 -Method PUT -Uri "/subscriptions/$($ctx.SubscriptionId)/resourceGroups/$env:RG/providers/Microsoft.Resources/deployments/$env:DEPLOYMENTNAME" -ApiVersion '2021-04-01' -Body @{ properties = @{ mode = 'Incremental'; templateLink = @{ uri = $env:TEMPLATE_URI } } } -AuthContext $ctx

$pollUri = $put.AzureAsyncOperation
while ($pollUri) {
  Start-Sleep -Seconds 5
  $status = ./skills/azure/Invoke-AzureRestMethod.ps1 -Method GET -Uri $pollUri -AuthContext $ctx
  $state = $status.Value.status
  if ($state -in @('Succeeded','Failed')) { break }
  $pollUri = $null  # if the server stopped returning an async URL, fall out
}

# 4) Use a config.yaml profile
$ctx = ./skills/azure/Connect-AzureApi.ps1 -Profile "prod" -ConfigPath "./config.yaml"

# 5) Use prefixed environment variables
$ctx = ./skills/azure/Connect-AzureApi.ps1 -Prefix "GOV" -Environment AzureUSGovernment

Prerequisites

• Required modules: PowerShell 7.2+, MSAL.PS (recommended for certificate token acquisition, used by Common.psm1), Azure CLI az if MSAL.PS is unavailable for certificate flows.
• Required roles: RBAC permissions on the target scope (subscription or resource group), for example Reader for read-only operations, Contributor or higher for PUT/PATCH/DELETE, and deployment permissions for ARM template deployments.

Related Docs

• Auth Patterns
• Token Chaining
• Environment Endpoints