Deprecation of Switch AzureMode in Azure PowerShell
Azure PowerShell team is removing Switch-AzureMode, which will be a breaking change to create a solid foundation for the future of Azure PowerShell. The changes are as follows and are targeted for release on Oct. 8th of 2015.
- Remove Switch-AzureMode remove modal behavior from Azure PowerShell
- Decompose AzureResourceManager module into component modules by service and functionality (management vs data plane by service)
- Rename cmdlets in AzureResourceManager module from [Verb]-Azure[Noun] to [Verb]-AzureRm[Noun]
- Distribute Azure and AzureResourceManager modules via PowerShell Gallery
- Adding automated documentation submission to content team for publication (MSDN) upon release for all modules
Azure PowerShell has received strong criticism for its modal / stateful behavior, which is rooted in the use of Switch-AzureMode to switch between Azure Service Management and Azure Resource Management modes. These changes will cause a breaking change, but will provide a strong foundation for the advancement and adoption of Azure PowerShell moving forward.
- Azure PowerShell will be stateless and enable simple use of ARM and ASM.
- Azure service teams can release module quicker on their own cadence.
- Scripts can run unchanged in Azure Automation.
- Documentation will be up-to-date with each release.
- Breaking change for all users currently targeting Azure Resource Manager.
- Content on Azure.com, MSDN and others needs updated prior to Oct. 8th of 2015.
Beginning in version 0.8.0, the Azure PowerShell installation included both Azure Service Management (ASM) and Azure Resource Manager (ARM) modules. These modules were not designed to be used in the same session. To allow use of the modules within the same session, one module would be loaded and the other module would be unloaded using Switch-AzureMode. ASM was the default module loaded into the Azure PowerShell session and required the use of Switch-AzureMode to transition to ARM mode.
For those who are unfamiliar with ASM and ARM, these modules represent collections of cmdlets, which target the Service Management and Resource Management REST APIs. These REST APIs provide an interface for managing Azure cloud resources such as virtual machines, networks, storage, etc. ARM and ASM can be used to create Azure resources, but the two APIs take drastically different approaches. ASM was a strictly imperative model for creating your Azure resources. ARM introduces an entirely new way of thinking about your Azure resources. Instead of creating and managing individual resources, you are able to manage entire topologies of resources together as logical units. ARM is the future of Azure management and thus the future of Azure PowerShell.
Initially, ARM did not have all of the functionality needed to perform all of the Azure management tasks required by most users, so it was decided to default to ASM. Now, ARM is ready to be the default. Though, rather than having a modal experience where one set of cmdlets is default, we want to load these modules side-by-side.
Switch-AzureMode cmdlet was created to hide the fact that many of the cmdlets in ARM share the same name as cmdlets in ASM (Azure/New-AzureVM and AzureResourceManager/New-AzureVM), because they were used to manage the same resources (WebApps, VMs, Storage Accounts …). We preferred the names of the cmdlets in ASM and wanted to keep them for ARM, but we did not want to break existing Azure PowerShell scripts. Therefore, rather than loading both modules and relying on PowerShell load order, one module was loaded at a time creating a modal / stateful experience for Azure PowerShell.
Switch-AzureMode cmdlet introduces a pattern, which is biased toward an interactive use of the cmdlets. When Switch-AzureMode is called, the module path is changed to include the selected cmdlets and previous mode’s cmdlets are removed from the path. This activity is stateful and causes other scripts running outside of the current session to be affected by this change. This is unexpected functionality and is quite troublesome when running multiple Azure PowerShell sessions.
PowerShell provides the functionality for a user to import and remove modules with a wide variety of options. The opinionated pattern of Switch-AzureMode has been confusing and frustrating to users. This pattern locks users into this opinionated approach to module loading. See the following quote from GitHub:
The two "modes" in Azure are painful and confusing to work with. For example, there's two different "Get-AzureVM" cmdlets (one in each "mode"), each listing its own sets of vms (the "ServiceManagement" cmdlet lists "v1" vms and the "ResourceManager" cmdlet lists "v2" vms). This is a horrible design. Please build a PowerShell module where every module is available without having to perform confusing operations like "Switch-AzureMode": The Azure module is the only module on the planet with two modes, and for good reasons: It is a plain stupid design.
There has been significant user feedback regarding the design and we have decided to make a change for the better and deprecate Switch-AzureMode.
With the deprecation of Switch-AzureMode, the following changes are proposed.
- Remove Switch-AzureMode
- Separate Azure and AzureResourceManager modules
- Azure PowerShell will no longer be modal
- Module Decomposition
- AzureResourceManager module will be broken up into component modules by service and function (management vs. data plane)
- Management Examples:
- AzureRM.Compute (contains compute mgmt. cmdlets)
- AzureRM.Storage (contains storage mgmt. cmdlets)
- Data Plane Example:
- Azure.Storage (contains cmdlets for accessing storage)
- Cmdlet Rename
- All cmdlets under Azure Resource Management modules will be renamed to fit the following format: [Verb]-AzureRm[Noun]
- Example:
- New-AzureVm becomes New-AzureRmVm
- Distribution Improvements
- PowerShell Gallery and WebPI will be used to distribute Azure PowerShell and all of its component modules.
- This will enable quicker, independent releases much like the way Azure SDK for .Net is able to release individual NuGet packages rather than one large installer.
- We will also be tagging modules with API versions they support.
- Documentation Improvements and Enforcement
- Add build verifications to ensure documentation coverage does not decrease.
- Automatically produce documentation upon release builds of Azure PowerShell and push the documentation to MSDN.
These changes will affect a large number of users and have the potential to break many scripts that currently use Azure Resource Management cmdlets. We chose this based on feedback from the community. In the original proposal, we decided to change the ASM cmdlet names rather than the ARM cmdlets. This met with some strong criticism. See the following quotes:
I can't possibly begin to explain how frustrating this is.
It seems that the decision is being made to throw bad engineering after bad engineering; introducing the Switch-AzureMode to allow the re-use of commands with different parameters and methods of use because "we liked the name".
At least for me, September is an insane timeframe to re-work scripts that took 6 months of professional services time to develop even if the "work" is to go back and add module version checks.
It seems to me that the right approach is to learn from the Switch-AzureMode debacle rather than build on it. Admit that the "nice names" isn't a sufficient reason to disrupt your customers and use new names like verb-AzureRMnoun for the new activities.
I agree. Moving the arm cmdlets to the "AzureRm"-prefix will cause the least amount of disruption of current scripts. I would move quickly tho, as some customers have no doubt already started using arm cmdlets.
After taking into account this discussion and the feedback from the community, we have landed on this plan of action. I think this plan will provide a solid foundation for the future of Azure PowerShell and I think the community agrees.
@devigned Thanks. As I said above, I think this is the best of some uncomfotable choices. I look forward to it comign about swiftly and smoothly. While saying this, there is a major communication exercise to undertake - This is going to affect at least some existing scripts - and the IT Pros behind those need forewarning!
The Switch-AzureMode method of Azure (ASM) and Azure Resource Manager (ARM) module use did not work in Azure’s Automation service, leading to a lack of ARM adoption in the service. The Azure PowerShell changes proposed above, along with proposed changes to Azure Automation, will make use of ASM and ARM cmdlets side by side in Azure Automation much simpler. The following change to Azure Automation is proposed:
- Azure Automation will ship out of the box the new ARM-management and data-plane modules discussed above (AzureRM.Compute, AzureRM.Storage, Azure.Storage, etc). Since the ARM-management modules use new cmdlet names (ex: “New-AzureRmVm”), they should not conflict with the Azure (ASM) cmdlets already shipping in the service.
With the wide-ranging impact of these changes in mind, we decided to start talking about the transition many months before we intended on making this changes. We have reached the time for action and the timeline is below.
Azure PowerShell is an open source project and as such, if you feel strongly regarding this topic and would like to have your design ideas heard, please contribute to the discussion via GitHub issue #428. The Azure Automation team will also be monitoring this GitHub issue.