Azure 市场 ARM 模板 Azure 门户用户界面指南
ARM 模板具有强大的部署功能,它的输入参数可以由发布者定义,因此具有良好的的弹性。发布者在 Azure 市场发布 ARM 模板的同时,还需要发布 ARM 模板 Azure 门户用户界面文件 createUiDefinition.json,这个文件用于定义 ARM 模板在Azure 门户中部署时的参数输入和用户界面。 本文档主要介绍 createUiDefinition.json(请注意这个文件名是固定的) 文件的基本概念和开发制作。
本文中的 “Azure 市场”作用范围均指中国。
1. createUiDefinition.json 文件结构
createUiDefinition.json 是 JSON 格式的文本文件,它和 ARM 模板相对应,CreateUiDefinition.json 始终包含三个属性 handler、version和parameters,schema为可选,如下列表所示:
handler,handler 应当始终为
Microsoft.Compute.MultiVm
,支持的最新版本为0.1.2-preview
。version,版本固定为
0.1.2-preview
。parameters,parameters 属性的架构取决于所指定的 handler 和 version 的组合。 对于ARM 模板,支持的属性为
basics
、steps
和outputs
。 basics 和 steps 属性包含要在 Azure 门户中显示的_元素_,例如文本框和下拉列表。 outputs 属性用来将指定元素的输出值映射到 Azure 资源管理器部署模板的参数。schema,建议包括 $schema,但这是可选的。 如果指定,则 version 的值必须与 $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": { } } }
制作 createUiDefinition.json 的主要工作就是填写 parameters 中的 basics
、steps
和 outputs
这三个字段的内容。 下面的一个 ARM 模板部署用户界面,basics
对应图中的步骤 “1” ,steps
对应图中的步骤 “2” 和 “3” 。下面对这三部分分别进行介绍,案例中用到的函数和元素在 2.4 后续步骤
中有参考页面。
注意:开发调试 createUiDefinition.json 的时候,在浏览器中按F12,查看Console菜单下是否报错,以及是否打印 outputs 输出结果。
2. createUiDefinition.json 文件开发
本节详细讲解 createUiDefinition.json 中 parameters 中的 basics
、steps
和 outputs
这三个字段的内容,并附有参考目录和示例文件。请注意,"label"、"toolTip"、"validationMessage"、"subLabel"等字段可以使用中文。
2.1 Outputs
Azure 门户使用 outputs 属性来将 basics 和 steps 中的元素映射到 ARM 部署模板的参数。 此字典中的键是模板参数的名称,值是所引用元素中的输出对象的属性。如下所示,定义了集群的名称和 ssh 登录密码/公钥,basics 和 steps 的参数分别在 2.2 Basics
和 2.3 Steps
中有示例:
"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]"
}
请注意,案例中的键 "clusterName" 对应着 ARM 模板中的参数,例如如下模板参数:
......
"parameters": {
"clusterName": {
"type": "string",
"metadata": {
"description": "The name of the cluster to create."
}
},
......
2.2 Basics
基础步骤始终是 Azure 门户在分析文件时生成的向导的第一个步骤。 除了会显示 basics 中指定的元素外,该门户还会为用户注入其他元素以用于为部署选择订阅、资源组和位置。 通常,对部署范围内的参数进行查询的元素(例如群集名称或管理员凭据)应当放在此步骤中。
如果元素的行为依赖于用户的订阅、资源组或位置,则不能在 basics 中使用该元素。 例如,Microsoft.Compute.SizeSelector 需要依赖于用户的订阅和位置来确定可用大小的列表。 因此,Microsoft.Compute.SizeSelector 只能用于 steps 中。 通常,只有 Microsoft.Common 命名空间中的元素可以用于 basics 中。 但是也允许其他命名空间中不依赖于用户上下文的某些元素(例如 Microsoft.Compute.Credentials)。
如下所示,对于集群名称 "clusterNameUi" 的定义。
"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
steps 属性可以包含要在 basics 后显示的零个或多个其他步骤,每个步骤都包含一个或多个元素。 请考虑按所部署的应用程序的角色或层添加步骤。 例如,针对群集中的主节点添加一个用于输入的步骤,针对辅助角色节点添加另一个步骤。
如下用例展示了 “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 元素和函数参考以及示例文件
createUiDefinition.json 文件本身具有一个简单的架构,它的实际深度来自所有受支持的元素和函数。 在以下页中更详细地说明了这些项:
有关用户界面文件示例,请参阅 Azure 快速启动模板样例文档。请搜索样例下的 createUiDefinition.json 文件。