Azure CLI Windows MSI Upgrade Issue: Root Cause, Mitigation, and Performance Improvements
Azure CLI on Windows MSI Upgrade Issue Summary About six months ago, some Windows users experienced an Azure CLI crash after upgrading via the MSI installer from Azure CLI 2.76.0 (or earlier) to 2.77.0 (or later). The failure occurred immediately on startup with: “ImportError: DLL load failed while importing win32file: The specified module could not be found.” This post explains what happened, why upgrades were affected (while clean installs typically worked), and what you can do to recover. Who is affected? You are likely affected if: You installed Azure CLI using the Windows MSI installer. You upgraded from Azure CLI 2.76.0 (or earlier) to 2.77.0 (or later) without fully uninstalling first. After the upgrade, any az command fails with the win32file ImportError on startup. Symptoms Typical error output (Azure CLI/Azure PowerShell): ImportError: DLL load failed while importing win32file: The specified module could not be found. Immediate recovery Upgrade to the latest version 2.83.0 If you want to install other versions of Azure CLI, perform a clean reinstall by uninstalling Microsoft Azure CLI from Windows Settings → Apps, deleting any remaining install folder (such as the CLI2 directory), reinstalling the latest Azure CLI using MSI or winget, and then verifying the installation with az --version. Root cause analysis During an affected MSI upgrade, the Azure CLI installation directory ended up missing a set of native Python extension files (.pyd files) required by the Windows integration layer. MSI logging showed components being blocked with messages indicating MSI believed the existing (older) key file was “newer” than the incoming one. The root cause was an interaction between Windows Installer file versioning rules and a third‑party dependency packaging change. Azure CLI 2.76.0/2.77.0 consumed pywin32 311, whose .pyd binaries were missing Windows version resource metadata. When upgrading from a previous Azure CLI build that contained version-stamped pywin32 binaries (e.g., pywin32 306), MSI could treat the older versioned files as higher priority than the incoming non-versioned files. As a result, MSI could remove the old files during upgrade but skip installing the new ones, leaving the install incomplete. Version mapping observed Azure CLI version Python pywin32 pywin32 .pyd version resource ≤ 2.75.0 3.12 306 Present (e.g., 3.12.306.0) 2.76.0 3.12 311 Missing / empty 2.77.0+ 3.13 311 Missing / empty If you need to collect MSI logs （for support） Run the installer with verbose logging （example）: msiexec /i "azure-cli-2.77.0.msi" /l*vx "C:\temp\azure-cli-install.log" References https://github.com/Azure/azure-cli/issues/32045#issuecomment-3669161120 Windows MSI Upgrade Performance Optimization The MSI upgrade process for Azure CLI on Windows has been significantly improved. Previously, Windows Installer performed per‑file version comparisons—particularly expensive for Python runtime files—which made upgrades slow and sometimes inconsistent. With the new logic, which skips the comparison and performs an overwrite installation. Upgrades now use a streamlined clean‑install process, resulting in faster and more reliable MSI upgrades. Performance Improvements Scenario Before After Improvement Fresh Install Baseline ~5% faster 5% faster Upgrade Long due to file-by-file version comparison ~23% faster 23% faster This update makes upgrades noticeably faster and more reliable by removing old files first and skipping slow per‑file version checks. For more details, please refer to: [Packaging] Optimize MSI upgrade performance by simplifying file replacement logic by wangzelin007 · Pull Request #32678 · Azure/azure-cli We encourage you to upgrade to the latest version of the Azure CLI. This will not only resolve the issue but also improve installation performance. Here is our release note. If you encounter any problems, please feel free to report them on Azure CLI GitHub.
Gaining Confidence with Az CLI and Az PowerShell: Introducing What if & Export Bicep
Ever hesitated before hitting Enter on a command, wondering what changes it might make? You’re not alone. Whether you’re deploying resources or updating configurations, the fear of unintended consequences can slow you down. That’s why we’re introducing new powerful features in Azure CLI and Azure PowerShell to preview the changes the commands may make: the What if and Export Bicep features. These capabilities allow you to preview the impact of your commands and allow you to export them as Bicep templates, all before making any changes to your Azure environment. Think of them as your safety net: you can validate actions, confirm resource changes, and even generate reusable infrastructure-as-code templates with confidence. Currently, these features are in private preview, and we’re excited to share how you can get early access. Why This Matters Reduce risk: Avoid accidental resource deletions or costly misconfigurations. Build confidence: Understand exactly what your command will do before execution. Accelerate adoption of IaC: Convert CLI commands into Bicep templates automatically. Improve productivity: Validate scripts quickly without trial-and-error deployments. How It Works What if preview of commands All you have to do is add the `--what-if` parameter to Azure CLI commands and then the `-DryRun` command to Azure PowerShell commands like below. Azure CLI: az storage account create --name "mystorageaccount" --resource-group "myResourceGroup" --location "eastus" --what-if Azure PowerShell: New-AzVirtualNetwork -name MyVNET -ResourceGroupName MyResourceGroup -Location eastus -AddressPrefix "10.0.0.0/16" -DryRun Exporting commands to Bicep To generate bicep from the command you will have to add the `--export-bicep` command with the --what-if parameter to generate a bicep file. The bicep code will be saved under the `~/.azure/whatif` directory on your machine. The command will specific exactly where the file is saved on your machine. Behind the scenes, AI translates your CLI command into Bicep code, creating a reusable template for future deployments. After generating the Bicep file, the CLI automatically runs a What-If analysis on the Bicep template to show you the expected changes before applying them. Here is a video of it in action! Here is another example where there is delete, modify and create actions happening all together. Private Preview Access These features are available in private preview. To sign up: Visit the aka.ms/PreviewSignupPSCLI Submit your request for access. Once approved, you’ll receive instructions to download the preview package. Supported Commands (Private Preview) Given these features are in a preview we have only added support for a small set of commands for the time being. Here’s a list of commands that will support these features during the private preview: Azure CLI Az vm create Az vm update az storage account create az storage container create az storage share create az network vnet create az network vnet update az storage account network-rule add az vm disk attach az vm disk detach az vm nic remove Azure PowerShell New-AzVM Update-AzVM New-AzStorageAccount New-AzRmStorageShare New-AzRmStorageContainer New-AzVirtualNetwork Set-AzVirtualNetwork Add-AzStorageAccountNetworkRule Next Steps Sign up for the private preview. Install the packages using the upcoming script. Start using --what-if, -DryRun, and --export-bicep to make safer, smarter decisions and accelerate your IaC journey. Give us feedback on what you think of the feature! At https://aka.ms/PreviewFeedbackWhatIf Thanks so much! Steven Bucher PM for Azure Client ToolsAzure CLI and Azure PowerShell Ignite 2025 Announcement
In 2025, the key investment areas for Azure CLI and Azure PowerShell are quality and security. We have also made significant efforts to improve the overall user experience. Meanwhile, AI remains a central theme. At Microsoft Ignite 2025, we are pleased to announce several new features related to these priorities: In terms of security: MFA enforcement Azure CLI Upgrade and Python 3.13 Compatibility explanation New feature: Azure CLI and Azure PowerShell -What-If and -export bicep parameter Extending our coverage We’ve rolled out significant updates across Azure CLI and Azure PowerShell to enhance functionality: Azure CLI and Azure PowerShell Upgrades Services updated: ACR, ACS, AKS, App Config, App Service, ARM, ARO, Backup, Batch, Cloud, Compute, Consumption, Container, Container app, Core, Cosmos DB, Cognitive Services, DMS, Eventhub, HDInsight, Identity, IoT, Key Vault, MySQL, NetAppFiles, Network, Packaging, Profile, RDBMS, Service Fabric, SQL, Storage. New Extensions for Azure CLI and Azure PowerShell Extensions added: arize-ai,connectedmachine,containerapp,lambda-test,migrate,neon,pscloud,sftp,site,storage-blob-preview. New GA Modules for Azure CLI and Azure PowerShell Modules are now generally available: DeviceRegistry, DataMigration, FirmwareAnalysis,LoadTesting,StorageDiscovery , DataTransfer, ArizeAI, Fabric, StorageAction, Oracle For detailed release notes: Azure CLI: https://learn.microsoft.com/cli/azure/release-notes-azure-cli Azure PowerShell: https://learn.microsoft.com/powershell/azure/release-notes-azureps Azure CLI Upgrade and Python 3.13 Compatibility Notes Azure CLI has been upgraded from version 2.76 to 2.77 primarily to address several security vulnerabilities (CVE), including issues related to remote code execution risks and certificate validation flaws in underlying dependencies, ensuring compliance with the latest security standards. This upgrade requires Python to move from 3.12 to 3.13, which introduces a significant change: Python 3.13 enforces stricter SSL verification rules, causing failures for users running behind proxies that intercept HTTPS traffic. Solution: Update your proxy certificate to comply with strict mode. For instance, Mitmproxy fixed this in version v10.1.2 (reference: https://github.com/Azure/azure-cli/issues/32083#issuecomment-3274196488). For more Python3.13 details, see What’s New In Python 3.13 . Handling Claims Challenges for MFA in Azure CLI and Azure PowerShell Claims challenges appear when ARM begins enforcing MFA requirements. If a user performs create, update, or delete operations without the necessary MFA claims, ARM rejects the request and returns a claims challenge, indicating that higher-level authentication is required before the API call can proceed. This mechanism is designed to ensure sensitive operations are performed only by users who have completed MFA. The challenge arises because Azure CLI and Azure PowerShell can only acquire MFA claims during the login phase, and only if the user’s account is configured to require MFA. Changing this setting affects all services associated with the account, and many customers are reluctant to enable MFA at the account level. As a result, when a claims challenge occurs, Azure CLI and Azure PowerShell cannot automatically trigger MFA in the same way Azure Portal does. Azure CLI example: az login --tenant "aaaabbbb-0000-cccc-1111-dddd2222eeee" --scope "https://management.core.windows.net//.default" --claims-challenge "<claims-challenge-token>" For more details, see: Azure CLI: Troubleshooting Azure CLI | Microsoft Learn Azure PowerShell example: Connect-AzAccount -Tenant yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyy -Subscription zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzz -ClaimsChallenge <claims-challenge-token> For more details, see: Azure PowerShell: Troubleshooting the Az PowerShell module | Microsoft Learn Advanced cloud analysis capabilities, involving capacity insights or forecasting in Azure CLI With this update, Azure CLI now uses the latest ARM API version (2022-09-01) for endpoint discovery during cloud registration and updates, replacing the older API versions previously used. This ensures more accurate and up-to-date service endpoints, simplifies the configuration of custom Azure clouds, and improves reliability when retrieving required endpoints. By adopting the new API, Azure CLI stays aligned with the latest Azure platform capabilities, increasing both compatibility and forward-compatibility. As a result, users benefit from more accurate endpoint discovery and improved support for new Azure features and service endpoints as they become available. For more details about managing cloud environments in Azure CLI, please refer to the official documentation: Azure cloud management with the Azure CLI | Microsoft Learn Azure PowerShell - Add Pagination Support for 'Invoke-AzRestMethod' via '-Paginate' parameter Invoke-AzRestMethod is a flexible fallback for calling Azure Management APIs, returning raw HTTP responses from underlying endpoints, but it currently lacks built-in pagination, forcing users to implement custom logic when working with large datasets. Since pagination was not part of the original design, changing the default behavior could break existing scripts that depend on the current response format and nextLink handling. To address this without disruption, we plan to introduce pagination as an optional opt-in feature, enabling users to retrieve complete datasets through server-driven pagination without writing custom code while preserving the current behavior by default for full backward compatibility. For more details, see the official documentation for Invoke-AzRestMethod: Invoke-AzRestMethod (Az.Accounts) | Microsoft Learn Introducing Azure CLI and Azure PowerShell -What-If and -export bicep parameter We’re introducing two new features in both Azure CLI and Azure PowerShell: the What-If and Export Bicep parameters. The What-If parameter gives you an intelligent preview of which resources will be created, updated, or deleted before a command runs, helping you catch issues early and avoid unexpected changes. The Export Bicep parameter generates the corresponding Bicep templates to streamline your infrastructure-as-code workflows. Both features leverage AI to assist with command interpretation and template generation. If you’d like to try these capabilities in Azure CLI and Azure PowerShell, you can sign up through our form. Please stay tuned for more updates. Breaking Changes The latest breaking change guidance documents can be found at the links below. To read more about the breaking changes migration guide, ensure your environment is ready to install the newest version of Azure CLI and Azure PowerShell. Azure CLI: Release notes & updates – Azure CLI | Microsoft Learn Azure PowerShell: Migration guide for Az 15.0.0 | Microsoft Learn Milestone timelines: Azure CLI Milestones Azure PowerShell Milestones Thank you for using the Azure command-line tools. We look forward to continuing to improve your experience. We hope you enjoy Ignite and all the great work released this week. We'd love to hear your feedback, so feel free to reach out anytime. GitHub: o https://github.com/Azure/azure-cli o https://github.com/Azure/azure-powershell Let's be in touch on X (Twitter) : @azureposh @AzureCli
Announcement of migrating to Azure Linux 3.0 for Azure CLI
Azure CLI 2.74.0 is the final version available on Azure Linux (Mariner) 2.0 and will not receive further updates. We recommend migrating to Azure Linux 3.0 to access newer versions of Azure CLI and continue receiving updates. A warning message will appear when using Azure CLI on Azure Linux 2.0. To suppress this message, set the AZURE_CLI_DISABLE_AZURELINUX2_WARNING environment variable to any value. We value the experiences of our Azure CLI users, especially when lifecycle changes might cause disruptions. Our goal is to provide clear communication and as much advance notice as possible. Quoting our internal partner, the Azure Linux team, as follows: Azure Linux 2.0 will reach its End of Life (EOL) on July 2025. After this date, it will no longer receive updates, security patches, or support, which may put your systems at risk. From today, we will not be entertaining package upgrade requests for Azure Linux 2.0. To ensure continued support, security, and performance, we strongly recommend upgrading to Azure Linux 3.0 by June 2025. Azure Linux 3.0 comes with enhanced features, better performance, and longer support, making it better choice for your infrastructure moving forward. Learn more about 3.0 here. We understand that migrations can take time, so we encourage you to begin planning your upgrade as soon as possible. Our Azure Linux team is available to assist with the transition, address any concerns, and help make the process as seamless as possible. Is this the same as Mariner? Yes, Mariner was rebranded to Azure Linux. We will slowly update our documentation and VM/container image tags to reflect this name change When did Azure Linux 3.0 GA? Azure Linux 3.0 became generally available in August 2024. When will Azure Linux 3.0 reach End of Life (EOL)? We currently support each major version for 3 years after it becomes generally available. Azure Linux 3.0 will reach EOL in Summer 2027. Azure CLI 2.74.0 (scheduled for release on 2025-06-03) is the final version to support Azure Linux 2.0. We strongly recommend reviewing your scenarios and using this transition period to ensure a smooth migration. For AKS customers, Noting that Azure Linux team are still supporting Azure Linux 2.0 until November 2025 to align with AKS v1.31 support. This means Azure Linux 2.0 is getting regular patches until November 2025. If you encounter any issues related to Azure CLI on Azure Linux 3.0, please open an issue in our GitHub repo.Azure CLI and Azure PowerShell Build 2025 Announcement
The key investment areas for Azure CLI and Azure PowerShell in 2025 are quality and security. We’ve also made meaningful efforts to improve the overall user experience. In parallel, we've enhanced the quality and performance of Azure CLI and Azure PowerShell responses in Copilot, ensuring a more reliable user experience. We encourage you to try out the improved Azure CLI and Azure PowerShell in the Copilot experience and see how it can help streamline your Azure workflows. At Microsoft Build 2025, we're excited to announce several new capabilities aligned with these priorities: Improvements in quality and security. Enhancements to user experience. Ongoing improvements to Copilot's response quality and performance. Improvements in quality and security Azure CLI and Azure PowerShell Long Term Support (LTS) releases support In November 2024, Azure PowerShell became the first to introduce both Standard Term Support (STS) and Long-Term Support (LTS) versions, providing users with more flexibility in managing their tools. At Microsoft Build 2025, we are excited to announce that Azure CLI now also supports both STS and LTS release models. This allows users to choose the version that best fits their project needs, whether they prefer the stability of LTS releases or want to stay up to date with the latest features in STS releases. Users can continue using an LTS version until the next LTS becomes available or choose to upgrade more frequently with STS versions. To learn more about the definitions and support timelines for Azure CLI and Azure PowerShell STS and LTS versions, please refer to the following documentation: Azure CLI lifecycle and support | Microsoft Learn Azure PowerShell support lifecycle | Microsoft Learn Users can choose between the Long-Term Support (LTS) and Short-Term Support (STS) versions of Azure CLI based on their specific needs. It is important to understand the trade-offs: LTS versions provide a stable and predictable environment with a support cycle of up to 12 months, making them ideal for scenarios where stability and minimal maintenance are priorities. STS versions, on the other hand, offer access to the latest features and more frequent bug fixes. However, this comes with the potential need for more frequent script updates as changes are introduced with each release. It is also worth noting that platforms such as Azure DevOps and GitHub Actions typically default to using newer CLI versions. That said, users still have the option to pin to a specific version if greater consistency is required in their CI/CD pipelines. When using Azure CLI to deploy services like Azure Functions within CI/CD workflows, the actual CLI version in use will depend on the version selected by the pipeline environment (e.g., GitHub Actions or Azure DevOps), and it is recommended to verify or explicitly set the version to align with your deployment requirements. SecureString update for Azure PowerShell Our team is gradually transitioning to using SecureString for tokens, account keys, and secrets, replacing the traditional string types. In November 2024, we offered an opt-in method for the Get-AzAccessToken cmdlet. At the 2025 Build event, we’ve made this option mandatory, which is a breaking change: Get-AzAccessToken Get-AzAccessToken Token : System.Security.SecureString ExpiresOn : 5/13/2025 1:09:15 AM +00:00 TenantId : 00000000-0000-0000-0000-000000000000 UserId : user@mail.com Type : Bearer In 2026, we plan to implement this secure method in more commands, converting all keys, tokens, and similar data from string types to SecureString. Please continue to pay attention to our upcoming breaking changes documentation. Install Azure PowerShell from Microsoft Artifact Registry (MAR) Installing Azure PowerShell from Microsoft Artifact Registry (MAR) brings several key advantages for enterprise users, particularly in terms of security, performance, and simplified artifact management. Stronger Security and Supply Chain Integrity Microsoft Artifact Registry (MAR) enhances security by ensuring only Microsoft can publish official packages, eliminating risks like name squatting. It also improves software supply chain integrity by offering greater transparency and control over artifact provenance. Faster and More Reliable Delivery By caching Az modules in your own ACR instances with MAR as an upstream source, customers benefit from faster downloads and higher reliability, especially within the Azure network. You can try installing Azure PowerShell from MAR using the following PowerShell command: $acrUrl = 'https://mcr.microsoft.com' Register-PSResourceRepository -Name MAR -Uri $acrUrl -ApiVersion ContainerRegistry Install-PSResource -Name Az -Repository MAR For detailed installation instructions and prerequisites, refer to the official documentation: Optimize the installation of Azure PowerShell | Microsoft Learn Enhancements to user experience Azure PowerShell Enhancements at Microsoft Build 2025 As part of the Microsoft Build 2025 announcements, Azure PowerShell has introduced several significant improvements to enhance usability, automation flexibility, and overall user experience. Real-Time Progress Bar for Long-Running Operations Cmdlets that perform long-running operations now display a real-time progress bar, offering users clear visual feedback during execution. Smarter Output Formatting Based on Result Count Output formatting is now dynamically adjusted based on the number of results returned: A detailed list view is shown when a single result is returned, helping users quickly understand the full details. A table view is presented when multiple results are returned, providing a concise summary that's easier to scan. JSON-Based Resource Creation for Improved Automation Azure PowerShell now supports creating resources using raw JSON input, making it easier to integrate with infrastructure-as-code (IaC) pipelines. When this feature is enabled (by default in Azure environments), applicable cmdlets accept: JSON strings directly via *ViaJsonString External JSON files via *ViaJsonFilePath This capability streamlines scripting and automation, especially for users managing complex configurations. We're always looking for feedback, so try the new features and let us know what you think. Improved for custom and disconnected clouds: Azure CLI now reads extended ARM metadata In disconnected environments like national clouds, air-gapped setups, or Azure Stack, customers often define their own cloud configurations, including custom dataplane endpoints. However, older versions of Azure CLI and its extensions relied heavily on hardcoded endpoint values based only on the cloud name, limiting functionality in these isolated environments. To address this, Azure CLI now supports reading richer cloud metadata from Azure Resource Manager (ARM) using API version 2022-09-01. This metadata includes extended data plane endpoints, such as those for Arc-enabled services and private registries previously unavailable in older API versions. When running az cloud register with the --endpoint-resource-manager flag, Azure CLI automatically parses and loads these custom endpoints into its runtime context. All extensions, like connectedk8s, k8s-configuration, and others, can now dynamically use accurate, environment-specific endpoints without needing hardcoded logic. Key Benefits: Improved Support for Custom Clouds: Enables more reliable automation and compatibility with Azure Local. Increased Security and Maintainability: Removes the need for manually hardcoding endpoints. Unified Extension Behavior: Ensures consistent behavior across CLI and its extensions using centrally managed metadata. Try it out: Register cloud az cloud register -n myCloud --endpoint-resource-manager https://management.azure.com/ Check cloud az cloud show -n myCloud For the original implementation, please refer to https://github.com/Azure/azure-cli/pull/30682. Azure PowerShell WAM authentication update Since Azure PowerShell 12.0.0, Azure PowerShell supports Web Authentication Manager (WAM) as the default authentication mechanism. Using Web Account Manager (WAM) for authentication in Azure enhances security through its built-in identity broker and default system browser integration. It also delivers a faster and more seamless sign-in experience. All major blockers have been resolved, and we are actively working on the pending issues. For detailed announcements on specific issues, please refer to the WAM issues and Workarounds issue. We encourage users to enable WAM functionality using the command: Update-AzConfig -EnableLoginByWam $true. under Windows operating systems to ensure security. If you encounter issues, please report them in Issues · Azure/azure-powershell. Improve Copilot's response quality and performance Azure CLI/PS enhancement with Copilot in Azure In the first half of 2025, we improved the knowledge of Azure CLI and Azure PowerShell commands for Azure Copilot end-to-end scenarios based on best practices to answer questions related to commands and scripts. In the past six months, we have optimized the following scenarios: Introduced Azure concept documents to RAG to provide more accurate and comprehensive answers. Improved the accuracy and relevance of knowledge retrieval query and chunking strategies Support more accurate rejection of the out-of-scope questions. AI Shell brings AI to the command line, enabling natural conversations with language models and customizable workflows. AI Shell is in public preview and allows you to access Copilot in Azure. All the optimizations apply to AI Shell. For more information about AI Shell releases, see: AI Shell To learn more about Microsoft Copilot for Azure and how it can help you, visit: Microsoft Copilot for Azure Breaking Changes You can find the latest breaking change guidance documents at the links below. To learn more about the breaking changes, ensure your environment is ready to install the newest version of Azure CLI and Azure PowerShell, see the release notes and migration guides. Azure CLI: Release notes & updates – Azure CLI | Microsoft Learn Azure PowerShell: Migration guide for Az 14.0.0 | Microsoft Learn Milestone timelines: Azure CLI Milestones Azure PowerShell Milestones Thank you for using the Azure command-line tools. We look forward to continuing to improve your experience. We hope you enjoy Microsoft Build and all the great work released this week. We'd love to hear your feedback, so feel free to reach out anytime. GitHub: o https://github.com/Azure/azure-cli o https://github.com/Azure/azure-powershell Let's stay in touch on X (Twitter) : @azureposh @AzureCli
Azure CLI Breaking Change Pre-Announcement
Background In our continuous effort to improve the quality and timeliness of our documentation, we have embarked on an initiative to automate the production of Upcoming Breaking Change Documentation. This initiative aims to alleviate the workload and pressure typically experienced before major events such as Microsoft Build and Microsoft Ignite. By leveraging automated methods, we can ensure that our documentation is both comprehensive and promptly available to our users. Streamlining the Process To further streamline this process, we are introducing a new workflow designed to encourage Service Teams to notify us of any future breaking changes several sprints ahead. The new workflow includes a new framework to pre-announce breaking changes, which will enable us to publish detailed and accurate Upcoming Breaking Change Documentation well ahead of time, providing our users with the information they need to prepare for these changes. Breaking Change Rule Core CLI A breaking change in Azure CLI refers to a modification that disrupts backward compatibility with previous versions, potentially causing scripts or automation written in earlier versions to fail. Common examples include modifying parameter names, input logic, result output format, behavior models, and adding additional verifications. To mitigate the impact, Azure CLI coordinates half-yearly Breaking Change Releases, bundling multiple breaking changes together. This approach helps users plan ahead and adapt effectively. Breaking Change Window The breaking change window is a designated sprint for merging service command breaking changes, aligning with Microsoft Build in May and Microsoft Ignite in November. Outside this window, breaking changes are typically prohibited to ensure consistency and stability. Exceptions require high-grade justifications and are assessed based on overall impact. 30-Day Pre-announcement Policy All breaking changes must be pre-announced 30 days (usually 2 sprints) before the release. This provides users with buffer time to adapt. Notifications are made through: Warning Log: Mandatory pre-announcement while executing. Upcoming Breaking Change Document: Automatic collection and listing of changes. Extensions All breaking changes in GA (General Available) extensions must be pre-announced at least 30 days prior to their release. While extensions do not need to follow the breaking change window, it is strongly recommended to align their releases with the Core Azure CLI breaking change window. GA (General Available) Release with Breaking Change Pre-Announcement Must include complete breaking change information. Must fulfill the 30-day announcement requirement. During the 30-day announcement period, releases are allowed for unrelated GA (General Available) versions and multiple preview releases (Beta versions). By adhering to these guidelines, users can ensure a smoother transition and maintain compatibility with their existing scripts and automation. How to Announce a Breaking Change It is simple to announce a Breaking Change using the new framework. Find the entry: Find or add an entry to the _breaking_change.py file in the top-level directory of the relevant module. Register Breaking Changes: You can then pre-announce breaking changes for different command groups or commands. Multiple breaking changes on the same command are accepted. from azure.cli.core.breaking_change import register_required_flag_breaking_change, register_default_value_breaking_change, register_other_breaking_change register_required_flag_breaking_change('bar foo', '--name') register_default_value_breaking_change('bar foo baz', '--foobar', 'A', 'B', target_version='May 2025') register_other_breaking_change('bar foo baz', 'During May 2024, another Breaking Change would happen in Build Event.') Try the Warning All related breaking changes will be displayed when executing the command. For instance, with the above declarations, the following warnings will be output when executing the command: # The azure command az bar foo baz # =====Warning output===== # The argument '--name' will become required in next breaking change release (2.61.0). # The default value of '--foobar' will be changed to 'B' from 'A' in May 2025. # During May 2024, another Breaking Change would happen in Build Event. Types of Breaking Changes There are several types of breaking changes defined in `_breaking_change.py`. You should use any of them to declare breaking changes: Remove Rename Output Change Change Default Change Be Required Other Changes Conditional Breaking Change Work with Breaking Change Detect To normalize the release of breaking changes, Azure CLI has integrated a Breaking Change Detection tool into the Pull Request Pipeline. This tool will reject any breaking changes that are submitted outside of the designated breaking change window and will provide guidelines for following the breaking change policies. Technical Implementation The Breaking Change Pre-Announcement uses a hook in the Azure CLI. This hook is used to collect announcements registered in _breaking_change.py files and transform them into tags that can be consumed by the Knack framework, which is the foundational framework used by the Azure CLI. When multiple tags are registered under the same identifier, they are consolidated into a single MergedTag. This MergedTag is then used to manage complex scenarios effectively. Conditional breaking changes are not transformed into tags. Instead, they are stored in the breaking changes registry. These changes can be accessed manually by calling the print_conditional_breaking_change function. Future Plan Detect out of date announcement Detect related announcements in PR of breaking changesUpcoming Breaking Change in Az SSH for Arc Connections Extension
The Az SSH extension is a vital tool for developers and IT professionals who use Azure DevOps. It allows users to securely connect to Azure virtual machines (VMs) using SSH (Secure Shell) and Entra ID, making remote management and deployment tasks more streamlined and efficient. The extension is widely used for its ease of integration with various Azure services and its ability to simplify the process of establishing secure connections. The Upcoming Breaking Change This breaking change affects all customers who use Az SSH extension for connecting to Azure Arc Machines. By May 21 st , all versions of the Az SSH extension prior to 2.0.4 will become unusable upon installation for connecting to Arc resources. This breaking change is due to deprecation of a storage blob used during installation. Versions of the Az SSH extension prior to 2.0.4 will still be functional, but if there is corruption of the extension files, you will not be able to reinstall the extension. To check what version of the extension you have installed, run this command az extension list --output table This change does not impact versions beginning with 2.0.4. Action Items To minimize the potential breaking of the Az SSH extension for connecting to Arc machines, we encourage you to take the following steps: Update the Az SSH Extension: Ensure that you update the Az SSH extension to the latest version (2.0.6). This can be done using the Azure CLI extension update command: az extension update --name ssh Review and Update Scripts: If you have scripts or automated processes that install a pinned version of Az SSH extension prior to 2.0.4, make necessary adjustments to install a later version. Stay Informed: Keep an eye on official documentation and blogs for additional updates or guidance related to the Az SSH extension. Staying informed will help you stay ahead of any future changes. The breaking change in the Az SSH extension is a critical security update. Follow the steps above for a smooth transition and secure management of Azure Arc Machines. Stay proactive, informed, and keep your tools updated to maintain security and efficiency. Thanks! Steven Bucher Product Manager for SSH CLI ExtensionAzure CLI and Azure PowerShell Ignite 2024 Announcement
The priority for Azure CLI and Azure PowerShell remains to provide our customers with the most complete, secure, and easy-to-use tools to manage Azure resources. At Microsoft Ignite 2024, we are announcing the following new capabilities delivering on our priorities: Extending our coverage and commands API version upgrade. Security improvements. Investments in Copilot in Azure Extending our coverage In the past six months, we have added or refreshed coverage for new or existing Azure services within 30 days of their general availability. You will see new and updated command lines for ArcGateway, AzTerraform, ConnectedMachine, Fabric, Astro, Synapse, AppComplianceAutomation, Storage, App, and other modules. Note: To use the associated commands, you need to install the Azure CLI extension or the Azure PowerShell module. For details about all the commands that have been updated, as well as a complete list of the new features in this release for the Azure client tools, see the release notes for each tool: Azure CLI: https://learn.microsoft.com/cli/azure/release-notes-azure-cli Azure PowerShell: https://learn.microsoft.com/powershell/azure/release-notes-azureps Credential detection from Az CLIs outputs We have been actively working on hardening your defense in depth with secrets awareness in Azure command line tools. For Azure CLI and Azure PowerShell, in the past 6 months, we have collaborated with our internal team to replace verification patten with the Azure secret common library, expanding the coverage types of patches and the range of command lines. The range of command line detection has been almost 100% covered. The Azure CLI and Azure PowerShell use the same detection logic and are continually being upgraded. We still encourage users to enable environment parameters: AZURE_CLIENTS_SHOW_SECRETS_WARNING=True (Default) For Azure PowerShell only Our team is gradually transitioning to using SecureString for tokens, account keys, and secrets, replacing the traditional string types. Currently, we offer an opt-in method for the Get-AzAccessToken command line, which does not introduce breaking changes: Get-AzAccessToken –AsSecureString We encourage users to utilize the -AsSecureString parameter to output tokens securely. Over the next year, we plan to implement this security method across more command lines, converting all keys, tokens, and similar data from string types to SecureString. Please note that when the command line output defaults to -AsSecureString mode, it may result in breaking changes. Therefore, we advise users to stay updated with our breaking change documentation. Support Azure Linux 3.0 for Azure CLI Azure CLI has supported Azure Linux 3.0 from 2.65.0. The Azure Linux 3 user can install CLI with tdnf install azure-cli Starting from version 2.64.0 of Azure CLI, the base Linux distribution of Azure CLI is now Azure Linux 3.0. It’s available at Microsoft Artifact Registry (MAR) https://mcr.microsoft.com/en-us/artifact/mar/azure-cli/about. You can get it with the below command： docker pull mcr.microsoft.com/azure-cli or docker pull mcr.microsoft.com/azure-cli:azurelinux3.0 For further migration guidance especially involved with GitHub Actions, please check out more details from blog. Deprecate SP with certificate with az login –password for Azure CLI For az login, --password will no longer accept service principal certificate in Azure CLI 2.67.0. Use `--certificate` to pass a service principal certificate. # Logging in with secret should work as before az login --service-principal --username xxx --password mysecret --tenant xxx # Old way to log in with a certificate, will show a deprecation warning az login --service-principal --username xxx --password ~/mycert.pem --tenant xxx # New way to log in with a certificate az login --service-principal --username xxx --certificate ~/mycert.pem --tenant xxx Note: To sign in with a certificate, the certificate must be available locally as a PEM or DER file in ASCII format. PKCS#12 files (.p12/.pfx) don't work. When you use a PEM file, the PRIVATE KEY and CERTIFICATE must be appended together within the file. You don't need to prefix the path with an `@` like you do with other az commands. Azure PowerShell WAM Authentication Issues and Fixes Since version Az 12.0.0, Azure PowerShell has supported Web Authentication Manager (WAM) as the default authentication mechanism. During this period, several critical issues affected users logging in interactively. These issues have been addressed and fixed by version 13.0.0, including: The WAM login interface failing to pop up, resulting in login failures. Login failures for users using the device-code authentication method. The "Work and school account" option does not appear in the WAM pop-up window. Incompatibility of the Export-AzSshConfig and Enter-AzVM commands from the Az.Ssh module when WAM is enabled. For detailed announcements on specific issues, please refer to our WAM issues and Workarounds/azure-powershell issue. In response to these WAM issues, our team has been actively fixing bugs, making improvements, and establishing monitoring and alert mechanisms with relevant teams to detect issues early and assess their impact. Additionally, we have integrated test cases baseline into the release pipeline. We encourage users to enable the WAM function for security by using the command: Update-AzConfig -EnableLoginByWam $true If you encounter problems, please report them in Issues · Azure/azure-powershell Note: Sovereign Cloud does not currently support WAM, we plan to implement this in the coming months. Change in Azure CLI extension management Starting with Azure CLI version 2.56.0, a new `--allow-preview` parameter was introduced for the extension installations, with its default value set to True. This change, as outlined in our extension versioning guidelines, helps distinguish between stable and preview versions, ensuring consistency across stable releases while still enabling the publication of preview features. Beginning with version 2.67.0, Azure CLI will now install only stable versions of extension modules by default. If a later preview version of an extension is available, users will receive a warning message that explains how to enable preview versions by using the `--allow-preview` parameter. Important Note: If no stable version of an extension is available, preview versions will be installed by default, along with a warning message, like below, notifying users of this behavior. "No stable version of 'xxx' to install. Preview versions are allowed." Azure PowerShell Long Term Support releases (LTS) support Azure PowerShell already supports both Standard Term Support releases (STS) and Long-Term Support releases (LTS). Users can choose the appropriate version according to their project needs. Users can choose to stay with the LTS version until the next LTS version, or upgrade with the latest version to experience new features. The following document details the definitions of LTS and STS. Beginning with Az 12, even numbered releases are LTS versions. Azure PowerShell support lifecycle: Azure PowerShell support lifecycle | Microsoft Learn Azure CLI will provide LTS version in early 2025. More details could be found at Azure CLI lifecycle and support | Microsoft Learn Enhancement to Invoke-AzRestMethod in Azure PowerShell Azure PowerShell 13.0.0 introduces major enhancements to the Invoke-AzRestMethod cmdlet, empowering users with a new option to enable long-running operations (LRO) and flexible control over operation status polling in complex Azure workflows. Key Features of Invoke-AzRestMethod Enhancement: LRO Support with Enhanced Status Tracking: With the new -WaitForCompletion parameter, users can wait for the operations to complete and directly receive the final status. In debug mode, users can also monitor long-running operations (such as deployments or resource provisioning) and receive real-time status updates directly in their PowerShell session. Flexible Polling Options for Customized Control: The addition of -PollFrom and -FinalResultFrom parameters enable users to define custom polling URIs and specify final result header sources, ensuring compatibility across various Azure resources and scenarios. Example Usage: Using the new -WaitForCompletion parameter, here’s how to create a Managed HSM (Hardware Security Module) and track its provisioning status until it’s fully completed: Invoke-AzRestMethod -Method PUT -WaitForCompletion -Path "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.KeyVault/managedHSMs/{hsmName}" This example monitors the creation of a Managed HSM, providing real-time updates throughout the longer provisioning process (in debug mode), ensuring the resource reaches a fully operational state. For more details and examples, refer to the updated release notes: Azure PowerShell release notes Azure CLI/PS scenarios with Copilot in Azure In the second half of 2024, we improved knowledge of Azure CLI commands and end-to-end scenarios for Copilot in Azure to answer questions related to Azure CLI commands or scripts, following our best practices. In the past 6 months, we have optimized the following scenarios: Enhanced Prompt Flow and RAG architecture tailored for CLI script generation, ensuring higher command and scenario accuracy. Improved user intent recognition with hybrid search, enabling more precise retrieval of relevant knowledge from user queries. Supported parameter value injection, simplifying the process for customers to input parameter values and generate directly usable scripts on Copilot in Azure. Optimized the knowledge base to reduce hallucination issues. More accurately identified out-of-scope questions. In the 2024 Ignite Event, we’ve also released a public preview of AI Shell, which lets you access Copilot in Azure to help answer any questions you have about Azure CLI or Azure PowerShell. For more information about the AI Shell release please check out. AI Shell To learn more about Microsoft Copilot for Azure and how it can help you, visit: Microsoft Copilot for Azure Breaking Changes The latest breaking change guidance documents can be found at the links below. To read more about the breaking changes migration guide, ensure your environment is ready to install the newest version of Azure CLI and Azure PowerShell. Azure CLI: Release notes & updates – Azure CLI | Microsoft Learn Azure PowerShell: Migration guide for Az 13.0.0 | Microsoft Learn Milestone timelines: Azure CLI Milestones Azure PowerShell Milestones Thank you for using the Azure command-line tools. We look forward to continuing to improve your experience. We hope you enjoy Ignite and all the great work released this week. We'd love to hear your feedback, so feel free to reach out anytime. GitHub: https://github.com/Azure/azure-cli https://github.com/Azure/azure-powershell Let's be in touch on X (Twitter) : @azureposh @AzureCli Azure CLI and Azure PowerShell team
