[AI-Suggested] Content update request from Product Release signal: azure-cli azure-cli-2.89.0

[learn-build-service-ppe]

Background

A recent product update has been released that may impact our documentation. This could include new features, changes to existing functionality, or other product enhancements.
Your Action Required: Please review the suggestions below and update the relevant documentation to ensure accuracy and completeness.

Signal Details:

• Title: azure-cli azure-cli-2.89.0
• Source URL: https://github.com/Azure/azure-cli/releases/tag/azure-cli-2.89.0
• Repository: https://github.com/Azure/azure-cli
• ReleaseWindowUtc: 2026-07-07 04:30:07Z - 2026-08-04 00:32:48Z
• TargetBranch: release
• currentTag: azure-cli-2.89.0
• targetCommitish: release
• releaseUrl: https://github.com/Azure/azure-cli/releases/tag/azure-cli-2.89.0
• previousTag: azure-cli-2.88.0

Source Signal Summary

Details

• Azure CLI az appservice plan managed instance features are now GA (no longer marked [Preview] in az <command> --help): removes the preview flag from az appservice plan managed-instance (and az appservice plan managed-instance instance list), az appservice plan identity, and from the related parameters --is-managed-instance, --mi-system-assigned, --mi-user-assigned, --default-identity, --rdp-enabled, --vnet, --subnet, --registry-adapter, --install-script, --storage-mount on az appservice plan create/update, plus --managed-instance-enabled on az appservice list-locations; additionally, az appservice list-locations --managed-instance-enabled now supports Premium V3 SKUs for managed instance App Service plans (in addition to Premium V4): --sku values corresponding to P0V3/Premium0V3, P*V3/PremiumV3, and P*MV3/PremiumMV3 will now return supported regions instead of returning none. (PR #33690, PR #33804)
• Azure CLI (App Service) adds a new preview command group and command: az webapp troubleshoot status under az webapp troubleshoot, to diagnose Linux Web Apps by aggregating per-instance Site Runtime Status (ARM .../siteStatus) and recent startup outcomes (KuduLite/SCM /api/startuplogs/summary); supports --slot/-s, --instance (accepts either ARM hex instanceId from az webapp list-instances or the worker machine name), default structured output suitable for -o json/yaml/table (including instances and optionally orphanStartups), and --report which prints a human-readable, colorized report to stdout and returns no machine-readable output; -o table is customized to show per-instance health/startup counts and may emit a post-table “Hint” recommending follow-up az webapp log tail / az webapp log startup show commands when errors are detected; additionally, Linux web app workflows now emit a new warning “Tip” suggesting az webapp troubleshoot status --name <app> --resource-group <rg> after certain commands/events (including az webapp create, az webapp up, and deployment status tracking paths) to guide users toward the new per-instance runtime/startup troubleshooting command. (PR #33673, PR #33804)
• Azure CLI (App Service) az webapp list-runtimes now correctly lists newer Linux Java SE runtimes (restoring Java 17/21/25 in addition to 8/11) by reading runtime data from the SDK’s raw container settings fields (including the runtimes array / javaNNRuntime fields on typespec models) and by selecting the Java SE auto-update container via its is_auto_update/isAutoUpdate flag instead of assuming a fixed position in the API response (improves reliability and future Java-version discovery). (PR #33672)
• Azure CLI App Service command az webapp config ssl import now restores App Service Certificate Key Vault secret-name resolution when using azure-mgmt-web 11.0.0+ by querying the ARM REST API for Microsoft.CertificateRegistration/certificateOrders (with pagination) instead of relying on the removed WebSiteManagementClient.app_service_certificate_orders; if the lookup fails, the command logs a warning and falls back to using the provided certificate name as the Key Vault secret name. (PR #33705)
• Azure CLI az network nat gateway create and az network nat gateway update now support a new --nat64 parameter (enum: Enabled, Disabled, None) to enable/disable NAT64 on StandardV2 NAT gateways; the corresponding nat64 property is now returned in az network nat gateway show and az network nat gateway list output (and therefore also visible via az network nat gateway wait polling results); additionally, az network nat gateway AAZ commands (create, update, show, list, delete, wait) were updated to use the Microsoft.Network/natGateways management-plane API version 2025-07-01 (from 2024-07-01), which may change the set of properties surfaced in az network nat gateway show/list JSON (e.g., new properties.serviceGateway object appearing in outputs). (PR #33679, PR #33804)
• Azure CLI az network private-endpoint-connection now uses API version 2025-03-31 (instead of 2022-08-31-preview) when working with Private Endpoint Connections for the resource type Microsoft.HardwareSecurityModules/cloudHsmClusters (Cloud HSM), which may change supported properties/behavior compared to the previously documented preview API behavior. (PR #33739, PR #33804)
• Azure CLI az network virtual-appliance migration adds a new command group for phased Network Virtual Appliance (NVA) infrastructure migration to the new internal load balancer (ILB) architecture (and OS-version migration), with four new long-running (LRO) commands—az network virtual-appliance migration prepare|execute|commit|abort (all support --no-wait), using API version 2025-09-01; prepare/execute/commit require --migration-type (MigrateToNewILBArchitecture or MigrateToNewOSVersion), prepare additionally supports --marketplace-version (intended only for MigrateToNewOSVersion), and abort prompts for confirmation and infers the migration type from the resource rather than taking --migration-type. (PR #33766, PR #33804)
• Breaking: Azure CLI az find is migrated from the retired Aladdin backend (app.aladdin.microsoft.com) to the Microsoft Learn MCP Server (https://learn.microsoft.com/api/mcp), which changes user-visible behavior and output: the command now searches both Microsoft Learn documentation and Azure CLI code samples (showing separate “Examples” and “Documentation” sections), applies new relevance filtering (e.g., filters out results from different az <group> command groups and low-overlap “noise” matches), caps displayed results (currently up to 3 code examples and 2 doc results), updates the wait/help messaging (“Finding examples and documentation…”, “AI assistant…based on Microsoft Learn documentation”), and updates the failure experience to a network/Microsoft Learn search error message (instead of stating az find is retired); later refinements further adjust Learn-backed search and output formatting to return more Azure CLI–specific results (docs query auto-appends hints like “Azure CLI” / “az command”, doc results are filtered to the same az <group> when titles look like command reference and must share keyword overlap with the query, and docs are re-ranked to prefer the az command reference /cli/azure and other az-invocation content), and output is cleaned up by deduplicating results (by URL/title), generating cleaner truncated doc summaries with an explicit continuation marker, and printing code samples as single copy-pasteable az lines by collapsing shell line continuations (including some / typos used as continuation). (PR #33491, PR #33796)
• Azure CLI az aks upgrade (ACS module) now automatically skips AKS agent pools whose mode is Machines (for both Kubernetes version upgrades and --node-image-only upgrades), logging a warning instead of failing the command with the AKS RP OperationNotAllowed error; documented az aks upgrade behavior may need to note that Machines-mode pools (for example the hidden aksmanagedap pool on Automatic/NAP clusters) are not upgraded by this command. (PR #33693, PR #33804)
• Azure CLI (az aks) adds a new GA command group az aks identity-binding (migrated into the core acs module from the aks-preview extension) to manage AKS identity bindings (trust domain mapping of a managed cluster to a user-assigned managed identity), including az aks identity-binding create (upsert via begin_create_or_update using --managed-identity-resource-id plus --cluster-name and --name/-n), show, list, and delete (with confirmation/--yes support); --no-wait is now actually supported for create and delete in core CLI. (PR #33558, PR #33804)
• Azure CLI (az aks update --outbound-type) validation in the acs command module now treats userDefinedRouting and userAssignedNATGateway differently on update: updating a managed VNet AKS cluster to these outbound types fails with a new, explicit InvalidArgumentValueError stating migration is only supported for custom (BYO) VNet clusters (and points users to the AKS outbound type migration documentation), instead of incorrectly implying/requiring the non-existent --vnet-subnet-id parameter on az aks update. (PR #33694, PR #33804)
• Azure CLI az aks nodepool rollback (AKS) no longer emits the “Auto-upgrade is enabled…” warning when the cluster’s upgradeChannel or nodeOSUpgradeChannel is actually disabled (e.g., NONE/none), by correctly evaluating string-enum .value for the auto-upgrade channel checks and reporting the resolved channel values in the warning message. (PR #33748, PR #33804)
• Azure CLI az appconfig data-plane commands (for example az appconfig kv import|export|set|list and other App Configuration key-value operations) now use an explicit azure-core RetryPolicy on AzureAppConfigurationClient (all auth modes: connection string, az login, and anonymous), increasing transient-failure resilience by retrying with exponential backoff (factor 0.5s, max 30s) up to an overall 100-second retry timeout (instead of the prior default ~3 retries / short retry window); additionally, az appconfig now better supports non-public/sovereign clouds and --endpoint/--connection-string workflows when using Microsoft Entra ID auth by updating to azure-appconfiguration Python SDK 1.8.0 and, if the current az cloud metadata doesn’t define appconfig_auth_token_audience, falling back to using the provided --endpoint as the token audience; additionally, az appconfig feature set telemetry (--telemetry-enabled true) can emit the Application Insights warning even when --name isn’t provided by deriving the store name from --endpoint or --connection-string. (PR #33219, PR #33393, PR #33804)
• Breaking: Azure CLI az monitor account commands (az monitor account create/show/list/wait) no longer surface the etag field in command output (AAZ response schema dropped etag), which may break scripts or --query etag usage that relied on it; az monitor account create and az monitor account update add --enable-access-using-resource-permissions (alias --enable-res-perm) and --public-network-access {Enabled|Disabled}; az monitor account create now supports managed identity assignment at creation via --system-assigned/--mi-system-assigned and --user-assigned/--mi-user-assigned; az monitor account identity is a new command group (assign, remove, show with --system-assigned/--user-assigned); az monitor account list now supports standard pagination (--max-items, --next-token); and Azure CLI adds new command groups az monitor account issue (create/update/show/delete/list plus related operations like add-or-update-alert, add-or-update-resource, list-alert, list-resource, add-investigation-result, fetch-investigation-result, fetch-background-visualization, set-background-visualization) and az monitor account metrics-container (create/update/show/list with --version and pagination on list). (PR #33325)
• Azure CLI az netappfiles volume create now supports a new --breakthrough-mode parameter (enum: Enabled/Disabled) to configure whether an Azure NetApp Files volume operates in “Breakthrough Mode”; related az netappfiles volume/volume-group command outputs (for example az netappfiles volume show/list and az netappfiles volume-group show) also surface the breakthroughMode property in the returned volume resource; az netappfiles volume create (and volume definitions within az netappfiles volume-group create) now allow underscores (_) in the volume file path name validation; and the az netappfiles command module is updated to use Azure NetApp Files management API version 2026-05-01 (from 2026-04-01) across the AAZ-based commands. (PR #33763, PR #33804)
• Azure CLI az acr import now correctly normalizes --source values that use ACR regional endpoints (<registry>.<region>.geo<loginServerSuffix>) back to the global ACR login server across public and sovereign clouds (including multi-label suffixes like .azurecr.sovcloud-azure.de/.fr), preventing fallback to anonymous registryUri pulls that can fail with 403/firewall-denied in sovereign environments. (PR #33754, PR #33804)
• Azure CLI az acr create and az acr update (Azure Container Registry) add a new preview parameter --writable-cache-repos (enum) to enable/disable writable behavior for repositories backed by ACR cache rules; default remains Disabled when not specified, and az acr create/update --help now includes new examples showing --writable-cache-repos enabled. (PR #33772)
• Azure CLI: the built-in az cosmosdb module no longer blocks the az documentdb ... command namespace (removed the pre-parse guard that raised “All documentdb commands have been renamed to cosmosdb”), so az documentdb is now available for reuse by other command modules/extensions (while az cosmosdb behavior is unchanged). (PR #33686)
• Azure CLI az cosmosdb restore now supports a new --disable-local-auth (three-state) flag to disable key-based authentication on the restored Azure Cosmos DB account; az cosmosdb fleet, az cosmosdb fleetspace, and az cosmosdb fleetspace account command groups are no longer marked is_preview=True; az cosmosdb network-rule output formatting now normalizes the virtual network rule field name to the historical CLI casing ignoreMissingVnetServiceEndpoint (from the service/model ignoreMissingVNetServiceEndpoint) and stops emitting the legacy additionalProperties field when present; and the Cosmos DB management API version support is reverted from 2026-03-15 back to 2025-10-15 (may affect available properties/behavior for Cosmos DB commands). (PR #33303, PR #33804)
• Azure CLI az backup protection enable-for-vm now supports Cross Subscription Backup (CSB) for AzureIaaSVM by allowing --vm to be the full VM ARM resource ID in a different subscription than the Recovery Services vault; in this CSB case the CLI skips vault-subscription discovery, validates the VM exists and is in the same region as the vault, and derives the backup container/item identifiers and sourceResourceId from the ARM ID; az backup restore restore-disks now supports Original Location Recovery (OLR) for CSB-protected Azure VMs (users should pass the native --container-name and --item-name—the name field from az backup container list / az backup item list—the VM subscription is derived automatically from the item/recovery point with no --target-subscription needed, and the command now fails with a clear validation error when a friendly container/item name matches multiple resources instead of crashing); and az backup item list, az backup item show, and az backup job show now surface properties.containerSubscriptionId for AzureIaasVM items/jobs for CSB scenarios. (PR #33703)
• Azure CLI az backup vault create and az backup vault update now support configuring Azure Backup Cost Management granularity via new enum parameter --cost-management-granularity (alias --cost-granularity-level) with values VaultLevel, ProtectedItemLevel, or ProtectedItemWithParentTag; documentation should note the default is VaultLevel (create sets this default, update preserves the existing setting unless the flag is provided); additionally, az backup vault create / az backup vault update behavior for --immutability-state has changed: when setting Unlocked or Locked, the command now sends an immutability configuration (defaults to type AsPerPolicy). (PR #33757, PR #33804)
• Azure CLI adds a new command group for Azure Database for MySQL Flexible Server Fabric Mirroring: az mysql flexible-server mirroring, with az mysql flexible-server mirroring enable and az mysql flexible-server mirroring disable (enable requires --identity-resource-id for a User Assigned Managed Identity (UAMI) and both commands operate on the fabricMirroringSettings/Default resource via a preview API version 2025-12-01-preview); az mysql flexible-server parameter list accepts --tags, --keyword, --page, and --page-size; and the MySQL Flexible Server batch parameter update command now returns {"status": "<poller status>"} after waiting for completion instead of an empty final response body. (PR #33774, PR #33804)
• Azure CLI az mysql flexible-server update (MySQL Flexible Server) adds a new optional --maintenance-batch parameter (accepted values: Default, Batch1, Batch2) to set the maintenance window “batch” (MaintenanceWindow.batch_of_maintenance); it’s only valid when --maintenance-window is enabled (errors if used without --maintenance-window or with --maintenance-window Disabled), omitting --maintenance-batch preserves the server’s existing batch, and disabling the maintenance window clears the batch. (PR #33768, PR #33804)
• Azure CLI az postgres flexible-server backup create now generates an auto backup name (when --backup-name isn’t provided) by incrementing the numeric suffix until it finds a name that doesn’t already exist, preventing failures/duplicates after users delete prior on-demand backups (previously it only tried at most one increment and could still collide). (PR #33684, PR #33804)
• Azure CLI az postgres flexible-server create help (postgresql/_help.py) now includes an additional az command reference example showing how to create an elastic cluster with a custom database name using --database-name (and updates the existing elastic-cluster example command text accordingly). (PR #33712, PR #33804)
• Azure CLI az postgres flexible-server upgrade now supports a new --validate-only flag (mapped to the validate parameter) to run a major version upgrade precheck for the target --version without performing the irreversible upgrade; the command starts the server-side precheck operation and then returns the prevalidation check result (and a new help example was added showing az postgres flexible-server upgrade ... -v 18 --validate-only). (PR #33683, PR #33804)
• Azure CLI (Resource Manager / az resource module) adds a new command group az stack-whatif to manage ARM deployment stack What-If results (Microsoft.Resources/deploymentStacksWhatIfResults) across scopes: az stack-whatif group|sub|mg with create, show, list, and delete; create/show support pretty-printed, colorized What-If output by default with new flags --no-pretty-print (return raw output object / honor normal --output formatting), --no-color (disable ANSI color in pretty output), and --with-property-changes/--wpc on show (fetch full results including property-level changes via the What-If POST), and the What-If target stack is specified via --stack-id (fully-qualified deployment stack resource ID). (PR #32854, PR #33804)
• Azure CLI az cognitiveservices account compute (preview) command group was added to manage Cognitive Services (AI Foundry) account compute cluster resources, including az cognitiveservices account compute create|show|list|delete; create introduces new flags --compute-name, --location, and Pool parameters --pool-name, --instance-type, --node-count, optional --vm-priority, and both create and delete support --no-wait (long-running operation behavior). (PR #33759, PR #33804)
• Azure CLI az vmss application set (Compute/VMSS) now correctly updates the VMSS model’s virtual_machine_profile.application_profile.gallery_applications property (fixing a wrong CamelCase property path that could cause gallery application assignments to be silently ignored) and no longer emits leftover debug print output during execution. (PR #33715, PR #33804)
• Azure CLI az vmss extension set (Compute/vm module) now correctly identifies existing VMSS extensions by the extension type field (instead of type_properties_type) when filtering/replacing extensions, fixing a bug that could incorrectly treat same-type extensions as duplicates and throw extension name 'xxx' cannot be used for more than one extension; documentation may need to remove/adjust any guidance suggesting this error can occur in normal extension set usage. (PR #33755)
• Azure CLI (Compute az sig image-version command group) no longer uses the legacy gallery_image_versions operation group/API profile (removed from azure.cli.core.profiles and from command registration), which fixes spurious ModuleNotFoundError failures in --debug runs (reported with az vm list --debug) and makes az sig image-version create use a single, consistent validation/build path (always requiring one of --managed-image/--os-snapshot/--vhd and always applying the VHD/data-disk argument validation and safety_profile construction, rather than gating these behaviors by API version checks). (PR #33150)
• Azure CLI az keyvault backup start / az keyvault backup restore for Azure Managed HSM now reliably works with --use-managed-identity true by upgrading the underlying azure-keyvault-administration dependency to 4.8.0b2, which fixes a client-side request replay issue that could surface a misleading 409 Conflict: Another backup operation is in progress even when the service had accepted the backup request (affects CLI versions 2.77.0–2.88.0 per PR description). (PR #33783)

Suggestions

Instructions for Copilot: Copilot should only fix suggestions with a checkmark and do not make any updates for unchecked suggestions.

Note

Suggestions are generated by AI and they should be reviewed by human before assigning it to Copilot. Please uncheck the ones you don't want Copilot to work on. Then assign this issue to Agent (GitHub Copilot).

• docs-ref-conceptual/Latest-version/release-notes-azure-cli.md:
  • [Improvements] Add a new release entry for Azure CLI Version 2.89.0 (or update the latest release section, depending on the page’s versioning structure) under the Network heading to include the new az network virtual-appliance migration command group and its four long-running commands (prepare, execute, commit, abort), including the key behavioral/parameter requirements: prepare/execute/commit require --migration-type (values MigrateToNewILBArchitecture or MigrateToNewOSVersion), prepare supports --marketplace-version (OS-version migration scenario), abort does not take --migration-type and prompts for confirmation, and all commands support --no-wait. (PR #33766, PR #33804)
• docs-ref-conceptual/Latest-version/release-notes-azure-cli.md:
  • [Improvements] Add a new release-notes entry for Azure CLI Version 2.89.0 (above the existing 2.88.0 section) and include the newly introduced/changed Azure Cosmos DB CLI behaviors in the appropriate subsections (for example, under a "Cosmos DB" heading): the new az cosmosdb restore --disable-local-auth three-state flag, the Cosmos DB network-rule output field casing normalization and removal of additionalProperties from output, and the Cosmos DB management API version support reverting from 2026-03-15 back to 2025-10-15 (as it can affect command behavior/properties). (PR #33303, PR #33804)

---

📚 To learn more about agentic content maintenance workflow, visit Agentic workflow for Learn content maintenance. Sign in using Learn Profile to access the content on this link.

💬 Share your feedback on the Learn Content Maintenance Agentic Workflow here.