Avvio rapido: Usare Bicep per creare e pubblicare una definizione di applicazione gestita di Azure

Questo avvio rapido descrive come usare Bicep per creare e pubblicare una definizione di applicazione gestita di Azure nel catalogo di servizi. Le definizioni nel catalogo di servizi sono disponibili per i membri dell'organizzazione.

Per creare e pubblicare una definizione di applicazione gestita nel catalogo di servizi, seguire questa procedura:

• Usare Bicep per sviluppare il modello e convertirlo in un modello di Azure Resource Manager (modello ARM). Il modello definisce le risorse di Azure distribuite dall'applicazione gestita.
• Convertire Bicep in JSON con il comando Bicep build. Dopo aver convertito il file in JSON, verificare l'accuratezza del codice.
• Definire gli elementi dell'interfaccia utente per il portale quando si distribuisce l'applicazione gestita.
• Creare un pacchetto ZIP contenente i file JSON necessari. Il file del pacchetto ZIP ha un limite di 120 MB per una definizione di applicazione gestita del catalogo di servizi.
• Pubblicare la definizione di applicazione gestita in modo che sia disponibile nel catalogo di servizi.

Se la definizione dell'applicazione gestita è superiore a 120 MB o se si vuole usare il proprio account di archiviazione per motivi di conformità dell'organizzazione, vedere Avvio rapido: Creare e pubblicare una definizione di applicazione gestita di Azure con una risorsa di archiviazione personalizzata (BYOS, Bring Your Own Storage).

È anche possibile usare Bicep per distribuire una definizione di applicazione gestita dal catalogo di servizi. Per altre informazioni, vedere Avvio rapido: Usare Bicep per distribuire una definizione di applicazione gestita di Azure.

Prerequisiti

Per seguire la procedura descritta in questo articolo, sono necessari gli elementi seguenti:

• Un account Azure con una sottoscrizione attiva e le autorizzazioni per le risorse di Microsoft Entra, ad esempio utenti, gruppi o entità servizio. Se non si ha un account Azure, crearne uno gratuito prima di iniziare.
• Visual Studio Code con l'estensione Strumenti di Azure Resource Manager più recente. Per i file Bicep, installare l'estensione Bicep per Visual Studio Code.
• Installare la versione più recente di Azure PowerShell o dell'interfaccia della riga di comando di Azure.

Creare un file Bicep

Ogni definizione di applicazione gestita include un file denominato mainTemplate.json, Il modello definisce le risorse di Azure da distribuire e non è diverso da un normale modello di ARM. È possibile sviluppare il modello usando Bicep e quindi convertire il file Bicep in JSON.

Aprire Visual Studio Code, creare un file con un nome che fa distinzione tra maiuscole e minuscole mainTemplate.bicep e salvarlo.

Aggiungere il codice Bicep seguente e salvare il file. Definisce le risorse dell'applicazione gestita per distribuire un servizio app, un piano di servizio app e un account di archiviazione.

param location string = resourceGroup().location

@description('App Service plan name.')
@maxLength(40)
param appServicePlanName string

@description('App Service name prefix.')
@maxLength(47)
param appServiceNamePrefix string

var appServicePlanSku = 'B1'
var appServicePlanCapacity = 1
var appServiceName = '${appServiceNamePrefix}${uniqueString(resourceGroup().id)}'
var linuxFxVersion = 'DOTNETCORE|8.0'

resource appServicePlan 'Microsoft.Web/serverfarms@2023-01-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanCapacity
  }
  kind: 'linux'
  properties: {
    zoneRedundant: false
    reserved: true
  }
}

resource appService 'Microsoft.Web/sites@2023-01-01' = {
  name: appServiceName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
    redundancyMode: 'None'
    siteConfig: {
      linuxFxVersion: linuxFxVersion
      minTlsVersion: '1.2'
      ftpsState: 'Disabled'
    }
  }
}

output appServicePlan string = appServicePlanName
output appServiceApp string = appService.properties.defaultHostName

Convertire Bicep in JSON

Usare PowerShell o l'interfaccia della riga di comando di Azure per compilare il file mainTemplate.json. Andare alla directory in cui è stato salvato il file Bicep ed eseguire il comando build.

bicep build mainTemplate.bicep

az bicep build --file mainTemplate.bicep

Per altre informazioni, vedere il comando Bicep build.

Dopo la conversione del file Bicep in JSON, il file mainTemplate.json corrisponderà all'esempio seguente. È possibile che siano presenti valori diversi nelle proprietà metadata per version e templateHash.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.30.3.12046",
      "templateHash": "16466621031230437685"
    }
  },
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "appServicePlanName": {
      "type": "string",
      "maxLength": 40,
      "metadata": {
        "description": "App Service plan name."
      }
    },
    "appServiceNamePrefix": {
      "type": "string",
      "maxLength": 47,
      "metadata": {
        "description": "App Service name prefix."
      }
    }
  },
  "variables": {
    "appServicePlanSku": "B1",
    "appServicePlanCapacity": 1,
    "appServiceName": "[format('{0}{1}', parameters('appServiceNamePrefix'), uniqueString(resourceGroup().id))]",
    "linuxFxVersion": "DOTNETCORE|8.0"
  },
  "resources": [
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2023-01-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[variables('appServicePlanSku')]",
        "capacity": "[variables('appServicePlanCapacity')]"
      },
      "kind": "linux",
      "properties": {
        "zoneRedundant": false,
        "reserved": true
      }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2023-01-01",
      "name": "[variables('appServiceName')]",
      "location": "[parameters('location')]",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "httpsOnly": true,
        "redundancyMode": "None",
        "siteConfig": {
          "linuxFxVersion": "[variables('linuxFxVersion')]",
          "minTlsVersion": "1.2",
          "ftpsState": "Disabled"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]"
      ]
    }
  ],
  "outputs": {
    "appServicePlan": {
      "type": "string",
      "value": "[parameters('appServicePlanName')]"
    },
    "appServiceApp": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Web/sites', variables('appServiceName')), '2023-01-01').defaultHostName]"
    }
  }
}

Definire l'esperienza del portale

Un editore definisce l'esperienza del portale per la creazione dell'applicazione gestita. Il file createUiDefinition.json genera l'interfaccia utente del portale. È possibile definire il modo in cui gli utenti specificheranno l'input per ogni parametro usando elementi di controllo, ad esempio elenchi a discesa e caselle di testo.

In questo esempio, l'interfaccia utente richiede di immettere il prefisso del nome del Servizio app e il nome del piano di servizio app. Durante la distribuzione di mainTemplate.json, le variabili appServiceName usano la funzione uniqueString per aggiungere una stringa di 13 caratteri al prefisso del nome in modo che il nome sia univoco a livello globale in Azure.

Aprire Visual Studio Code, creare un file con un nome che fa distinzione tra maiuscole e minuscole createUiDefinition.json e salvarlo.

Aggiungere il codice JSON seguente al file e salvarlo.

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "basics": [
      {}
    ],
    "steps": [
      {
        "name": "webAppSettings",
        "label": "Web App settings",
        "subLabel": {
          "preValidation": "Configure the web app settings",
          "postValidation": "Completed"
        },
        "elements": [
          {
            "name": "appServicePlanName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service plan name",
            "placeholder": "App Service plan name",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with a maximum of 40 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{1,40}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a maximum of 40 characters."
            },
            "visible": true
          },
          {
            "name": "appServiceName",
            "type": "Microsoft.Common.TextBox",
            "label": "App Service name prefix",
            "placeholder": "App Service name prefix",
            "defaultValue": "",
            "toolTip": "Use alphanumeric characters or hyphens with minimum of 2 characters and maximum of 47 characters.",
            "constraints": {
              "required": true,
              "regex": "^[a-z0-9A-Z-]{2,47}$",
              "validationMessage": "Only alphanumeric characters or hyphens are allowed, with a minimum of 2 characters and maximum of 47 characters."
            },
            "visible": true
          }
        ]
      }
    ],
    "outputs": {
      "location": "[location()]",
      "appServicePlanName": "[steps('webAppSettings').appServicePlanName]",
      "appServiceNamePrefix": "[steps('webAppSettings').appServiceName]"
    }
  }
}

Per altre informazioni, vedere Introduzione a CreateUiDefinition.

Creare il pacchetto dei file

Aggiungere i due file a un file di pacchetto denominato app.zip. I due file devono trovarsi al livello radice del file con estensione zip. Se i file si trovano all'interno di una cartella, durante la creazione della definizione di applicazione gestita viene visualizzato un errore che indica che i file necessari non sono presenti.

Caricare app.zip in un account di archiviazione di Azure in modo da poterlo usare quando si distribuisce la definizione di applicazione gestita. Il nome dell'account di archiviazione deve essere univoco a livello globale in Azure, la lunghezza deve essere compresa tra 3 e 24 caratteri e deve contenere solo lettere minuscole e numeri. Nel comando sostituire il segnaposto <pkgstorageaccountname>, incluse le parentesi acute (<>), con il nome dell'account di archiviazione univoco.

Connect-AzAccount

New-AzResourceGroup -Name packageStorageGroup -Location westus

$pkgstorageparms = @{
  ResourceGroupName = "packageStorageGroup"
  Name = "<pkgstorageaccountname>"
  Location = "westus"
  SkuName = "Standard_LRS"
  Kind = "StorageV2"
  MinimumTlsVersion = "TLS1_2"
  AllowBlobPublicAccess = $true
  AllowSharedKeyAccess = $false
}

$pkgstorageaccount = New-AzStorageAccount @pkgstorageparms

$pkgstoragecontext = New-AzStorageContext -StorageAccountName $pkgstorageaccount.StorageAccountName -UseConnectedAccount

New-AzStorageContainer -Name appcontainer -Context $pkgstoragecontext -Permission blob

$blobparms = @{
  File = "app.zip"
  Container = "appcontainer"
  Blob = "app.zip"
  Context = $pkgstoragecontext
}

Set-AzStorageBlobContent @blobparms

$packageuri=(Get-AzStorageBlob -Container appcontainer -Blob app.zip -Context $pkgstoragecontext).ICloudBlob.StorageUri.PrimaryUri.AbsoluteUri

az login

az group create --name packageStorageGroup --location westus

az storage account create \
  --name <pkgstorageaccountname> \
  --resource-group packageStorageGroup \
  --location westus \
  --sku Standard_LRS \
  --kind StorageV2 \
  --min-tls-version TLS1_2 \
  --allow-blob-public-access true \
  --allow-shared-key-access false

pkgstgacct=$(az storage account show \
  --resource-group packageStorageGroup \
  --name <pkgstorageaccountname> \
  --query name \
  --output tsv)

az storage container create \
  --account-name $pkgstgacct \
  --name appcontainer \
  --auth-mode login \
  --public-access blob

az storage blob upload \
  --account-name $pkgstgacct \
  --container-name appcontainer \
  --auth-mode login \
  --name "app.zip" \
  --file "app.zip"

packageuri=$(az storage blob url \
  --account-name $pkgstgacct \
  --container-name appcontainer \
  --auth-mode login \
  --name app.zip --output tsv)

Creare la definizione di applicazione gestita

In questa sezione si ottengono informazioni sull'identità da Microsoft Entra ID, si crea un gruppo di risorse e si distribuisce la definizione di applicazione gestita.

Ottenere l'ID gruppo e l'ID della definizione del ruolo

Nel passaggio successivo si selezionerà un gruppo di utenti, un utente o un'applicazione per gestire le risorse per il cliente. Questa identità ha le autorizzazioni per il gruppo di risorse gestite in base al ruolo assegnato. Il ruolo può essere qualsiasi ruolo predefinito di Azure, ad esempio Proprietario o Collaboratore.

Questo esempio usa un gruppo di sicurezza e l'account Microsoft Entra deve essere membro del gruppo. Per ottenere l'ID oggetto del gruppo, sostituire il segnaposto <managedAppDemo> incluse le parentesi acute (<>) con il nome del gruppo. Quando si distribuisce la definizione di applicazione gestita, si usa il valore della variabile.

Per creare un nuovo gruppo di Microsoft Entra, passare a Gestire i gruppi di Microsoft Entra e l'appartenenza a gruppi.

$principalid=(Get-AzADGroup -DisplayName <managedAppDemo>).Id

principalid=$(az ad group show --group <managedAppDemo> --query id --output tsv)

Recuperare quindi l'ID definizione del ruolo predefinito di Azure a cui concedere l'accesso all'utente, al gruppo o all'applicazione. Quando si distribuisce la definizione di applicazione gestita, si usa il valore della variabile.

$roleid=(Get-AzRoleDefinition -Name Owner).Id

roleid=$(az role definition list --name Owner --query [].name --output tsv)

Creare il modello di distribuzione delle definizioni

Usare un file Bicep per distribuire la definizione di applicazione gestita nel catalogo di servizi.

Aprire Visual Studio Code, creare un file con il nome deployDefinition.bicep e salvarlo.

Aggiungere il codice Bicep seguente e salvare il file.

param location string = resourceGroup().location

@description('Name of the managed application definition.')
param managedApplicationDefinitionName string

@description('The URI of the .zip package file.')
param packageFileUri string

@description('Publishers Principal ID that needs permissions to manage resources in the managed resource group.')
param principalId string

@description('Role ID for permissions to the managed resource group.')
param roleId string

var definitionLockLevel = 'ReadOnly'
var definitionDisplayName = 'Sample Bicep managed application'
var definitionDescription = 'Sample Bicep managed application that deploys web resources'

resource managedApplicationDefinition 'Microsoft.Solutions/applicationDefinitions@2021-07-01' = {
  name: managedApplicationDefinitionName
  location: location
  properties: {
    lockLevel: definitionLockLevel
    description: definitionDescription
    displayName: definitionDisplayName
    packageFileUri: packageFileUri
    authorizations: [
      {
        principalId: principalId
        roleDefinitionId: roleId
      }
    ]
  }
}

Per altre informazioni sulle proprietà del modello, vedere Microsoft.Solutions/applicationDefinitions.

lockLevel nel gruppo di risorse gestite impedisce al cliente di eseguire operazioni indesiderate su questo gruppo di risorse. ReadOnly è attualmente il solo livello di blocco supportato. ReadOnly specifica che il cliente è autorizzato solo alla lettura delle risorse presenti nel gruppo di risorse gestite. Le identità degli editori a cui è concesso l'accesso al gruppo di risorse gestito sono esenti dal livello di blocco.

Creare il file di parametri

Il modello di distribuzione della definizione di applicazione gestita richiede l'input per numerosi parametri. Il comando di distribuzione richiede di immettere i valori oppure è possibile creare un file di parametri per i valori. In questo esempio verrà usato un file di parametri per passare i valori dei parametri al comando di distribuzione.

In Visual Studio Code creare un nuovo file denominato deployDefinition-parameters.bicepparam e salvarlo.

Aggiungere quanto segue al file dei parametri e salvarlo. Sostituire quindi <placeholder values>, incluse le parentesi acute (<>), con i valori.

using './deployDefinition.bicep'

param managedApplicationDefinitionName = 'sampleBicepManagedApplication'
param packageFileUri = '<placeholder for the packageFileUri>'
param principalId = '<placeholder for principalid value>'
param roleId = '<placeholder for roleid value>'

Nella tabella seguente vengono descritti i valori dei parametri per la definizione di applicazione gestita.

Per ottenere i valori delle variabili:

• Azure PowerShell: in PowerShell digitare $variableName per visualizzare il valore di una variabile.
• Interfaccia della riga di comando di Azure: in Bash digitare echo $variableName per visualizzare il valore di una variabile.

Distribuire la definizione

Con la distribuzione, la definizione di applicazione gestita diventa disponibile nel catalogo di servizi. Questo processo non distribuisce le risorse dell'applicazione gestita.

Creare un gruppo di risorse denominato bicepDefinitionGroup e distribuire la definizione di applicazione gestita.

New-AzResourceGroup -Name bicepDefinitionGroup -Location westus

$deployparms = @{
  ResourceGroupName = "bicepDefinitionGroup"
  TemplateFile = "deployDefinition.bicep"
  TemplateParameterFile = "deployDefinition-parameters.bicepparam"
  Name = "deployDefinition"
}

New-AzResourceGroupDeployment @deployparms

az group create --name bicepDefinitionGroup --location westus

az deployment group create \
  --resource-group bicepDefinitionGroup \
  --template-file deployDefinition.bicep \
  --parameters deployDefinition-parameters.bicepparam \
  --name "deployDefinition"

Verificare i risultati

Eseguire il comando seguente per verificare che la definizione sia pubblicata nel catalogo di servizi.

Get-AzManagedApplicationDefinition -ResourceGroupName bicepDefinitionGroup

az managedapp definition list --resource-group bicepDefinitionGroup

Assicurarsi che gli utenti possano accedere alla definizione

Si ha accesso alla definizione dell'applicazione gestita, ma si vuole assicurarsi che gli altri utenti nell'organizzazione possano accedervi. Concedere loro almeno il ruolo di Lettore per la definizione. Gli utenti potrebbero aver ereditato questo livello di accesso dalla sottoscrizione o dal gruppo di risorse. Per verificare chi può accedere alla definizione e aggiungere utenti o gruppi, passare a Assegnare ruoli di Azure usando il portale di Azure.

Pulire le risorse

Se si intende distribuire la definizione, continuare con la sezione Passaggi successivi che include un collegamento all'articolo per distribuire la definizione con Bicep.

Se la definizione di applicazione gestita è stata completata, è possibile eliminare i gruppi di risorse creati denominati packageStorageGroup e bicepDefinitionGroup.

Remove-AzResourceGroup -Name packageStorageGroup

Remove-AzResourceGroup -Name bicepDefinitionGroup

az group delete --resource-group packageStorageGroup --no-wait

az group delete --resource-group bicepDefinitionGroup --no-wait

Passaggi successivi

La definizione di applicazione gestita è stata pubblicata. Il passaggio successivo consiste nell'apprendere come distribuire un'istanza di tale definizione.