Учебник по созданию форм портала Azure для спецификации шаблона
Вы можете создать форму, которая отображается в портал Azure, чтобы помочь пользователям в развертывании спецификации шаблона. Форма позволяет пользователям вводить значения, передаваемые в качестве параметров в спецификацию шаблона.
При создании спецификации шаблона форма и шаблон Azure Resource Manager (шаблон ARM) упаковываются вместе. Во время развертывания спецификации шаблона на портале автоматически запускается форма.
На следующем снимке экрана показана форма, открытая в портал Azure.
Предварительные требования
Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.
Для Azure PowerShell используйте версию 6.0.0 или более позднюю. Для Azure CLI используйте версию 2.24.0 или более позднюю.
Создание шаблона
Чтобы отобразить различные элементы портала, доступные в форме, используйте шаблон ARM с несколькими параметрами. Следующий шаблон создает хранилище ключей, настраивает к нему разрешения для пользователя и добавляет секрет.
Скопируйте этот файл и сохраните его локально. В этом учебнике предполагается, что вы его назвали keyvault.json, но ему можно дать и другое имя.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"keyVaultName": {
"type": "string",
"metadata": {
"description": "Specifies the name of the key vault."
}
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Specifies the Azure location where the key vault should be created."
}
},
"enabledForDeployment": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Virtual Machines are permitted to retrieve certificates stored as secrets from the key vault."
}
},
"enabledForDiskEncryption": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Disk Encryption is permitted to retrieve secrets from the vault and unwrap keys."
}
},
"enabledForTemplateDeployment": {
"type": "bool",
"defaultValue": false,
"allowedValues": [
true,
false
],
"metadata": {
"description": "Specifies whether Azure Resource Manager is permitted to retrieve secrets from the key vault."
}
},
"tenantId": {
"type": "string",
"defaultValue": "[subscription().tenantId]",
"metadata": {
"description": "Specifies the Azure Active Directory tenant ID that should be used for authenticating requests to the key vault. Get it by using Get-AzSubscription cmdlet."
}
},
"objectId": {
"type": "string",
"metadata": {
"description": "Specifies the object ID of a user, service principal or security group in the Azure Active Directory tenant for the vault. The object ID must be unique for the list of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets."
}
},
"keysPermissions": {
"type": "array",
"defaultValue": [
"list"
],
"metadata": {
"description": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge."
}
},
"secretsPermissions": {
"type": "array",
"defaultValue": [
"list"
],
"metadata": {
"description": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge."
}
},
"skuName": {
"type": "string",
"defaultValue": "standard",
"allowedValues": [
"standard",
"premium"
],
"metadata": {
"description": "Specifies whether the key vault is a standard vault or a premium vault."
}
},
"secretName": {
"type": "string",
"metadata": {
"description": "Specifies the name of the secret that you want to create."
}
},
"secretValue": {
"type": "secureString",
"metadata": {
"description": "Specifies the value of the secret that you want to create."
}
}
},
"resources": [
{
"type": "Microsoft.KeyVault/vaults",
"apiVersion": "2022-07-01",
"name": "[parameters('keyVaultName')]",
"location": "[parameters('location')]",
"properties": {
"enabledForDeployment": "[parameters('enabledForDeployment')]",
"enabledForDiskEncryption": "[parameters('enabledForDiskEncryption')]",
"enabledForTemplateDeployment": "[parameters('enabledForTemplateDeployment')]",
"tenantId": "[parameters('tenantId')]",
"accessPolicies": [
{
"objectId": "[parameters('objectId')]",
"tenantId": "[parameters('tenantId')]",
"permissions": {
"keys": "[parameters('keysPermissions')]",
"secrets": "[parameters('secretsPermissions')]"
}
}
],
"sku": {
"name": "[parameters('skuName')]",
"family": "A"
},
"networkAcls": {
"defaultAction": "Allow",
"bypass": "AzureServices"
}
}
},
{
"type": "Microsoft.KeyVault/vaults/secrets",
"apiVersion": "2022-07-01",
"name": "[format('{0}/{1}', parameters('keyVaultName'), parameters('secretName'))]",
"dependsOn": [
"[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
],
"properties": {
"value": "[parameters('secretValue')]"
}
}
]
}
Создание формы по умолчанию
Портал Azure предоставляет песочницу для создания и предварительного просмотра форм. Эта песочница может визуализировать форму из существующего шаблона ARM. Эта форма по умолчанию используется для начала создания формы для спецификации шаблона. Дополнительные сведения о структуре формы см. в разделе FormViewType.
Откройте песочницу представления формы.
В поле Тип пакета выберите CustomTemplate. Перед указанием шаблона развертывания убедитесь, что выбран тип пакета.
В разделе Шаблон развертывания (необязательно) выберите шаблон хранилища ключей, сохраненный локально. При появлении запроса на перезапись текущих изменений выберите Да. Автоматически созданная форма отображается в окне кода. Форма доступна для редактирования на портале. Сведения о настройке формы см. в разделе Настройка формы. Если вы внимательно изучите автоматически созданную форму, заголовок по умолчанию называется представлением тестовой формы, и определен только один шаг, называемый основными сведениями .
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json", "view": { "kind": "Form", "properties": { "title": "Test Form View", "steps": [ { "name": "basics", "label": "Basics", "elements": [ ... ] } ] }, "outputs": { ... } } }Чтобы увидеть, что она работает без изменений, выберите Предварительный просмотр.
В песочнице отображается форма. Она содержит поля для выбора подписки, группы ресурсов и региона. Кроме того, она содержит поля для всех параметров из шаблона.
Большинство полей являются текстовыми, но некоторые поля характерны для типа параметра. Если шаблон содержит допустимые значения для параметра, автоматически созданная форма использует раскрывающийся элемент. Раскрывающийся элемент предварительно заполняется допустимыми значениями.
Между заголовком и сведениями о проекте нет вкладок, так как в форме по умолчанию определен только один шаг. В разделе Настройка формы вы разбейте параметры на несколько вкладок.
Предупреждение
Не выбирайте Создать, так как будет запущено реальное развертывание. Далее в этом учебнике у вас будет возможность развернуть спецификацию шаблона.
Чтобы выйти из предварительной версии, нажмите кнопку Отмена.
Настройка формы
Форма по умолчанию является хорошей отправной точкой для понимания форм, но, как правило, ее нужно настроить. Вы можете ее изменить в песочнице или в Visual Studio Code. Параметр "Предварительный просмотр" доступен только в песочнице.
Присвойте форме заголовок, описывающий ее использование.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret",В вашей форме по умолчанию все поля для шаблона объединены в один шаг под названием Основы. Чтобы помочь пользователям понять, какие значения они предоставляют, разделите форму на шаги. Каждый шаг содержит поля, связанные с логическим элементом решения, которое нужно развернуть.
Найдите шаг с меткой Основы. Вы продолжите выполнять этот шаг, но вам нужно добавить следующие шаги. В новых шагах основное внимание уделяется настройке хранилища ключей, настройке разрешений пользователя и указанию секрета. Убедитесь, что после шага "Основы" вы добавили запятую.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret", "steps": [ { "name": "basics", "label": "Basics", "elements": [ ... ] }, { "name": "keyvault", "label": "Key Vault", "elements": [ ] }, { "name": "permissions", "label": "Permissions", "elements": [ ] }, { "name": "secret", "label": "Secret", "elements": [ ] } ] }, "outputs": { ... } } }Важно!
В свойствах формы учитывается регистр. Убедитесь, что вы используете регистр, показанный в примерах.
Выберите Предварительный просмотр. Вы увидите шаги, но в большинстве из них нет элементов.
Теперь переместите элементы в соответствующие шаги. Начните с элементов с метками Имя секрета и Значение секрета. Удалите эти элементы из шага Основы и добавьте их в шаг Секрет.
{ "name": "secret", "label": "Secret", "elements": [ { "name": "secretName", "type": "Microsoft.Common.TextBox", "label": "Secret Name", "defaultValue": "", "toolTip": "Specifies the name of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretValue", "type": "Microsoft.Common.PasswordBox", "label": { "password": "Secret Value", "confirmPassword": "Confirm password" }, "toolTip": "Specifies the value of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "options": { "hideConfirmation": true }, "visible": true } ] }При перемещении элементов необходимо исправить раздел
outputs. В настоящее время раздел с выходными данными ссылается на эти элементы, будто они все еще находятся на шаге "Основы". Исправьте синтаксис, чтобы он ссылался на элементы в шагеsecret."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Продолжайте перемещать элементы в соответствующие шаги. Вместо того чтобы просматривать каждый из них, ознакомьтесь с обновленной формой.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret", "steps": [ { "name": "basics", "label": "Basics", "elements": [ { "name": "resourceScope", "type": "Microsoft.Common.ResourceScope", "location": { "resourceTypes": [ "microsoft.resources/resourcegroups" ] } } ] }, { "name": "keyvault", "label": "Key Vault", "elements": [ { "name": "keyVaultName", "type": "Microsoft.Common.TextBox", "label": "Key Vault Name", "defaultValue": "", "toolTip": "Specifies the name of the key vault.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "skuName", "type": "Microsoft.Common.DropDown", "label": "Sku Name", "defaultValue": "Standard", "toolTip": "Specifies whether the key vault is a standard vault or a premium vault.", "constraints": { "required": false, "allowedValues": [ { "label": "Standard", "value": "Standard" }, { "label": "Premium", "value": "Premium" } ] }, "visible": true }, { "name": "location", "type": "Microsoft.Common.TextBox", "label": "Location", "defaultValue": "[[resourceGroup().location]", "toolTip": "Specifies the Azure location where the key vault should be created.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "enabledForDeployment", "type": "Microsoft.Common.DropDown", "label": "Enabled For Deployment", "defaultValue": "false", "toolTip": "Specifies whether Azure Virtual Machines are permitted to retrieve certificates stored as secrets from the key vault.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true }, { "name": "enabledForDiskEncryption", "type": "Microsoft.Common.DropDown", "label": "Enabled For Disk Encryption", "defaultValue": "false", "toolTip": "Specifies whether Azure Disk Encryption is permitted to retrieve secrets from the vault and unwrap keys.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true }, { "name": "enabledForTemplateDeployment", "type": "Microsoft.Common.DropDown", "label": "Enabled For Template Deployment", "defaultValue": "false", "toolTip": "Specifies whether Azure Resource Manager is permitted to retrieve secrets from the key vault.", "constraints": { "required": false, "allowedValues": [ { "label": "true", "value": true }, { "label": "false", "value": false } ] }, "visible": true } ] }, { "name": "permissions", "label": "Permissions", "elements": [ { "name": "tenantId", "type": "Microsoft.Common.TextBox", "label": "Tenant Id", "defaultValue": "[[subscription().tenantId]", "toolTip": "Specifies the Azure Active Directory tenant ID that should be used for authenticating requests to the key vault. Get it by using Get-AzSubscription cmdlet.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "objectId", "type": "Microsoft.Common.TextBox", "label": "Object Id", "defaultValue": "", "toolTip": "Specifies the object ID of a user, service principal or security group in the Azure Active Directory tenant for the vault. The object ID must be unique for the list of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "keysPermissions", "type": "Microsoft.Common.TextBox", "label": "Keys Permissions", "defaultValue": "[[\"list\"]", "toolTip": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretsPermissions", "type": "Microsoft.Common.TextBox", "label": "Secrets Permissions", "defaultValue": "[[\"list\"]", "toolTip": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge.", "constraints": { "required": false, "regex": "", "validationMessage": "" }, "visible": true } ] }, { "name": "secret", "label": "Secret", "elements": [ { "name": "secretName", "type": "Microsoft.Common.TextBox", "label": "Secret Name", "defaultValue": "", "toolTip": "Specifies the name of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "visible": true }, { "name": "secretValue", "type": "Microsoft.Common.PasswordBox", "label": { "password": "Secret Value", "confirmPassword": "Confirm password" }, "toolTip": "Specifies the value of the secret that you want to create.", "constraints": { "required": true, "regex": "", "validationMessage": "" }, "options": { "hideConfirmation": true }, "visible": true } ] } ] }, "outputs": { "parameters": { "keyVaultName": "[steps('keyvault').keyVaultName]", "location": "[steps('keyvault').location]", "enabledForDeployment": "[steps('keyvault').enabledForDeployment]", "enabledForDiskEncryption": "[steps('keyvault').enabledForDiskEncryption]", "enabledForTemplateDeployment": "[steps('keyvault').enabledForTemplateDeployment]", "tenantId": "[steps('permissions').tenantId]", "objectId": "[steps('permissions').objectId]", "keysPermissions": "[steps('permissions').keysPermissions]", "secretsPermissions": "[steps('permissions').secretsPermissions]", "skuName": "[steps('keyvault').skuName]", "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }, "kind": "ResourceGroup", "location": "[steps('basics').resourceScope.location.name]", "resourceGroupId": "[steps('basics').resourceScope.resourceGroup.id]" } } }Сохраните этот файл локально под именем keyvaultform.json.
Создание спецификации шаблона
При создании спецификации шаблона укажите оба файла.
Для PowerShell используйте команду New-AzTemplateSpec и укажите форму в параметре -UIFormDefinitionFile.
New-AzTemplateSpec `
-name keyvaultspec `
-version 1 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
Для Azure CLI используйте команду az ts create и укажите форму в параметре --ui-form-definition.
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Развертывание через портал
Чтобы протестировать форму, перейдите на портал, а затем — к спецификации шаблона и выберите Развернуть.
Вы увидите созданную форму. Выполните шаги и укажите значения для полей.
На шаге Основы вы увидите поле для региона. Это поле используется в качестве расположения группы ресурсов. На шаге Key Vault вы увидите поле для расположения. Это поле используется в качестве расположения хранилища ключей.
На шаге Разрешения можно указать собственный идентификатор пользователя для идентификатора объекта. Используйте значение по умолчанию (["list"]) для разрешений ключа и секрета. Вы улучшите этот параметр в следующем разделе.
Указав все значения, нажмите Создать, чтобы развернуть спецификацию шаблона.
Улучшение формы
В предыдущем разделе вы добавили шаги и переместили элементы, но вы не изменили поведения по умолчанию. В этом разделе вы внесете изменения, которые улучшают работу пользователей вашей спецификации шаблона.
Ранее два поля разрешений были текстовыми. Теперь вы воспользуетесь раскрывающимся списком. Для параметра "Тип" задайте значение Microsoft.Common.DropDown.
Обновление keysPermissions:
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
И secretsPermissions:
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
Эти поля должны передать массив в шаблон. Обычный раскрывающийся список не будет работать, так как он позволяет вам выбрать только одно значение. Чтобы выбрать несколько значений и передать их в виде массива, добавьте поле multiselect и задайте для него значение true.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
В конце вам необходимо указать разрешенные значения для раскрывающегося списка, а также значение по умолчанию.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
"defaultValue":{
"value": "list"
},
"toolTip": "Specifies the permissions to keys in the vault. Valid values are: all, encrypt, decrypt, wrapKey, unwrapKey, sign, verify, get, list, create, update, import, delete, backup, restore, recover, and purge.",
"constraints": {
"required": false,
"allowedValues":[
{
"label": "all",
"value": "all"
},
{
"label": "encrypt",
"value": "encrypt"
},
{
"label": "decrypt",
"value": "decrypt"
},
{
"label": "list",
"value": "list"
},
{
"label": "delete",
"value": "delete"
},
{
"label": "backup",
"value": "backup"
},
{
"label": "restore",
"value": "restore"
},
{
"label": "recover",
"value": "recover"
},
{
"label": "purge",
"value": "purge"
},
{
"label": "wrapKey",
"value": "wrapKey"
},
{
"label": "unwrapKey",
"value": "unwrapKey"
},
{
"label": "sign",
"value": "sign"
},
{
"label": "verify",
"value": "verify"
},
{
"label": "get",
"value": "get"
},
{
"label": "create",
"value": "create"
},
{
"label": "update",
"value": "update"
},
{
"label": "import",
"value": "import"
}
]
},
"visible": true
},
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
"defaultValue":{
"value": "list"
},
"toolTip": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge.",
"constraints": {
"required": false,
"allowedValues":[
{
"label": "all",
"value": "all"
},
{
"label": "get",
"value": "get"
},
{
"label": "list",
"value": "list"
},
{
"label": "set",
"value": "set"
},
{
"label": "delete",
"value": "delete"
},
{
"label": "backup",
"value": "backup"
},
{
"label": "restore",
"value": "restore"
},
{
"label": "recover",
"value": "recover"
},
{
"label": "purge",
"value": "purge"
}
]
},
"visible": true
}
Создайте новую версию спецификации шаблона.
С помощью PowerShell:
New-AzTemplateSpec `
-name keyvaultspec `
-version 2 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
или с помощью Azure CLI:
az ts create \
--name keyvaultspec \
--version 2 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Повторно разверните спецификацию шаблона с помощью улучшенной формы портала.
Обратите внимание, что поля разрешений теперь являются раскрывающимся списком, разрешающим несколько значений.
Дальнейшие действия
Дополнительные сведения о развертывании шаблона спецификации в качестве связанного шаблона см. в разделе Учебник. Развертывание шаблона спецификации в качестве связанного шаблона.