If you’ve been working with the Microsoft Azure public cloud platform lately, you might be familiar with the terms “Service Management” and “Resource Manager” (Azure RM). These terms refer to two different REST APIs that enable access to Microsoft Azure cloud services. Cloud Services is an ambiguous term, because there is an Azure platform feature called a “cloud service,” but in this article, I’ll refer to “cloud services” as Azure platform features, generically speaking. You may also see me refer to various cloud services as Azure platform features. Azure platform features could include the following, and many more:
- App Service (umbrella service, broken into Web, API, Logic, Mobile Apps)
- Cloud Services (specific services)
- SQL Database
- Virtual Networks
- Traffic Manager
- Virtual Machines
- Blob, Queue, NoSQL Storage
- Caching (Redis Cache)
The Microsoft Azure public cloud platform offers two distinct REST APIs to create and manage cloud services. Having two APIs can (and does) cause a lot of customer confusion, and raises questions such as “which API should I use, and why?” The two APIs are known as the following:
- Azure Service Management (ASM) – The “old” API
- Azure Resource Manager (ARM) – The “new” API
Each of these APIs has their pros and cons, but it’s important to understand that there isn’t 100% cross-compatibility between them. Certain resource types that are provisioned via the ASM API can be viewed through the ARM API, but generally speaking, the reverse is not true. Looking beyond the REST APIs themselves, you can actually envision ASM and ARM as two distinct management pillars. Each interface has a separate UI Portal experience, a separate REST API, a separate PowerShell module, and a separate “mode” of operation in the Azure Cross-Platform (xPlat) CLI Tool.
Azure Service Management (ASM)
As mentioned before, the ASM API is the “old” API, and correlates to the web portal at http://manage.windowsazure.com. There is also a separate PowerShell module that communicates exclusively with this API; the PowerShell module itself is simply called
Azure. If you see the term “classic” in the context of Microsoft Azure, chances are it is referring to the Service Management API, as opposed to Azure Resource Manager. For example, all of the MSDN documentation in the Service Management REST API Reference has been updated to include “(classic)” in the topics for different cloud resource types.
Azure Service Management is an XML-driven REST API, which adds some overhead to API calls, compared to JSON. The ASM API covers most the majority of Azure cloud features, while some features are only available via the ARM REST API. Consequently, you’ll need to consider which API you must use, as you’re planning on your use of Microsoft Azure features. It may not be possible to exclusively leverage one API or the other.
Azure Resource Manager (ARM)
The Azure Resource Manager (ARM or Azure RM) API is a JSON-driven REST API to provision and manage Azure cloud resources. There is also a separate web portal, called the Azure Portal (formerly the “Ibiza Preview Portal“), which is used to provision Azure cloud resources using the Azure RM API. If you provision cloud resources using the “old” Azure Portal, they are provisioned through the ASM API, and not the ARM API.
One of the benefits of using the Azure RM API is that you can declare cloud resources as part of what’s called an “ARM JSON template.” An ARM JSON template is a specially-crafted JSON file that contains cloud resource definitions. Once the resources have been declared in the JSON template, the template file is deployed into a container called a Resource Group. An ARM Resource Group is a logical set of correlated cloud resources that roughly share a life span. The declarative nature of the ARM JSON Template feature is very similar to Amazon Web Service’s CloudFormation service, which enables declarative provisioning of AWS cloud resources.
The Azure RM API has its own, separate PowerShell module to perform automation tasks with. Many Azure RM features are supported, but the module is still a ways off from having 100% Azure feature coverage. For example, it is impossible to manage Azure App Service WebJobs using the ARM PowerShell module, unless you use the generic “resource” cmdlets, which don’t have any intrinsic knowledge about the feature they’re automating. On the other hand some features like Azure DNS are only supported by leveraging the Azure PowerShell module, and are not available in the Azure Portal.
Role-Based Access Control (RBAC) was a commonly sought after feature, before ARM existed, and thankfully, Microsoft has implemented RBAC support in ARM! You can configure custom roles in ARM, and then apply those user roles to individual ARM resources or Resource Groups, or even entire Azure Subscriptions! This permissions system differs significantly from the co-administrator (effectively god-mode) model that existed back in the old Azure Portal.
Another capability, which is complementary (not a replacement) to ARM RBAC, is the ability to create custom policies that restrict the parameters to the operations that can be performed. These policies can be applied, similar to RBAC, at the Azure Subscription, Resource Group, and individual Resource level. For example, you could:
- Limit the creation of a specific resource type in a Resource Group
- Limit the creation of resources to a specific Azure Region
- Require that a specific tag (key-value pair) be set, in order to invoke the operation
ARM policies are different from RBAC, in that you aren’t specifying who can perform which operations, but rather putting scope around the operations themselves.
Although ARM is the “new way” of performing management of Microsoft Azure cloud resources, it has received significant criticism for lack of documentation, lack of tooling, and other usability limitations. In fact, some Microsoft customers have given up using ARM entirely, and reverted back to using the Azure Service Management API, and even made efforts to move to different cloud providers. Many of the ARM PowerShell commands do not have any documentation, have useless documentation with circular definitions, and/or do not conform to PowerShell design guidelines.
Here are some comments that were left on the Authoring Resource Manager Templates documentation page. Customers are frustrated at the copy-paste experience, lack of documentation, and unsupported promises of performance.
So, to answer your question, which API should you use? If you’re forward-thinking, open to usability issues and a steep learning curve, then you will most likely want to stick with Azure Resource Manager (ARM). On the other hand, if you’re looking for a [more] reliable experience, using APIs that have been leveraged by a larger customer base, you’ll likely want to stick with the Azure Service Management (ASM) API. Although documentation, tooling, and cloud service support is being worked on vigilantly by Microsoft, the ARM API is still lagging significantly behind ASM. On the outset, it might sound like a great service, and it certainly has a strong vision behind it, but the implementation is suffering as of today. Unfortunately, marketing messaging and actual performance of the service are drastically out of sync (but when aren’t they, I guess?).
Keep in mind that, over time, the Service Management API will be phased out, so don’t necessarily expect to be relying on it for the next 10 years either. At some point, you’ll end up having to migrate your ASM-provisioned resources over to the ARM API. Microsoft is currently authoring tools to help with this cloud migration process, but it will take time before they become available and have all the kinks worked out.
NOTE: This article was reviewed and updated at 12:00 PM Central European Time (CET) on Sunday, January 31st, 2016.