In this blog post, Shriram Natarajan (Senior Program Manager, Azure Stack Hub) walks us through how to interact with Azure Stack Hub using REST APIs.
Microsoft Azure cloud provides a robust platform for developers and operators to build and deploy their solutions seamlessly to the public cloud, the regional clouds as well as to Azure Stack Hub on-premises solutions. This ease of management is enabled by the consistent APIs, provided by the Cloud services available across all of these instances. Each cloud is fronted by the Azure Resource Manager (ARM) which simplifies the manage of application resources, enabling you to repeatedly deploy applications, with confidence that the resources are deployed in a consistent state. Azure Resource Manager makes it easy for you to manage and visualize resources in your app. You no longer have to deploy parts of your app separately and then manually stitch them together. You put resources with a common lifecycle into a resource group that can be deployed or deleted in a single action. You can see which resources are linked by a dependency. You can apply tags to resources to categorize them for management tasks, such as billing. On Azure Stack Hub, ARM is available for the cloud Operators as well to manage the cloud easily and ensure high availability to their customers.
Azure has robust tooling with SDKs in a variety of languages to help customers interact with the ARM APIs wherever they are. These tools are the recommended way to interact with any of the Azure clouds. However, there may be some cases where you would want to call the ARM APIs directly. For example:
For such scenarios, this blog will detail the process of making Authenticated API calls to the Azure Resource Manager. For the purposes of this blog we will use the ARM instance in Azure Stack Hub, but the process is the same regardless of whether you authenticate to Public Azure, any of the regional clouds or Azure Stack Edge.
This blog will help you get boots on ground quick and get started with calling ARM.
Note:
Note: this post will use Service Principal with a secret.
Download the API requests and Environment Variables.
Import the API requests into postman using the import wizard.
Click on Upload files and select both the Azure Stack - Admin ARM REST.postman_collection.json and Azure Stack - Admin ARM REST.postman_environment.json files. This will set up the necessary requests and the environment variables needed for you to follow along.
Make sure you have the API request collection imported on the left nav. To see the Environment variables, click on the dropdown on the top right.
Before you can start communicating with your Azure Stack Environment, you need to know a couple of things:
You can enter these values in the Environment setup in Postman. Click on the Manage Environments icon and Select the Azure Stack – Admin ARM REST environment.
Replace the “Current Value” field for all the variables with the values from your environment.
Before we start executing the postman requests, let’s quickly see an overview of the steps that need to be done:
Now you’re ready to call the ARM endpoint and have authenticated interactions with the Cloud!
Note: Make sure the right Environment is selected in Postman before you execute the requests below.
This is one of the common causes for failure in following this guide.
This will send a request to {{adminArmEndpoint}}/metadata/endpoints?api-version=2015-11-01 with the adminArmEndpoint value being the one you set up in the Environment.
You will get the following response back from ARM.
Using the “Tests” functionality in POSTMAN, we’re creating additional environment variables using the values in the response. The most important ones are the ARM Audience and the loginEndpoint. These variables will be used for subsequent requests.
This step will send a call to the AAD or AD FS endpoint discovered in the previous step to fetch the actual token endpoint where we will need to send our credentials. The token endpoint can be read from the “Open ID connect Configuration” for that Identity system.
We will again use the Tests to save this into a new environment variable.
Execute the Authenticate Service Principal request next and make sure that the service Principal ID and secret are set in the environment. This will send a request to the token endpoint discovered in the previous step along with the credentials and the ARM audience inferred from the endpoint discovery step.
Assuming your credentials are correct and you do have the permission to request a token, you will get the access token back in the response as seen above. Using Tests, we will store this token in a new variable inside the environment.
At this point you have everything you need to interact with ARM! The first thing you would need to know is the subscription ID – in this scenario, the operator would need to know the id of the Default Provider Subscription.
This will send a request to the {{adminArmEndpoint}}/subscriptions?api-version=2015-01-06 endpoint. Note that the token is sent as a Bearer token in the Authorization Header of the request.
Note: the number of subscriptions returned in this request is dependent on the number of subscriptions the Service Principal has access to on the Admin ARM. In this case, the Service Principal has access only to the Default Provider Subscription, and so only one will be returned.
Following the same template for get subscription, we can also get the default location for that Azure Stack Stamp.
Executing this will send a request to the /providers API which will return all the namespaces and the corresponding resource types and api-versions available under them.
With the information we’ve obtained from the above requests viz. Arm Endpoint, subscriptionID, location, namespaces, resource types and API versions that are available to the subscription, we can compose other requests to ARM. The Postman Request collection has samples of other such API calls you can compose with this information. Feel free to give them a whirl!
Here are some resources that do a great job in providing you an overview of ARM and how to interact with it.
For learning more about operating an Azure Stack Hub, check the https://github.com/Azure-Samples/Azure-Stack-Hub-Foundation-Core which includes videos, slides, and workshops.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.