Use API version Profiles with Node.js software development kit (SDK) in Azure Stack Hub

  • Article

Node.js and API version profiles

You can use Node.js SDK to help build and manage the infrastructure for your apps. API profiles in the Node.js SDK help with your hybrid cloud solutions by letting you switch between Azure resources and Azure Stack Hub resources. You can code once and then target both Azure and Azure Stack Hub.

In this article, you can use Visual Studio Code as your development tool. Visual Studio Code can debug the Node.js SDK and allows you to run the app and push the app to your Azure Stack Hub instance. You can debug from Visual Studio Code or through a terminal window running the command node <nodefile.js>.

The Node.js SDK

The Node.js SDK provides Azure Stack Hub Resource Manager tools. Resource providers in the SDK include compute, networking, storage, app services, and KeyVault. There are 10 resource provider client libraries that you can install in your node.js application. You can also download specify which resource provider you will use for the 2020-09-01-profile in order to optimize the memory for your application. Each module consists of a resource provider, the respective API version, and the API profile.

An API profile is a combination of resource providers and API versions. You can use an API profile to get the latest, most stable version of each resource type in a resource provider package.

  • To make use of the latest versions of all the services, use the latest profile of the packages.

  • To use the services compatible with Azure Stack Hub, use the @azure/arm-resources-profile-hybrid-2020-09-01 or @azure/arm-storage-profile-2020-09-01-hybrid

NPM Packages

Each resource provider has its own package. You can get the package from the npm registry.

You can find the following packages:

Resource provider Package
App Service @azure/arm-resources-profile-2020-09-01-hybrid
Azure Resource Manager Subscriptions @azure/arm-subscriptions-profile-hybrid-2020-09-01
Azure Resource Manager Policy @azure/arm-policy-profile-hybrid-2020-09-01
Azure Resource Manager DNS @azure/arm-dns-profile-2020-09-01-hybrid
Authorization @azure/arm-authorization-profile-2020-09-01-hybrid
Compute @azure/arm-compute-profile-2020-09-01-hybrid
Storage @azure/arm-storage-profile-2020-09-01-hybrid
Network @azure/arm-network-profile-2020-09-01-hybrid
Resources @azure/arm-resources-profile-hybrid-2020-09-01
Keyvault @azure/arm-keyvault-profile-2020-09-01-hybrid

To use the latest API-version of a service, use the Latest profile of the specific client library. For example, if you would like to use the latest-API version of resources service alone, use the azure-arm-resource profile of the Resource Management Client Library. package.

Use the specific API versions defined inside the package for the specific API-versions of a resource provider.

  • @azure/arm-resourceprovider-profile-2020-09-01-hybrid

    Latest Profile built for Azure Stack Hub. Use this profile for services to be most compatible with Azure Stack Hub as long as you are on 1808 stamp or further.

  • @azure-arm-resource

    Profile consists of latest versions of all services. Use the latest versions of all the services in Azure.

Profiles

For profiles containing dates, to use a different SDK profile or version you can substitute the date in @azure/arm-keyvault-profile-<date>-hybrid. For example, for the 2008 version, the profile is 2019-03-01, and the string becomes @azure/arm-keyvault-profile-2019-03-01-hybrid. Note that sometimes the SDK team changes the name of the packages, so simply replacing the date of a string with a different date might not work. See the following table for association of profiles and Azure Stack versions.

Azure Stack version Profile
2311 2020_09_01
2301 2020_09_01
2206 2020_09_01
2108 2020-09-01
2102 2020-09-01
2008 2019-03-01

For more information about Azure Stack Hub and API profiles, see the Summary of API profiles.

Install the Node.js SDK

  1. Install Git. For instructions, see Getting Started - Installing Git.

  2. Install or upgrade to the current version of Node.js. Node.js also includes the npm JavaScript package manager.

  3. Install or upgrade Visual Studio Code and install the Node.js extension for Visual Studio Code.

  4. Install the client packages for the Azure Stack Hub Resource Manger. For more information, see how to install client libraries.

  5. The packages that need to be installed depends on the profile version you would like to use. You can find a list of resource providers in the Packages in npm section.

Subscription

If you do not already have a subscription, create a subscription and save the subscription ID to be used later. For information about how to create a subscription, see this document.

Service principal

A service principal and its associated environment information should be created and saved somewhere. Service principal with owner role is recommended, but depending on the sample, a contributor role may suffice. Refer to the README in the sample repository for the required values. You may read these values in any format supported by the SDK language such as from a JSON file (which our samples use). Depending on the sample being run, not all of these values may be used. See the sample repository for updated sample code or further information.

Tenant ID

To find the directory or tenant ID for your Azure Stack Hub, follow the instructions in this article.

Register resource providers

Register required resource providers by following this document. These resource providers will be required depending on the samples you want to run. For example, if you want to run a VM sample, the Microsoft.Compute resource provider registration is required.

Azure Stack resource manager endpoint

Azure Resource Manager (ARM) is a management framework that enables administrators to deploy, manage, and monitor Azure resources. Azure Resource Manager can handle these tasks as a group, rather than individually, in a single operation. You can get the metadata info from the Resource Manager endpoint. The endpoint returns a JSON file with the info required to run your code.

Consider the following:

  • The ResourceManagerEndpointUrl in the Azure Stack Development Kit (ASDK) is: https://management.local.azurestack.external/.

  • The ResourceManagerEndpointUrl in integrated systems is: https://management.region.<fqdn>/, where <fqdn> is your fully qualified domain name.

  • To retrieve the metadata required: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0

Sample JSON:

{
   "galleryEndpoint": "https://portal.local.azurestack.external:30015/",
   "graphEndpoint": "https://graph.chinacloudapi.cn/",
   "portal Endpoint": "https://portal.local.azurestack.external/",
   "authentication": 
      {
         "loginEndpoint": "https://login.chinacloudapi.cn/",
         "audiences": ["https://management.yourtenant.partner.onmschina.cn/3cc5febd-e4b7-4a85-a2ed-1d730e2f5928"]
      }
}

Samples

See the sample repository for update-to-date sample code. The root README.md describes general requirements, and each sub-directory contains a specific sample with its own README.md on how to run that sample.

See here for the sample applicable for Azure Stack version 2008 or profile 2019-03-01 and below.

Next steps

Learn more about API profiles: