Esercitazione: Creare moduli del portale di Azure per una specifica di modello
Puoi creare un modulo visualizzato nel portale di Azure per aiutare gli utenti a distribuire una specifica di modello. Il modulo consente agli utenti di immettere valori passati come parametri alla specifica di modello.
Quando crei la specifica di modello, il modulo e il modello di Azure Resource Manager (modello di ARM) vengono raggruppati. La distribuzione della specifica di modello tramite il portale avvia automaticamente il modulo.
Lo screenshot seguente mostra un modulo aperto nel portale di Azure.
Prerequisiti
Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Per Azure PowerShell, usa la versione 6.0.0 o successiva. Per l'interfaccia della riga di comando di Azure, usa la versione 2.24.0 o successiva.
Creare il modello
Per visualizzare i diversi elementi del portale disponibili in un modulo, userai un modello di ARM con diversi parametri. Il modello seguente crea un insieme di credenziali delle chiavi, configura le autorizzazioni per l'insieme di credenziali delle chiavi per un utente e aggiunge un segreto.
Copia il file e salvalo in locale. Questa esercitazione presuppone che sia stata stato denominato keyvault.json ma è possibile assegnare qualsiasi nome.
{
"$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')]"
}
}
]
}
Crea modulo predefinito
Il portale di Azure offre una sandbox per la creazione e l'anteprima dei moduli. Questa sandbox può eseguire il rendering di un modulo da un modello di ARM esistente. Userai questo modulo predefinito per iniziare a creare un modulo per la specifica di modello. Per ulteriori informazioni sulla struttura del modulo, vedi FormViewType.
Apri la Sandbox visualizzazione modulo.
In Tipo di pacchetto seleziona CustomTemplate. Assicurati di selezionare il tipo di pacchetto prima di specificare il modello di distribuzione.
In Modello di distribuzione (facoltativo), seleziona il modello dell'insieme di credenziali delle chiavi salvato in locale. Quando viene richiesto se vuoi sovrascrivere le modifiche correnti, seleziona Sì. Il modulo generato automaticamente viene visualizzato nella finestra del codice. Il modulo è modificabile dal portale. Per personalizzare il modulo, vedi Personalizzare il modulo. Se esamini attentamente il modulo generato automaticamente, il titolo predefinito è denominato Visualizzazione modulo di test ed è definito solo un passaggio denominato nozioni di base.
{ "$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": { ... } } }Per verificare che funzioni senza modifiche, seleziona Anteprima.
La sandbox mostra il modulo. Include campi per la selezione di una sottoscrizione, un gruppo di risorse e un'area. Contiene inoltre campi per tutti i parametri del modello.
La maggior parte dei campi sono caselle di testo, ma alcuni campi sono specifici per il tipo di parametro. Quando il tuo modello include valori consentiti per un parametro, il modulo generato automaticamente usa un elemento a discesa. L'elemento a discesa viene prepopolato con i valori consentiti.
Tra il titolo e i i dettagli del progetto non sono presenti schede perché il modulo predefinito dispone di un solo passaggio definito. Nella sezione Personalizza modulo i parametri possono essere suddivisi in più schede.
Avviso
Non selezionare Crea perché questo avvierà una distribuzione reale. Potrai distribuire la specifica di modello più avanti in questa esercitazione.
Per uscire dall'anteprima, seleziona Annulla.
Personalizzare il modulo
Il modulo predefinito è un buon punto di partenza per comprendere i moduli, ma in genere è consigliabile personalizzarlo. Puoi modificarlo nella sandbox o in Visual Studio Code. L'opzione di anteprima è disponibile solo nella sandbox.
Assegna al modulo un titolo che ne descriva l'uso.
{ "$schema": "https://schema.management.azure.com/schemas/2021-09-09/uiFormDefinition.schema.json#", "view": { "kind": "Form", "properties": { "title": "Key Vault and secret",Il modulo predefinito include tutti i campi per il modello in un unico passaggio denominato Basics (Informazioni di base). Per aiutare gli utenti a comprendere i valori che forniscono, dividi il modulo in passaggi. Ogni passaggio contiene campi correlati a una parte logica della soluzione da distribuire.
Trova il passaggio con etichetta Basics. Mantieni questo passaggio, ma aggiungi i passaggi seguenti. I nuovi passaggi si concentreranno sulla configurazione dell'insieme di credenziali delle chiavi, sull'impostazione delle autorizzazioni utente e sulla specifica del segreto. Assicurati di aggiungere una virgola dopo il passaggio di base.
{ "$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": { ... } } }Importante
Le proprietà nel modulo fanno distinzione tra maiuscole e minuscole. Assicurati di usare la combinazione di maiuscole e minuscole mostrata negli esempi.
Seleziona Anteprima. Vedrai i passaggi, ma la maggior parte di essi non include elementi.
Sposta ora gli elementi nei passaggi appropriati. Inizia con gli elementi etichettati Nome segreto e Valore segreto. Rimuovi questi elementi dal passaggio Basics e aggiungili al passaggio Segreto .
{ "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 } ] }Quando sposti gli elementi, devi correggere la sezione
outputs. Attualmente, la sezione outputs fa riferimento a tali elementi come se fossero ancora nel passaggio di base. Correggi la sintassi in modo che faccia riferimento agli elementi nel passaggiosecret."outputs": { "parameters": { ... "secretName": "[steps('secret').secretName]", "secretValue": "[steps('secret').secretValue]" }Continua a spostare gli elementi nei passaggi appropriati. Invece di passare attraverso ognuno di essi, dai un’occhiata al modulo aggiornato.
{ "$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]" } } }Salva questo file in locale con il nome keyvaultform.json.
Creare la specifica di modello
Quando crei la specifica di modello, specifica entrambi i file.
Per PowerShell, usa New-AzTemplateSpec e specifica il modulo nel parametro -UIFormDefinitionFile .
New-AzTemplateSpec `
-name keyvaultspec `
-version 1 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
Per l'interfaccia della riga di comando di Azure, usa az ts create e specifica il modulo nel parametro --ui-form-definition.
az ts create \
--name keyvaultspec \
--version 1 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Distribuisci tramite il portale
Per testare il modulo, vai al portale e passa alla specifica del modello. Selezionare Distribuisci.
Verrà visualizzato il modulo creato. Esegui i passaggi e specifica i valori per i campi.
Nel passaggio Basics verrà visualizzato un campo per Area. Questo campo viene usato per la posizione del gruppo di risorse. Nel passaggio Key Vault (Insieme di credenziali delle chiavi) verrà visualizzato un campo per Posizione. Questo campo viene usato per la posizione dell'insieme di credenziali delle chiavi.
Nel passaggio Permissions (Autorizzazioni di accesso) puoi specificare il tuo ID utente per l'ID oggetto. Usa il valore predefinito (["list"]) per le autorizzazioni chiave e segreto. Potrai migliorare questa opzione nella sezione successiva.
Dopo aver fornito tutti gli altri valori, seleziona Crea per distribuire la specifica di modello.
Migliorare il modulo
Nella sezione precedente hai aggiunto passaggi ed elementi spostati, ma non hai modificato alcun comportamento predefinito. In questa sezione, apporterai delle modifiche che migliorano l'esperienza per gli utenti della specifica di modello.
In precedenza, i due campi delle autorizzazioni erano caselle di testo. Ora userai un elenco a discesa. Imposta il tipo su Microsoft.Common.DropDown.
AggiornamentokeysPermissions:
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
E secretsPermissions:
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
Questi campi devono passare una matrice al modello. Un normale elenco a discesa non funzionerà perché consente solo di selezionare un valore. Per selezionare più di un valore e passarli come matrice, aggiungi il campo multiselect e imposta su true.
{
"name": "keysPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Keys Permissions",
"multiselect": true,
{
"name": "secretsPermissions",
"type": "Microsoft.Common.DropDown",
"label": "Secrets Permissions",
"multiselect": true,
Alla fine, devi specificare i valori consentiti per l'elenco a discesa e un valore predefinito.
{
"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
}
Creare una nuova versione della specifica di modello.
Con PowerShell:
New-AzTemplateSpec `
-name keyvaultspec `
-version 2 `
-ResourceGroupName templateSpecRG `
-location westus2 `
-templatefile keyvault.json `
-UIFormDefinitionFile keyvaultform.json
o l’interfaccia della riga di comando di Azure:
az ts create \
--name keyvaultspec \
--version 2 \
--resource-group templatespecRG \
--location westus2 \
--template-file keyvault.json \
--ui-form-definition keyvaultform.json
Ridistribuisci la tua specifica di modello con il modulo del portale migliorato.
Si noti che i campi delle autorizzazioni ora sono a discesa, per consentire più valori.
Passaggi successivi
Per ulteriori informazioni sulla distribuzione di una specifica di modello come modello collegato, vedi Esercitazione: Distribuire una specifica di modello come modello collegato.