Azure Knowledge Patch

Microsoft Azure compatibility guide

Use this skill when changing Azure infrastructure, automation, authentication, or service configuration. Start with the quick-reference guidance below, then open the topic reference that matches the resource or tool being changed.

Reference index

Working method

1. Identify the controlling client: AzureRM, AzAPI, Azure CLI, Azure PowerShell, a Bicep binary, an Identity SDK, or a direct ARM API.
2. Read the project's manifest and lockfile before choosing syntax. Keep a deliberately pinned API or client behavior unless the change requires a migration.
3. Confirm the Azure cloud, tenant, subscription, region, resource provider, and API version. Public-cloud assumptions do not always hold in sovereign clouds.
4. Make changed defaults explicit in reproducible automation. Treat JSON and table output as interfaces and test consumers against the current shape.
5. For stateful or networking migrations, inspect the service-specific transition rules before applying. Some changes require deallocation, replacement, downtime, or an explicit outbound path.

Breaking changes and deprecations

AzureRM 4 provider setup

• Every provider instance needs subscription_id or ARM_SUBSCRIPTION_ID; Azure CLI authentication no longer supplies the active subscription implicitly.
• Choose resource_provider_registrations from core, extended, all, none, or the transitional legacy set. Add an exact custom list through resource_providers_to_register.
• Migrate removed SQL resources to azurerm_mssql_*, MySQL Single Server to Flexible Server, and other removed services or resources to the replacements listed in the Terraform reference.
• Update renamed AKS, diagnostic-setting, Cosmos DB, Service Bus, networking, Container Registry, and VMSS fields before upgrading.
• Remove positional indexing where AzureRM changed lists to sets. Pin values that must not follow changed security, SKU, network, or upgrade defaults.

provider "azurerm" {
  subscription_id                 = var.subscription_id
  resource_provider_registrations = "core"
  resource_providers_to_register  = ["Microsoft.ContainerService"]
  features {}
}

AzAPI 2 provider behavior

• Use native HCL objects for body and consume output as an HCL object; remove surrounding jsonencode and jsondecode calls.
• Replace ignore_body_changes with a precise lifecycle.ignore_changes path. Build any former global naming prefix or suffix into each resource name.
• Managed identity is opt-in because use_msi defaults to false.
• Review state after the default-output change, or set disable_default_output = true when computed response output is unwanted.
• Remove deprecated retry.multiplier, retry.randomization_factor, and provider-level maximum_busy_retry_attempts; current retry defaults replace them.

Authentication and authorization

• Do not use az login --username for a user-assigned managed identity. Pass --client-id, --object-id, or --resource-id.
• az role assignment delete no longer means delete everything when selection criteria are absent. Always specify the intended assignments.
• Azure Resource Manager enforces MFA server-side for affected user write operations. A claims challenge can follow a sign-in that is sufficient for reads; use challenge-capable clients or move unattended jobs to workload identities.
• Username/password authentication cannot satisfy mandatory MFA and is deprecated across Identity SDKs and MSAL clients.
• Azure AD Graph is retired. Use Microsoft Graph endpoints and the Microsoft Graph application-manifest shape.
• Get-AzAccessToken returns a SecureString token. PowerShell scripts must not assume plaintext output.

Azure CLI output and defaults

• Re-test parsers for disk, snapshot, gallery application, resource-list, access-restriction, ACR token, Key Vault key, and consumption output.
• az webapp list-runtimes returns structured objects rather than flat strings; filter with --runtime and --support.
• AKS creation now follows --no-ssh-key behavior by default.
• VM and VMSS creation defaults to Standard_D2s_v5 when no size is supplied.
• Linux App Service plans default to P0V3, and App Service plan creation defaults to Linux unless Windows is selected explicitly.
• The core CLI no longer supplies CDN commands; install and manage the CDN extension where automation depends on them.

Network and service retirements

• Basic Load Balancer and Basic public IP are retired and unsupported. Plan a resource-specific migration to matching Standard SKUs, including NSG and explicit outbound requirements.
• New virtual networks created with the newer API default subnets to private outbound behavior. Configure NAT Gateway, a Standard load-balancer outbound rule, a Standard public IP, or firewall/NVA routing as appropriate.
• Deallocate existing VMs after changing a subnet's default-outbound setting so the NIC configuration receives the change.
• API Management's direct management API and ADAL-based developer-portal identity providers are retired. Use ARM-based management and MSAL with authorization code plus PKCE.
• Key Vault control-plane APIs older than 2026-02-01 retire on February 27,
  2027. New vaults created through the current stable API default to RBAC unless enableRbacAuthorization is explicitly false.
• Azure SQL Database control-plane API 2014-04-01 retires on June 30, 2027; some old operation groups require workflow redesign rather than an API-version substitution.

Common workflows

Build and parse Azure resource IDs

With Terraform 1.8 or later, prefer provider functions over string assembly. AzureRM supplies normalise_resource_id and parse_resource_id; AzAPI adds scope-specific builders and an API-type-aware parser. Preserve caller-owned name casing when normalizing Azure-controlled ID segments.

Validate AzAPI before deployment

Set enable_preflight = true to validate supported resource properties during planning. Use ignore_not_found plus exists for absence-aware reads, and use sensitive_body or sensitive_response_export_values for secret payloads. For list reconciliation, identify entries with list_unique_id_property before allowing unmanaged remote items.

Register resource providers deliberately

Registration completes independently by region. A provider may remain globally Registering while a target region is usable. Register only required providers, and query each resource type's metadata for API versions and locations instead of assuming a provider-wide value.

az provider show --namespace Microsoft.Batch \
  --query "resourceTypes[?resourceType=='batchAccounts'].apiVersions | [0]" \
  --output tsv

Author and test Bicep

• Layer parameter files with extends; only parameter assignments inherit, and object or array values require explicit spread-based merging.
• Mark string or object outputs with @secure() to keep values out of deployment history and command output.
• Use direct bicep snapshot for deterministic local deployment snapshots and bicep console for expression experiments. Neither feature is an az bicep substitute.
• Module identity syntax is recognized but is not yet deployable by the backend service.

Keep AKS and ACR automation explicit

• Pin node VM size, OS SKU, outbound type, storage mode, SSH-key behavior, and upgrade availability when those choices affect cluster invariants.
• Treat ACNS, deployment safeguards, managed namespaces, Automatic clusters, Managed Gateway API, artifact streaming, control-plane metrics, and rollback as separate opt-in workflows with their documented command flags.
• ACR token audience, endpoint protocol, content-trust deprecation, regional endpoint login, cache identity, and writable cache settings can affect login and repository automation.

Choose a credential chain intentionally

Set AZURE_TOKEN_CREDENTIALS=dev, prod, or a credential class name to constrain DefaultAzureCredential. Account for the managed-identity IMDS retry window when sizing startup timeouts. Claims-challenge support differs among Azure CLI, Azure PowerShell, Azure Developer CLI, and language credentials; do not assume one tool-backed credential can substitute for another.

Stabilize data-service provisioning

• Pass MySQL version, IOPS scaling, storage redundancy, backup interval, and maintenance choices explicitly where supported; remove options that later commands have dropped.
• For PostgreSQL, verify engine capability, compute tier, storage type, network mode, HA terminology, and mirroring restrictions for the operation being performed.
• Treat Azure Files OAuth, NFS, encryption-in-transit, user-delegation SAS, and provisioned-share controls as distinct authorization and protocol paths.
• Review SQL, Cosmos DB, Backup, and NetApp Files references before changing retention, restore, replication, encryption, or network behavior.

Inventory retirements

Use Azure Advisor retirement metadata and impacted-resource APIs for public Azure, then query the Resource Graph advisorresources table for affected resource IDs and dates. Filter out upgrade-only recommendations that have no retiring feature. Advisor coverage is incomplete, so use the retirement analyzer for sovereign and national-partner clouds.