Delen via

Een implementatiescript ontwikkelen in Bicep

  • Artikel

Dit artikel bevat voorbeelden om u te laten zien hoe u een implementatiescript ontwikkelt in Bicep.

Resources voor implementatiescripts hebben mogelijk een implementatieduur. Voor een efficiënte ontwikkeling en het testen van deze scripts kunt u overwegen een toegewezen ontwikkelomgeving te maken, zoals een Azure-containerinstantie (ACI) of een Docker-exemplaar. Zie Een ontwikkelomgeving maken voor meer informatie.

Syntaxis

Het volgende Bicep-bestand is een voorbeeld van een implementatiescriptresource. Zie het meest recente schema voor implementatiescripts voor meer informatie.

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

Geef in uw implementatiescript deze eigenschapswaarden op:

  • tags: Geef scripttags voor implementatie op. Als de implementatiescriptservice de twee ondersteunende resources (een opslagaccount en een containerinstantie) maakt, worden de tags doorgegeven aan beide resources. U kunt de tags gebruiken om de resources te identificeren. Een andere manier om deze ondersteunende resources te identificeren, is via hun achtervoegsels, die azscripts bevatten. Zie Implementatiescripts bewaken en problemen oplossen voor meer informatie.

  • identity: Voor implementatiescript-API-versie 2020-10-01 of hoger is een door de gebruiker toegewezen beheerde identiteit optioneel, tenzij u Azure-specifieke acties in het script moet uitvoeren of als u het implementatiescript uitvoert in een privénetwerk. API-versie 2019-10-01-preview vereist een beheerde identiteit omdat de implementatiescriptservice deze gebruikt om de scripts uit te voeren.

    Wanneer u de identity eigenschap opgeeft, roept Connect-AzAccount -Identity de scriptservice aan voordat u het gebruikersscript aanroept. Op dit moment wordt alleen een door de gebruiker toegewezen beheerde identiteit ondersteund. Als u zich wilt aanmelden met een andere identiteit in het implementatiescript, kunt u Connect-AzAccount aanroepen. Zie De minimale machtigingen configureren voor meer informatie.

  • kind: Geef het type script op, of AzurePowerShell AzureCLI. Daarnaast kindmoet u de azPowerShellVersion of azCliVersion eigenschap opgeven.

  • storageAccountSettings: Geef de instellingen op voor het gebruik van een bestaand opslagaccount. Als storageAccountName dit niet is opgegeven, wordt automatisch een opslagaccount gemaakt. Zie Een bestaand opslagaccount gebruiken voor meer informatie.

  • containerSettings: Pas de naam van de Azure-containerinstantie aan. Zie Een containerinstantie configureren verderop in dit artikel voor meer informatie over het configureren van de groepsnaam van de container. Zie Access a private virtual network voor informatie over het configureren subnetIds van het implementatiescript in een particulier netwerk.

  • environmentVariables: Geef de omgevingsvariabelen op die moeten worden doorgegeven aan het script.

  • azPowerShellVersion/azCliVersion: Geef de moduleversie op die moet worden gebruikt.

    Bekijk een lijst met ondersteunde Azure CLI-versies.

    Belangrijk

    Het implementatiescript maakt gebruik van de beschikbare CLI-installatiekopieën uit Microsoft-artefactregister. Het duurt doorgaans ongeveer één maand om een CLI-installatiekopieën voor een implementatiescript te certificeren. Gebruik geen CLI-versies die in de afgelopen 30 dagen zijn uitgebracht. Raadpleeg de releaseopmerkingen van Azure CLI om de releasedatums voor de installatiekopieën te vinden. Als u een niet-ondersteunde versie gebruikt, worden in het foutbericht de ondersteunde versies vermeld.

  • arguments: Geef de parameterwaarden op. De waarden worden gescheiden door een spatie.

    Het implementatiescript splitst de argumenten in een matrix met tekenreeksen door de aanroep van het CommandLineToArgvW-systeem aan te roepen. Deze stap is nodig omdat de argumenten worden doorgegeven als een opdrachteigenschap aan Azure Container Instances en de opdrachteigenschap een matrix met tekenreeksen is.

    Als de argumenten escape-tekens bevatten, moet u de tekens dubbel escapen. In de vorige bicep-syntaxis van het vorige voorbeeld is -name \"John Dole\"het argument bijvoorbeeld . De escape-tekenreeks is -name \\"John Dole\\".

    Als u een Bicep-parameter van het type object als argument wilt doorgeven, converteert u het object naar een tekenreeks met behulp van de functie string() en gebruikt u vervolgens de functie replace() om aanhalingstekens (") te vervangen door dubbele escaped aanhalingstekens (\\"). Voorbeeld:

    replace(string(parameters('tables')), '"', '\\"')

    Zie het Bicep-voorbeeldbestand voor meer informatie.

  • scriptContent: Geef de scriptinhoud op. Het kan een inlinescript of een extern scriptbestand zijn dat u hebt geïmporteerd met behulp van de functie loadTextContent . Zie Inline versus extern bestand verderop in dit artikel voor meer informatie. Als u een extern script wilt uitvoeren, gebruikt primaryScriptUri u in plaats daarvan.

  • primaryScriptUri: Geef een openbaar toegankelijke URL op naar het primaire implementatiescript met ondersteunde bestandsextensies. Zie Externe scripts verderop in dit artikel gebruiken voor meer informatie.

  • supportingScriptUris: Geef een matrix van openbaar toegankelijke URL's op voor ondersteunende bestanden die worden aangeroepen in of scriptContent primaryScriptUri. Zie Inline versus extern bestand verderop in dit artikel voor meer informatie.

  • timeout: Geef de maximale toegestane tijd op voor het uitvoeren van scripts, in ISO 8601-indeling. De standaardwaarde is P1D.

  • forceUpdateTag: Als u deze waarde wijzigt tussen bicep-bestandsimplementaties, wordt het implementatiescript opnieuw uitgevoerd. Als u de newGuid() of utcNow() functie gebruikt, kunt u deze alleen gebruiken in de standaardwaarde voor een parameter. Zie Een script meer dan één keer uitvoeren verderop in dit artikel voor meer informatie.

  • cleanupPreference. Geef de voorkeur op voor het opschonen van de twee ondersteunende implementatieresources (het opslagaccount en de containerinstantie) wanneer de uitvoering van het script in een terminalstatus terechtkomt. De standaardinstelling is Always, die het verwijderen van ondersteunende resources aanroept, ongeacht de terminalstatus (Succeeded, Failedof Canceled). Zie Resources voor implementatiescripts opschonen verderop in dit artikel voor meer informatie.

  • retentionInterval: Geef het interval op waarvoor de service de implementatiescriptresource behoudt nadat de uitvoering van het implementatiescript een terminalstatus heeft bereikt. De implementatiescriptresource wordt verwijderd wanneer deze duur verloopt. De duur is gebaseerd op het ISO 8601-patroon. Het bewaarinterval ligt tussen 1 uur (PT1H) en 26 uur (PT26H). U gebruikt deze eigenschap wanneer cleanupPreference deze is ingesteld op OnExpiration. Zie Resources voor implementatiescripts opschonen verderop in dit artikel voor meer informatie.

Meer voorbeelden

  • Voorbeeld 1: Een sleutelkluis maken en een implementatiescript gebruiken om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 2: Maak een resourcegroep op abonnementsniveau, maak een sleutelkluis in de resourcegroep en gebruik vervolgens een implementatiescript om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 3: Maak een door de gebruiker toegewezen beheerde identiteit, wijs de rol inzender toe aan de identiteit op het niveau van de resourcegroep, maak een sleutelkluis en gebruik vervolgens een implementatiescript om een certificaat toe te wijzen aan de sleutelkluis.
  • Voorbeeld 4: Maak handmatig een door de gebruiker toegewezen beheerde identiteit en wijs deze machtiging toe om de Microsoft Graph API te gebruiken om Microsoft Entra-toepassingen te maken. Gebruik in het Bicep-bestand een implementatiescript om een Microsoft Entra-toepassing en service-principal te maken en om de object-id's en client-id uit te voeren.

Inline versus extern bestand

Een implementatiescript kan zich in een Bicep-bestand bevinden of u kunt het extern opslaan als een afzonderlijk bestand.

Een inlinescript gebruiken

In het volgende Bicep-bestand ziet u hoe u een inlinescript gebruikt.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

Neem set -e op in uw script om direct afsluiten in te schakelen als een opdracht een niet-nulstatus retourneert. Deze procedure stroomlijnt foutopsporingsprocessen.

Een scriptbestand laden

Gebruik de functie loadTextContent om een scriptbestand op te halen als een tekenreeks. Met deze functie kunt u het script in een extern bestand onderhouden en openen als een implementatiescript. Het pad dat is opgegeven voor het scriptbestand, is relatief ten opzichte van het Bicep-bestand.

U kunt het inlinescript uit het voorgaande Bicep-bestand uitpakken in een hello.sh-bestand en het bestand vervolgens in een submap met de naam scripts plaatsen.

output="Hello $1"
echo $output

Vervolgens kunt u het voorgaande Bicep-bestand aanpassen, zoals in het volgende voorbeeld:

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

Externe scripts gebruiken

U kunt externe scriptbestanden gebruiken in plaats van inlinescripts. Alleen primaire PowerShell-scripts met de extensie .ps1 worden ondersteund. Voor CLI-scripts kunnen primaire scripts alle geldige Bash-scriptextensies bevatten of helemaal geen extensie hebben. Als u externe scriptbestanden wilt gebruiken, wisselt u met scriptContent primaryScriptUri.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

De externe scriptbestanden moeten toegankelijk zijn. U kunt uw scriptbestanden die zijn opgeslagen in Azure-opslagaccounts beveiligen door een SAS-token (Shared Access Signature) te genereren en op te nemen in de URI voor de sjabloon. Stel de vervaldatum in om voldoende tijd te geven om de implementatie te voltooien. Zie Een persoonlijke ARM-sjabloon implementeren met een SAS-token voor meer informatie.

U bent verantwoordelijk voor de integriteit van het script waarnaar het implementatiescript verwijst (of primaryScriptUri supportingScriptUris). Verwijs alleen naar scripts die u vertrouwt.

Ondersteunende scripts gebruiken

U kunt ingewikkelde logica scheiden in een of meer ondersteunende scriptbestanden. Gebruik de supportingScriptUris eigenschap om zo nodig een matrix met URI's op te geven voor de ondersteunende scriptbestanden.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

U kunt ondersteunende scriptbestanden aanroepen vanuit zowel inlinescripts als primaire scriptbestanden. Ondersteunende scriptbestanden hebben geen beperkingen voor de bestandsextensie.

De ondersteunende bestanden worden tijdens runtime gekopieerd naar azscripts/azscriptinput . Gebruik een relatief pad om te verwijzen naar de ondersteunende bestanden van inlinescripts en primaire scriptbestanden.

Toegang tot Azure-resources

Voor toegang tot Azure-resources moet u het identity element configureren. Het volgende Bicep-bestand laat zien hoe u een lijst met Azure-sleutelkluizen ophaalt. Het verlenen van de machtiging voor het beheer van gebruikerstoewijzingen voor toegang tot de sleutelkluis is ook nodig.

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Notitie

Aanmeldingslogica voor Azure is nu ingebouwd in het wrapper-script. Als u machtigingen verleent in hetzelfde Bicep-bestand als uw implementatiescripts, probeert de implementatiescriptservice zich tien minuten (met intervallen van tien seconden) opnieuw aan te melden totdat de roltoewijzing van de beheerde identiteit wordt gerepliceerd.

Werken met uitvoer

De aanpak voor het verwerken van uitvoer varieert op basis van het type script dat u gebruikt: de Azure CLI of Azure PowerShell.

Het Azure CLI-implementatiescript maakt gebruik van een omgevingsvariabele met de naam AZ_SCRIPTS_OUTPUT_PATH om de locatie van het bestand voor scriptuitvoer aan te geven. Wanneer u een implementatiescript uitvoert in een Bicep-bestand, configureert de Bash-shell deze omgevingsvariabele automatisch voor u. De vooraf gedefinieerde waarde wordt ingesteld als /mnt/azscripts/azscriptoutput/scriptoutputs.json.

De uitvoer moet voldoen aan een geldige JSON-tekenreeksobjectstructuur. De inhoud van het bestand moet worden opgemaakt als sleutel-waardepaar. Sla bijvoorbeeld een matrix met tekenreeksen op als { "MyResult": [ "foo", "bar"] }. Het opslaan van alleen de matrixresultaten, zoals [ "foo", "bar" ], is ongeldig.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

In het voorgaande voorbeeld wordt jq gebruikt voor het maken van uitvoer. Het hulpprogramma jq wordt geleverd met de containerinstallatiekopieën. Zie Een ontwikkelomgeving configureren voor meer informatie.

Omgevingsvariabelen gebruiken

Beveiligde tekenreeksen doorgeven aan een implementatiescript

U kunt omgevingsvariabelen (EnvironmentVariable) instellen in uw containerinstanties om dynamische configuratie te bieden van de toepassing of het script dat door de container wordt uitgevoerd. Een implementatiescript verwerkt niet-beveiligde en beveiligde omgevingsvariabelen op dezelfde manier als Azure Container Instances. Zie Omgevingsvariabelen instellen in containerinstanties voor meer informatie.

De maximale toegestane grootte voor omgevingsvariabelen is 64 kB.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

Door het systeem gedefinieerde omgevingsvariabelen

De volgende tabel bevat de door het systeem gedefinieerde omgevingsvariabelen:

Omgevingsvariabele Standaardwaarde (CLI) Standaardwaarde (PowerShell) Systeem gereserveerd
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud AzureCloud Nee
AZ_SCRIPTS_CLEANUP_PREFERENCE Always Always Nr.
AZ_SCRIPTS_OUTPUT_PATH /mnt/azscripts/azscriptoutput/scriptoutputs.json Niet van toepassing Ja
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput Niet van toepassing Ja
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput Niet van toepassing Ja
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME userscript.sh userscript.ps1 Ja
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config primaryscripturi.config Ja
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config supportingscripturi.config Ja
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json scriptoutputs.json Ja
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json executionresult.json Ja
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY Niet van toepassing Niet van toepassing Nee

Zie Werken met uitvoer eerder in dit artikel voor een voorbeeld van het gebruikAZ_SCRIPTS_OUTPUT_PATH.

Gebruik de volgende code om toegang te krijgen tot de omgevingsvariabelen.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

Een bestaand opslagaccount gebruiken

U hebt een opslagaccount en een containerinstantie nodig om het script uit te voeren en problemen op te lossen. U kunt een bestaand opslagaccount aanwijzen of de scriptservice zowel het opslagaccount als het containerexemplaren automatisch laten maken.

Dit zijn de vereisten voor het gebruik van een bestaand opslagaccount:

  • De volgende tabel bevat de ondersteunde accounttypen. De kolom voor lagen verwijst naar de waarde van de -SkuName of --sku parameter. De kolom voor ondersteunde typen verwijst naar de -Kind of --kind parameter.

    Laag Ondersteund type
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Deze combinaties ondersteunen bestandsshares. Zie Een Azure-bestandsshare en typen opslagaccounts maken voor meer informatie.

  • Firewallregels voor opslagaccounts worden nog niet ondersteund. Raadpleeg Firewalls en virtuele netwerken voor Azure Storage configureren voor meer informatie.

  • De implementatie-principal moet machtigingen hebben voor het beheren van het opslagaccount, waaronder het lezen, maken en verwijderen van bestandsshares. Zie De minimale machtigingen configureren voor meer informatie.

  • De allowSharedKeyAccess eigenschap van het opslagaccount moet worden ingesteld op true. De enige manier om een opslagaccount te koppelen in Azure Container Instance (ACI) is via een toegangssleutel.

Als u een bestaand opslagaccount wilt opgeven, voegt u de volgende Bicep-code toe aan het eigenschapselement van Microsoft.Resources/deploymentScripts:

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Zie Syntaxis eerder in dit artikel voor een volledig Microsoft.Resources/deploymentScripts definitievoorbeeld.

Wanneer u een bestaand opslagaccount gebruikt, maakt de scriptservice een bestandsshare met een unieke naam. Zie Resources voor implementatiescripts verderop in dit artikel voor meer informatie over hoe de scriptservice de bestandsshare opschoont.

Een containerinstantie configureren

Voor een implementatiescript is een nieuwe Azure-containerinstantie vereist. U kunt geen bestaande containerinstantie opgeven. U kunt de groepsnaam van de container echter aanpassen met behulp van containerGroupName. Als u geen groepsnaam opgeeft, wordt deze automatisch gegenereerd. Er zijn aanvullende configuraties vereist voor het maken van dit containerexemplaren. Zie De minimale machtigingen configureren voor meer informatie.

U kunt ook waarden opgeven subnetId voor het uitvoeren van het implementatiescript in een particulier netwerk. Zie Access a private virtual network (Toegang tot een virtueel particulier netwerk) voor meer informatie.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Een script meer dan één keer uitvoeren

De uitvoering van het implementatiescript is een idempotente bewerking. Als er geen wijzigingen zijn in een van de deploymentScripts resource-eigenschappen, inclusief het inlinescript, wordt het script niet uitgevoerd wanneer u het Bicep-bestand opnieuw implementeert.

De implementatiescriptservice vergelijkt de resourcenamen in het Bicep-bestand met de bestaande resources in dezelfde resourcegroep. Er zijn twee opties als u hetzelfde implementatiescript meerdere keren wilt uitvoeren:

  • Wijzig de naam van uw deploymentScripts resource. Gebruik bijvoorbeeld de functie utcNow als de resourcenaam of als onderdeel van de resourcenaam. U kunt de utcNow functie alleen gebruiken in de standaardwaarde voor een parameter.

    Als u de resourcenaam wijzigt, wordt er een nieuwe deploymentScripts resource gemaakt. Het is goed om een geschiedenis van het uitvoeren van scripts bij te houden.

  • Geef een andere waarde op in de forceUpdateTag eigenschap. Gebruik bijvoorbeeld utcNow als waarde.

Schrijf implementatiescripts om idempotentie te garanderen, dus onbedoeld opnieuw uitvoeren leidt niet tot systeemwijzigingen. Wanneer u bijvoorbeeld een Azure-resource maakt via het implementatiescript, valideert u de afwezigheid voordat u het maakt om ervoor te zorgen dat het script slaagt of het maken van redundante resources voorkomt.

Microsoft Graph gebruiken binnen een implementatiescript

Een implementatiescript kan Microsoft Graph gebruiken om objecten in Microsoft Entra-id te maken en ermee te werken.

Opdracht

Wanneer u Azure CLI-implementatiescripts gebruikt, kunt u opdrachten in de az ad opdrachtgroep gebruiken om te werken met toepassingen, service-principals, groepen en gebruikers. U kunt ook rechtstreeks Microsoft Graph API's aanroepen met behulp van de az rest opdracht.

Wanneer u Azure PowerShell-implementatiescripts gebruikt, kunt u de Invoke-RestMethod cmdlet gebruiken om de Microsoft Graph-API's rechtstreeks aan te roepen.

Machtigingen

De identiteit die door uw implementatiescript wordt gebruikt, moet worden geautoriseerd om te werken met de Microsoft Graph API, met de juiste machtigingen voor de bewerkingen die worden uitgevoerd. U moet de identiteit buiten uw Bicep-bestand autoriseren, bijvoorbeeld door een door de gebruiker toegewezen beheerde identiteit vooraf te maken en deze toe te wijzen aan een app-rol voor Microsoft Graph. Zie dit snelstartvoorbeeld voor meer informatie.

Resources voor implementatiescripts opschonen

De twee automatisch gemaakte ondersteunende resources kunnen de deploymentScript resource nooit overleven, tenzij ze door fouten worden verwijderd. De cleanupPreference eigenschap bepaalt de levenscyclus van de ondersteunende resources. De retentionInterval eigenschap bepaalt de levenscyclus van de deploymentScript resource. U kunt deze eigenschappen als volgt gebruiken:

  • cleanupPreference: Geef de opschoningsvoorkeur op van de twee ondersteunende resources wanneer de scriptuitvoering een terminalstatus krijgt. De ondersteunde waarden zijn:

    • Always: Verwijder de twee ondersteunende resources nadat de uitvoering van het script een terminalstatus heeft. Als u een bestaand opslagaccount gebruikt, verwijdert de scriptservice de bestandsshare die door de service is gemaakt. Omdat de deploymentScripts resource nog steeds aanwezig is nadat de ondersteunende resources zijn opgeschoond, blijft de scriptservice de resultaten van de uitvoering van het script behouden (bijvoorbeeld stdout), uitvoer en retourwaarde voordat de resources worden verwijderd.

    • OnSuccess: Verwijder de twee ondersteunende resources alleen wanneer de uitvoering van het script is geslaagd. Als u een bestaand opslagaccount gebruikt, verwijdert de scriptservice de bestandsshare alleen wanneer de uitvoering van het script is geslaagd.

      Als de uitvoering van het script niet lukt, wacht de scriptservice totdat de retentionInterval waarde verloopt voordat de ondersteunende resources worden opgeschoond en vervolgens de implementatiescriptresource.

    • OnExpiration: Verwijder de twee ondersteunende resources alleen wanneer de retentionInterval instelling is verlopen. Als u een bestaand opslagaccount gebruikt, verwijdert de scriptservice de bestandsshare, maar behoudt het opslagaccount.

    Het containerexemplaren en het opslagaccount worden verwijderd op basis van de cleanupPreference waarde. Als het script echter mislukt en cleanupPreference niet is ingesteld Alwaysop, wordt de container automatisch gedurende één uur uitgevoerd door het implementatieproces of totdat de container is opgeschoond. U kunt de tijd gebruiken om problemen met het script op te lossen.

    Als u de container na geslaagde implementaties actief wilt houden, voegt u een slaapstandstap toe aan uw script. Voeg bijvoorbeeld Start-Sleep toe aan het einde van uw script. Als u de slaapstandstap niet toevoegt, wordt de container ingesteld op een terminalstatus en kan deze niet worden geopend, zelfs niet als u deze nog niet hebt verwijderd.

  • retentionInterval: Geef het tijdsinterval op dat een deploymentScript resource wordt bewaard voordat deze is verlopen en verwijderd.

Notitie

We raden u niet aan het opslagaccount en het containerexemplaren te gebruiken dat de scriptservice voor andere doeleinden genereert. De twee resources kunnen worden verwijderd, afhankelijk van de levenscyclus van het script.

Volgende stappen

In dit artikel hebt u geleerd hoe u resources voor implementatiescripts maakt. Zie voor meer informatie:

Implementatiescripts gebruiken in Bicep