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 changes
Upcoming 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 teamAnnouncing a new login experience with Azure PowerShell and Azure CLI
“You never get a second chance to make a first impression” said Will Rogers, this also applies to the Azure CLI and Azure PowerShell with the first command to execute. After hearing from our customers, our team spent the last few months improving the first experience of the Azure client tools. The new experience prioritizes access to usable information and shorter path to selecting your subscription.Azure CLI and PowerShell Tools Build 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 Build 2024, we are announcing the following new capabilities delivering on our priorities: Extending our coverage and commands API version upgrade. Improvements in user login experience. Security improvements. Invested in Copilot in Azure
