Delen via

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, controleert u de code 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

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

Bicep converteren naar JSON

Gebruik PowerShell of Azure CLI om het mainTemplate.json-bestand 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 mainTemplate.json bestand 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.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]"
    }
  }
}

Uw portalervaring definiëren

Als uitgever definieert u de portalervaring voor het maken van de beheerde toepassing. Het createUiDefinition.json-bestand 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 vraagt de gebruikersinterface u om het voorvoegsel van de App Service-naam en de naam van het App Service-plan in te voeren. Tijdens de implementatie van mainTemplate.json de variabelen de appServiceName uniqueString functie gebruiken om een tekenreeks van 13 tekens toe te voegen aan het naamvoorvoegsel, zodat de naam wereldwijd uniek is 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
          }
        ]
      }
    ],
    "outputs": {
      "location": "[location()]",
      "appServicePlanName": "[steps('webAppSettings').appServicePlanName]",
      "appServiceNamePrefix": "[steps('webAppSettings').appServiceName]"
    }
  }
}

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 <pkgstorageaccountname> , 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 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

De $pkgstorageparms variabele maakt gebruik van PowerShell-splatting om de leesbaarheid te verbeteren voor de parameterwaarden die in de opdracht worden gebruikt om het nieuwe opslagaccount te maken. Splatting wordt gebruikt in andere PowerShell-opdrachten die meerdere parameterwaarden gebruiken.

Nadat u het opslagaccount hebt gemaakt, voegt u de roltoewijzing Opslagblobgegevensbijdrager toe aan het opslagaccountbereik. Wijs toegang toe aan uw Microsoft Entra-gebruikersaccount. Afhankelijk van uw toegangsniveau in Azure hebt u mogelijk andere machtigingen nodig die zijn toegewezen door uw beheerder. Zie Een Azure-rol toewijzen voor toegang tot blobgegevens en Azure-rollen toewijzen met behulp van Azure Portal voor meer informatie.

Nadat u de rol aan het opslagaccount hebt toegevoegd, duurt het enkele minuten om actief te worden in Azure. Vervolgens kunt u de context maken die nodig is om de container te maken en het bestand te uploaden.

$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

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 $pkgstoragecontext).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.bicepparam en sla het op.

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

using './deployDefinition.bicep'

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

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

Parameter Weergegeven als
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.
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 bicepDefinitionGroup en implementeer de definitie van de beheerde toepassing.

New-AzResourceGroup -Name bicepDefinitionGroup -Location westus

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

New-AzResourceGroupDeployment @deployparms

De resultaten controleren

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

Get-AzManagedApplicationDefinition -ResourceGroupName bicepDefinitionGroup

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 packageStorageGroup en bicepDefinitionGroup.

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

Remove-AzResourceGroup -Name packageStorageGroup

Remove-AzResourceGroup -Name bicepDefinitionGroup

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.