Wat zijn implementatiescripts?

  • 5 minuten

In deze les leert u hoe de deploymentScripts resource ARM-sjablonen (Azure Resource Manager) kan uitbreiden.

ARM-sjablonen zijn geweldige dingen. U kunt ze gebruiken om de gewenste status van uw cloudinfrastructuur te declareren en de API's en services te laten achterhalen hoe u daar komt. Af en toe moet u echter acties uitvoeren die buiten de mogelijkheden van Azure Resource Manager vallen.

Wat zijn implementatiescripts?

deploymentScripts resources zijn PowerShell- of Bash-scripts die worden uitgevoerd in een Docker-container als onderdeel van uw sjabloonimplementatie. De standaardcontainerinstallatiekopieën hebben de Azure CLI of Azure PowerShell beschikbaar. Deze scripts worden uitgevoerd tijdens de verwerking van arm-sjablonen, zodat u aangepast gedrag kunt toevoegen aan het implementatieproces.

Implementatiescripts gebruiken een beheerde identiteit om te verifiëren bij Azure. Een beheerde identiteit is een service-principal waarvan de referenties en levenscyclus worden beheerd door het Azure-platform. Deze identiteit is wat de Azure PowerShell- of Azure CLI-opdrachten gebruiken om op de omgeving te reageren. Omdat u de identiteit toewijst, bepaalt u het bereik van wat een deploymentScripts resource kan beïnvloeden.

De deploymentScripts resource produceert uitvoer die andere resources in de implementatie kunnen gebruiken. U kunt vervolgens informatie opzoeken uit een extern systeem of gegevens opgeven op basis van de huidige status van uw omgeving om de rest van de implementatie te beïnvloeden.

Hoe implementatiescripts werken

Een deploymentScripts resource gebruikt een door de gebruiker verstrekt script (van de sjabloon of van de URI) en mogelijk enkele ondersteunende scripts en voert deze uit in een Azure-containerinstantie. Aan die containerinstantie wordt de beheerde identiteit toegewezen die u opgeeft. De scripts en hun uitvoer worden opgeslagen in een bestandsshare voor een Azure-opslagaccount.

Wanneer de sjabloonimplementatie wordt uitgevoerd, wordt gecontroleerd of er een bestaande deploymentScripts resource in de doelresourcegroep aanwezig is. Zo ja, dan worden de eigenschappen vergeleken. Als alles overeenkomt, gebeurt er niets nieuws. Als de resource niet bestaat of is gewijzigd, maakt Azure Resource Manager een nieuw containerexemplaren en voert u de implementatiescripts in die containerinstantie uit. Gedefinieerde uitvoer wordt teruggegeven aan Azure Resource Manager voor later gebruik in de implementatie.

Implementatiescriptstructuur

Als u een aangepast gedrag wilt toevoegen aan een ARM-sjabloon, begint u met de deploymentScripts resource. U moet minimaal algemene gegevens opgeven, zoals:

  • Een name voor de deploymentScripts resource.
  • De type en apiVersion waarden.
  • De locatie (location waarde) waar de ondersteunende resources worden gemaakt.
  • Een leeg properties object. Daar kom je zo snel bij.

Er zijn twee deploymentScriptsspecifieke waarden vereist:

  • kind: het type script dat moet worden uitgevoerd ( AzurePowerShell of AzureCLI).

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

    resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

  • identity: De beheerde identiteit die door het containerexemplaren wordt gebruikt. U kunt de beheerde identiteit van tevoren maken en deze opgeven zoals in het volgende voorbeeld, of u kunt deze maken in de sjabloon en ernaar verwijzen (wat u in de volgende oefening gaat doen).

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

    resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

Nadat u deze elementen hebt ingesteld, kunt u naar de properties sectie van de deploymentScripts resource gaan. Het belangrijkste deel hiervan is het scriptContent, dat het werkelijke script aangeeft dat moet worden uitgevoerd:

"properties": {
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
}

properties: {
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
}

U ziet dat er scriptContent een tekenreeks met meerdere regels wordt gebruikt. In Bicep kunt u een tekenreeks met meerdere regels opgeven door drie aanhalingstekens samen (''') voor en na de tekenreeks te gebruiken.

Het is gebruikelijk dat een implementatiescript uitvoer teruggeeft aan de implementatie. Als u bijvoorbeeld een script gebruikt om bepaalde gegevens uit een API op te zoeken, kunt u de informatie als uitvoer doorgeven aan de implementatie. Andere resources in de implementatie kunnen vervolgens de informatie in hun eigen definities gebruiken.

Voor een PowerShell-script geeft u uitvoer terug door een variabele te maken met de naam $DeploymentScriptOutputs, die een hash-tabel moet zijn. Het voorbeeldscript initialiseert de hash-tabel en maakt vervolgens een uitvoer met de naam text, die de waarde van de $output lokale variabele haalt:

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

Tip

U kunt ook implementatiescripts schrijven in Bash. Als u uitvoer van een Bash-script wilt maken, moet u een JSON-bestand maken op een locatie die is opgegeven door de AZ_SCRIPTS_OUTPUT_PATH omgevingsvariabele.

In de properties sectie definieert u ook de verschillende opties die deploymentScripts u kunt nemen. In deze module houden we het eenvoudig en voegen we net genoeg toe om het script uit te voeren. U moet minimaal de versie van Azure PowerShell of de Azure CLI opgeven die moet worden gebruikt, een script dat moet worden uitgevoerd en een bewaarperiode.

Het bewaarinterval is hoe lang de resultaten moeten worden bewaard als u de resources wilt behouden. De resultaten worden standaard verwijderd nadat u het script hebt uitgevoerd.

"properties": {
  "azPowerShellVersion": "3.0",
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
  "retentionInterval": "P1D"
}

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
  retentionInterval: 'P1D'
}

Onze volledige sjabloon ziet er ongeveer als volgt uit:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.1",
  "apiProfile": "",
  "parameters": {},
  "variables": {},
  "functions": [],
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "myFirstDeploymentScript",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
        }
      },
      "properties": {
        "azPowerShellVersion": "3.0",
        "scriptContent": "
            $output = 'Hello Learner!'
            Write-Output $output
            $DeploymentScriptOutputs = @{}
            $DeploymentScriptOutputs['text'] = $output
        ",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "scriptResult": {
      "type": "string",
      "value": "[reference('myFirstDeploymentScript').outputs.text]"
    }
  }
}

resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
  properties: {
    azPowerShellVersion: '3.0'
    scriptContent: '''
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output scriptResult string = myFirstDeploymentScript.properties.outputs.text

Scriptbestanden opnemen

Het insluiten van scripts inline in sjablonen kan lastig zijn, moeilijk te lezen en te begrijpen en moeilijk te wijzigen. Bicep gebruikt de loadTextContent() functie om een extern tekstbestand in te sluiten in uw implementatie. Wanneer Bicep uw sjabloon transpileert in JSON, wordt het externe bestand ingesloten in de sjabloon die wordt verzonden.

Stel dat u een PowerShell-bestand met de naam myscript.ps1 hebt in dezelfde map als uw Bicep-sjabloon. U kunt Bicep laten weten het bestand als volgt in te sluiten:

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: loadTextContent('myscript.ps1')
  retentionInterval: 'P1D'
}

U vindt alle eigenschappen voor de deploymentScripts resource in de referentiedocumentatie voor ARM-sjablonen.