Azure Marketplace ARM Template Azure Portal User Interface Guide

  • Article

ARM templates have powerful deployment features, and their input parameters can be defined by the publisher, giving them great flexibility. When you publish an ARM template on Azure Marketplace, you also need to publish the ARM Template Azure Portal User Interface file createUiDefinition.json. This file is used to define the parameter inputs and user interface when the ARM template is deployed in Azure portal. This article mainly introduces the basic concepts and creation of createUiDefinition.json (please note that this is a fixed file name) files.

Within this article, scope of “Azure Marketplace” is limited to China.

1. Structure of createUiDefinition.json

createUiDefinition.json is a JSON file that corresponds to the ARM template. createUiDefinition.json always contains three properties: handler, version, and parameters. The schema is optional, as shown in the following list:

  • Handler: Handler should always be Microsoft.Compute.MultiVm, and the latest supported version is 0.1.2-preview.

  • Version: The version is set to 0.1.2-preview.

  • Parameters: The schema of the parameters property depends on the combination of the specified handler and version. For ARM templates, the supported properties are basics, steps, and outputs. The basics and steps properties contain the elements—like textboxes and dropdowns—to be displayed in the Azure portal. The outputs property is used to map the output values of the specified elements to the parameters of the Azure Resource Manager deployment template.

  • Including $schema is recommended, but optional. If specified, the value for version must match the version within the $schema URI.

    {
 "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
 "handler": "Microsoft.Compute.MultiVm",
 "version": "0.1.2-preview",
 "parameters": {
      "basics": [ ],
      "steps": [ ],
      "outputs": { }
  }
}

The process of creating createUiDefinition.json chiefly consists of entering the content of the basics, steps, and outputs fields in the parameters. In the ARM template deployment user interface below, basics corresponds to Step 1 in the diagram, and steps corresponds to Step 2 and Step 3 in the diagram. These three parts are explained separately below. Reference pages for the functions and elements used in the examples can be found in Step 2.4.

Note: When you are developing and debugging createUiDefinition.json, you can press F12 in the browser to check for error reports in the Console menu and print the outputs.

2. Developing createUiDefinition.json Files

This section explains in detail the content of the basics, steps and outputs fields in the parameters within createUiDefinition.json, and includes a list of references and sample files. Please note that you can use Chinese for the “label”, “toolTip”, “validationMessage”, and “subLabel” fields.

2.1 Outputs

The Azure portal uses the outputs property to map elements from basics and steps to the parameters of the Azure Resource Manager deployment template. The keys of this dictionary are the names of the template parameters, and the values are properties of the output objects from the referenced elements. The example below shows definitions of the name of the cluster and the SSH login password/public key. Examples of the parameters for Basics and Steps are shown in 2.2 Basics and Steps 2.3.

"outputs": {
  "clusterName": "[basics('clusterNameUi')]",
  "clusterLoginUserName": "[basics('clusterLoginUserNameUi')]",
  "sshUserName": "[steps('cluster').sshUserNameUi]",
  "sshAuthenticationType": "[steps('cluster').sshCredentialUi.authenticationType]",
  "sshPassword": "[steps('cluster').sshCredentialUi.password]",
  "sshPublicKey": "[steps('cluster').sshCredentialUi.sshPublicKey]"
}

Please note that the key “clusterName” in the example corresponds to the parameters in the ARM template, as in the template parameters below:

......
"parameters": {
  "clusterName": {
    "type": "string",
    "metadata": {
      "description": "The name of the cluster to create."
      }
  },
......

2.2 Basics

The Basics step is always the first step of the wizard generated when the Azure portal parses the file. In addition to displaying the elements specified in basics, the portal injects elements for users to choose the subscription, resource group, and location for the deployment. Generally, elements that query for deployment-wide parameters, like the name of a cluster or administrator credentials, should go in this step.

If an element's behavior depends on the user's subscription, resource group, or location, then that element can't be used in basics. For example, Microsoft.Compute.SizeSelector depends on the user's subscription and location to determine the list of available sizes. Therefore, Microsoft.Compute.SizeSelector can only be used in steps. Generally, only elements in the Microsoft.Common namespace can be used in basics. Although some elements in other namespaces (like Microsoft.Compute.Credentials) that don't depend on the user's context, are still allowed.

The definition of the cluster name “clusterNameUi” is shown below.

"basics": [
  {
    "name": "clusterNameUi",
    "type": "Microsoft.Common.TextBox",
    "label": "HDInsight 集群名称",
    "toolTip": "名称长度不得长于50个字符，可以包含字母、数字和连字符。",
    "constraints": {
      "required": true,
      "regex": "^[a-zA-Z0-9][a-zA-Z0-9-]{0,57}[a-zA-Z0-9]$",
      "validationMessage": "名称长度不得长于50个字符，可以包含字母、数字和连字符。"
    }
  },
  {
    "name": "clusterLoginUserNameUi",
    "type": "Microsoft.Common.TextBox",
    "label": "集群管理员用户名",
    "toolTip": "用来向集群提交任务以及登录集群仪表板的用户名。",
    "constraints": {
      "required": true,
      "regex": "^[a-z0-9]{1,64}$",
      "validationMessage": "用户名必须由1-64个小写字母或数字组成。"
    }
  },
......

2.3 Steps

The steps property can contain zero or more additional steps to display after basics, each of which contains one or more elements. Consider adding steps per role or tier of the application being deployed. For example, add a step for inputs for the master nodes, and a step for the worker nodes in a cluster.

The example below shows two parameters within the “elements”.

"steps": [
  {
    "name": "cluster",
    "label": "集群配置",
    "subLabel": {
      "preValidation": "设置集群参数",
      "postValidation": "完成"
    },
    "bladeTitle": "集群配置",
    "elements": [
      {
        "name": "sshUserNameUi",
        "type": "Microsoft.Compute.UserNameTextBox",
        "label": "SSH 登录用户名",
        "toolTip": "用于远程访问集群节点。",
        "constraints": {
          "required": true,
          "validationMessage": "用户名必须由1-64个小写字母或数字组成。"
        },
        "osPlatform": "Linux"
      },
      {
        "name": "sshCredentialUi",
        "type": "Microsoft.Compute.CredentialsCombo",
        "label": {
          "authenticationType": "身份验证类型",
          "password": "密码",
          "confirmPassword": "确认密码",
          "sshPublicKey": "SSH 公钥"
        },
        "osPlatform": "Linux"
      },
  ......

2.4 Element and Function References and Samples Files

The createUiDefinition.json file itself has a simple schema. The real depth of it comes from all the supported elements and functions. These are explained in greater detail on the following pages:

Please see Azure Quickstart Template Sample Files for sample user interface documents. Please search the samples for the file “createUiDefinition.json”.

Next steps

Feedback

  • If you have any questions about this documentation, please submit user feedback in the Azure Marketplace.
  • You can also look for solutions in the FAQs.