Quickstart: Bicep gebruiken om een definitie van een door Azure beheerde toepassing te maken en publiceren

  • Artikel

In deze quickstart wordt beschreven hoe u Bicep gebruikt voor het maken en publiceren van een definitie van een door Azure beheerde toepassing in uw servicecatalogus. De definitie in uw servicecatalogus is beschikbaar voor leden van uw organisatie.

Voer de volgende taken uit om een definitie van een beheerde toepassing te maken en te publiceren in uw servicecatalogus:

  • Gebruik Bicep om uw sjabloon te ontwikkelen en deze te converteren naar een ARM-sjabloon (Azure Resource Manager). De sjabloon definieert de Azure-resources die zijn geïmplementeerd door de beheerde toepassing.
  • Converteer Bicep naar JSON met de Bicep-opdracht build . Nadat het bestand is geconverteerd naar JSON, is het raadzaam om de code te controleren op nauwkeurigheid.
  • De elementen van de gebruikersinterface voor de portal definiëren bij het implementeren van de beheerde toepassing.
  • Maak een ZIP-pakket met de vereiste JSON-bestanden. Het ZIP-pakketbestand heeft een limiet van 120 MB voor de definitie van een beheerde toepassing van een servicecatalogus.
  • Publiceer de definitie van de beheerde toepassing zodat deze beschikbaar is in uw servicecatalogus.

Als de definitie van uw beheerde toepassing meer dan 120 MB is of als u uw eigen opslagaccount wilt gebruiken om de nalevingsredenen van uw organisatie, gaat u naar quickstart: Bring your own storage to create and publish an Azure Managed Application definition.

U kunt ook Bicep een definitie van een beheerde toepassing implementeren vanuit uw servicecatalogus. Ga voor meer informatie naar Quickstart: Bicep gebruiken om een definitie van een beheerde Azure-toepassing te implementeren.

Vereisten

Als u de taken in dit artikel wilt uitvoeren, hebt u het volgende nodig:

Een Bicep-bestand maken

De definitie van een beheerde toepassing bevat altijd een bestand met de naam mainTemplate.json. De sjabloon definieert de Azure-resources die moeten worden geïmplementeerd en verschilt niet van een gewone ARM-sjabloon. U kunt de sjabloon ontwikkelen met Bicep en vervolgens het Bicep-bestand converteren naar JSON.

Open Visual Studio Code, maak een bestand met de hoofdlettergevoelige naam mainTemplate.bicep en sla het op.

Voeg de volgende Bicep-code toe en sla het bestand op. Hiermee definieert u de resources van de beheerde toepassing voor het implementeren van een App Service-, App Service-plan en een opslagaccount.

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

@description('Storage account name prefix.')
@maxLength(11)
param storageAccountNamePrefix string

@description('Storage account type allowed values')
@allowed([
  'Premium_LRS'
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountType string

var appServicePlanSku = 'F1'
var appServicePlanCapacity = 1
var appServiceName = '${appServiceNamePrefix}${uniqueString(resourceGroup().id)}'
var storageAccountName = '${storageAccountNamePrefix}${uniqueString(resourceGroup().id)}'
var appServiceStorageConnectionString = 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};EndpointSuffix=${environment().suffixes.storage};Key=${storageAccount.listKeys().keys[0].value}'

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku
    capacity: appServicePlanCapacity
  }
}

resource appServiceApp 'Microsoft.Web/sites@2022-03-01' = {
  name: appServiceName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    httpsOnly: true
    siteConfig: {
      appSettings: [
        {
          name: 'AppServiceStorageConnectionString'
          value: appServiceStorageConnectionString
        }
      ]
    }
  }
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

output appServicePlan string = appServicePlan.name
output appServiceApp string = appServiceApp.properties.defaultHostName
output storageAccount string = storageAccount.properties.primaryEndpoints.blob

Bicep converteren naar JSON

Gebruik PowerShell of Azure CLI om het bestand mainTemplate.json te bouwen. Ga naar de map waarin u uw Bicep-bestand hebt opgeslagen en voer de build opdracht uit.

bicep build mainTemplate.bicep

Ga naar Bicep build voor meer informatie.

Nadat het Bicep-bestand is geconverteerd naar JSON, moet het bestand mainTemplate.json overeenkomen met het volgende voorbeeld. Mogelijk hebt u verschillende waarden in de metadata eigenschappen voor version en templateHash.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.17.1.54307",
      "templateHash": "1234567891234567890"
    }
  },
  "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."
      }
    },
    "storageAccountNamePrefix": {
      "type": "string",
      "maxLength": 11,
      "metadata": {
        "description": "Storage account name prefix."
      }
    },
    "storageAccountType": {
      "type": "string",
      "allowedValues": [
        "Premium_LRS",
        "Standard_LRS",
        "Standard_GRS"
      ],
      "metadata": {
        "description": "Storage account type allowed values"
      }
    }
  },
  "variables": {
    "appServicePlanSku": "F1",
    "appServicePlanCapacity": 1,
    "appServiceName": "[format('{0}{1}', parameters('appServiceNamePrefix'), uniqueString(resourceGroup().id))]",
    "storageAccountName": "[format('{0}{1}', parameters('storageAccountNamePrefix'), uniqueString(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2022-03-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[variables('appServicePlanSku')]",
        "capacity": "[variables('appServicePlanCapacity')]"
      }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2022-03-01",
      "name": "[variables('appServiceName')]",
      "location": "[parameters('location')]",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "httpsOnly": true,
        "siteConfig": {
          "appSettings": [
            {
              "name": "AppServiceStorageConnectionString",
              "value": "[format('DefaultEndpointsProtocol=https;AccountName={0};EndpointSuffix={1};Key={2}', variables('storageAccountName'), environment().suffixes.storage, listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2022-09-01').keys[0].value)]"
            }
          ]
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
      ]
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {
        "accessTier": "Hot"
      }
    }
  ],
  "outputs": {
    "appServicePlan": {
      "type": "string",
      "value": "[parameters('appServicePlanName')]"
    },
    "appServiceApp": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Web/sites', variables('appServiceName')), '2022-03-01').defaultHostName]"
    },
    "storageAccount": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2022-09-01').primaryEndpoints.blob]"
    }
  }
}

Uw portalervaring definiëren

Als uitgever definieert u de portalervaring voor het maken van de beheerde toepassing. Het bestand createUiDefinition.json genereert de gebruikersinterface van de portal. U definieert hoe gebruikers invoer bieden voor elke parameter met behulp van besturingselementen zoals vervolgkeuzelijsten en tekstvakken.

In dit voorbeeld wordt u in de gebruikersinterface gevraagd om het voorvoegsel van de App Service-naam, de naam van het App Service-plan, het voorvoegsel van het opslagaccount en het type opslagaccount in te voeren. Tijdens de implementatie gebruiken de variabelen in mainTemplate.json de uniqueString functie om een tekenreeks van 13 tekens toe te voegen aan de naamvoorvoegsels, zodat de namen wereldwijd uniek zijn in Azure.

Open Visual Studio Code, maak een bestand met de hoofdlettergevoelige naam createUiDefinition.json en sla het op.

Voeg de volgende JSON-code toe aan het bestand en sla deze op.

{
  "$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
          }
        ]
      },
      {
        "name": "storageConfig",
        "label": "Storage settings",
        "subLabel": {
          "preValidation": "Configure the storage settings",
          "postValidation": "Completed"
        },
        "elements": [
          {
            "name": "storageAccounts",
            "type": "Microsoft.Storage.MultiStorageAccountCombo",
            "label": {
              "prefix": "Storage account name prefix",
              "type": "Storage account type"
            },
            "toolTip": {
              "prefix": "Enter maximum of 11 lowercase letters or numbers.",
              "type": "Available choices are Standard_LRS, Standard_GRS, and Premium_LRS."
            },
            "defaultValue": {
              "type": "Standard_LRS"
            },
            "constraints": {
              "allowedTypes": [
                "Premium_LRS",
                "Standard_LRS",
                "Standard_GRS"
              ]
            },
            "visible": true
          }
        ]
      }
    ],
    "outputs": {
      "location": "[location()]",
      "appServicePlanName": "[steps('webAppSettings').appServicePlanName]",
      "appServiceNamePrefix": "[steps('webAppSettings').appServiceName]",
      "storageAccountNamePrefix": "[steps('storageConfig').storageAccounts.prefix]",
      "storageAccountType": "[steps('storageConfig').storageAccounts.type]"
    }
  }
}

Ga naar Aan de slag met CreateUiDefinition voor meer informatie.

De bestanden verpakken

Voeg de twee bestanden toe aan een pakketbestand met de naam app.zip. De twee bestanden moeten zich in de hoofdmap van het .zip-bestand bevinden. Als de bestanden zich in een map bevinden en u de definitie van de beheerde toepassing maakt, krijgt u een foutmelding waarin wordt aangegeven dat de vereiste bestanden niet aanwezig zijn.

Upload app.zip naar een Azure-opslagaccount, zodat u dit kunt gebruiken wanneer u de definitie van de beheerde toepassing implementeert. De naam van het opslagaccount moet globaal uniek zijn in Azure en de lengte moet 3-24 tekens zijn met alleen kleine letters en cijfers. Vervang in de opdracht de tijdelijke aanduiding <demostorageaccount> , inclusief de punthaken (<>), door de unieke naam van uw opslagaccount.

Open in Visual Studio Code een nieuwe PowerShell-terminal en meld u aan bij uw Azure-abonnement.

Connect-AzAccount

Met de opdracht opent u uw standaardbrowser en wordt u gevraagd u aan te melden bij Azure. Ga naar Aanmelden met Azure PowerShell voor meer informatie.

Nadat u verbinding hebt gemaakt, voert u de volgende opdrachten uit.

New-AzResourceGroup -Name packageStorageRG -Location westus3

$storageAccount = New-AzStorageAccount `
  -ResourceGroupName packageStorageRG `
  -Name "<demostorageaccount>" `
  -Location westus3 `
  -SkuName Standard_LRS `
  -Kind StorageV2 `
  -AllowBlobPublicAccess $true

$ctx = $storageAccount.Context

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

Set-AzStorageBlobContent `
  -File "app.zip" `
  -Container appcontainer `
  -Blob "app.zip" `
  -Context $ctx

Gebruik de volgende opdracht om de URI van het pakketbestand op te slaan in een variabele met de naam packageuri. U gebruikt de waarde van de variabele wanneer u de definitie van de beheerde toepassing implementeert.

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

De definitie van de beheerde toepassing maken

In deze sectie haalt u identiteitsgegevens op uit Microsoft Entra-id, maakt u een resourcegroep en implementeert u de definitie van de beheerde toepassing.

Groeps-id en roldefinitie-id ophalen

De volgende stap bestaat uit het selecteren van een gebruiker, beveiligingsgroep of toepassing voor het beheren van de resources voor de klant. Deze identiteit heeft machtigingen voor de beheerde resourcegroep op basis van de toegewezen rol. De rol kan elke ingebouwde rol van op rollen gebaseerd toegangsbeheer (RBAC) zijn, zoals Eigenaar of Inzender.

In dit voorbeeld wordt een beveiligingsgroep gebruikt en uw Microsoft Entra-account moet lid zijn van de groep. Als u de object-id van de groep wilt ophalen, vervangt u de tijdelijke aanduiding <managedAppDemo> inclusief de punthaken (<>), door de naam van de groep. U gebruikt de waarde van de variabele wanneer u de definitie van de beheerde toepassing implementeert.

Als u een nieuwe Microsoft Entra-groep wilt maken, gaat u naar Microsoft Entra-groepen en groepslidmaatschap beheren.

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

Haal vervolgens de roldefinitie-id op van de ingebouwde Azure-rol die u toegang wilt verlenen tot de gebruiker, groep of toepassing. U gebruikt de waarde van de variabele wanneer u de definitie van de beheerde toepassing implementeert.

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

De definitie-implementatiesjabloon maken

Gebruik een Bicep-bestand om de definitie van de beheerde toepassing in uw servicecatalogus te implementeren.

Open Visual Studio Code, maak een bestand met de naam deployDefinition.bicep en sla het op.

Voeg de volgende Bicep-code toe en sla het bestand op.

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
      }
    ]
  }
}

Ga naar Microsoft.Solutions/applicationDefinitions voor meer informatie over de eigenschappen van de sjabloon.

Met lockLevel de beheerde resourcegroep voorkomt u dat de klant ongewenste bewerkingen op deze resourcegroep uitvoert. ReadOnly Momenteel is dit het enige ondersteunde vergrendelingsniveau. ReadOnly geeft aan dat de klant alleen de resources kan lezen die aanwezig zijn in de beheerde resourcegroep. De uitgeversidentiteiten die toegang krijgen tot de beheerde resourcegroep, zijn uitgesloten van het vergrendelingsniveau.

Het parameterbestand maken

De implementatiesjabloon van de definitie van de beheerde toepassing heeft invoer nodig voor verschillende parameters. De implementatieopdracht vraagt u om de waarden of u kunt een parameterbestand voor de waarden maken. In dit voorbeeld gebruiken we een parameterbestand om de parameterwaarden door te geven aan de implementatieopdracht.

Maak in Visual Studio Code een nieuw bestand met de naam deployDefinition.parameters.json en sla het op.

Voeg het volgende toe aan het parameterbestand en sla het op. Vervang vervolgens de <placeholder values> punthaken (<>) door uw waarden.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "managedApplicationDefinitionName": {
      "value": "sampleBicepManagedApplication"
    },
    "packageFileUri": {
      "value": "<placeholder for the packageFileUri>"
    },
    "principalId": {
      "value": "<placeholder for principalid value>"
    },
    "roleId": {
      "value": "<placeholder for roleid value>"
    }
  }
}

In de volgende tabel worden de parameterwaarden voor de definitie van de beheerde toepassing beschreven.

Parameter Waarde
managedApplicationDefinitionName Naam van de definitie van de beheerde toepassing. Gebruik voor dit voorbeeld sampleBicepManagedApplication.
packageFileUri Voer de URI in voor het ZIP-pakketbestand . Gebruik de waarde van uw packageuri variabele. De indeling is https://yourStorageAccountName.blob.core.windows.net/appcontainer/app.zip.
principalId De principal-id van uitgevers die machtigingen nodig heeft voor het beheren van resources in de beheerde resourcegroep. Gebruik de waarde van uw principalid variabele.
roleId Rol-id voor machtigingen voor de beheerde resourcegroep. Bijvoorbeeld Eigenaar, Inzender, Lezer. Gebruik de waarde van uw roleid variabele.

Ga als volgende te werk om uw variabelewaarden op te halen:

  • Azure PowerShell: Typ $variableName in PowerShell om de waarde van een variabele weer te geven.
  • Azure CLI: Typ in Bash echo $variableName om de waarde van een variabele weer te geven.

De definitie implementeren

Wanneer u de definitie van de beheerde toepassing implementeert, wordt deze beschikbaar in uw servicecatalogus. Met dit proces worden de resources van de beheerde toepassing niet geïmplementeerd.

Maak een resourcegroep met de naam bicepDefinitionRG en implementeer de definitie van de beheerde toepassing.

New-AzResourceGroup -Name bicepDefinitionRG -Location westus3

New-AzResourceGroupDeployment `
  -ResourceGroupName bicepDefinitionRG `
  -TemplateFile deployDefinition.bicep `
  -TemplateParameterFile deployDefinition.parameters.json

De resultaten controleren

Voer de volgende opdracht uit om te controleren of de definitie is gepubliceerd in uw servicecatalogus.

Get-AzManagedApplicationDefinition -ResourceGroupName bicepDefinitionRG

Get-AzManagedApplicationDefinition bevat alle beschikbare definities in de opgegeven resourcegroep, zoals sampleBicepManagedApplication.

Zorg ervoor dat gebruikers toegang hebben tot uw definitie

U hebt toegang tot de definitie van de beheerde toepassing, maar u wilt controleren of andere gebruikers in uw organisatie hiertoe toegang hebben. Verleen hun minimaal de rol van Lezer voor de definitie. Mogelijk hebben ze dit toegangsniveau overgenomen van het abonnement of de resourcegroep. Als u wilt controleren wie toegang heeft tot de definitie en gebruikers of groepen wilt toevoegen, gaat u naar Azure-rollen toewijzen met behulp van Azure Portal.

Resources opschonen

Als u de definitie gaat implementeren, gaat u verder met de sectie Volgende stappen die is gekoppeld aan het artikel om de definitie te implementeren met Bicep.

Als u klaar bent met de definitie van de beheerde toepassing, kunt u de resourcegroepen verwijderen die u hebt gemaakt met de naam packageStorageRG en bicepDefinitionRG.

Met de opdracht wordt u gevraagd om te bevestigen dat u de resourcegroep wilt verwijderen.

Remove-AzResourceGroup -Name packageStorageRG

Remove-AzResourceGroup -Name bicepDefinitionRG

Volgende stappen

U hebt de definitie van de beheerde toepassing gepubliceerd. De volgende stap is om te leren hoe u een exemplaar van die definitie implementeert.

Quickstart: Bicep gebruiken om een definitie van een door Azure beheerde toepassing te implementeren.