Che cosa sono gli script di distribuzione?

  • 5 minuti

In questa unità si apprenderà come la risorsa può estendere i deploymentScripts modelli di Azure Resource Manager (ARM).

I modelli di ARM sono risorse straordinarie. È possibile usarli per dichiarare lo stato desiderato dell'infrastruttura cloud e indicare alle API e ai servizi come ottenerlo. In alcuni casi, tuttavia, è necessario eseguire azioni non previste da Azure Resource Manager.

Che cosa sono gli script di distribuzione?

Le risorse deploymentScripts sono script di PowerShell o Bash che vengono eseguiti in un contenitore Docker come parte della distribuzione del modello. Le immagini del contenitore predefinite hanno disponibile Azure CLI o Azure PowerShell. Questi script vengono eseguiti durante l'elaborazione del modello di ARM, quindi è possibile aggiungere un comportamento personalizzato al processo di distribuzione.

Gli script di distribuzione usano un'identità gestita per l'autenticazione in Azure. Un'identità gestita è un'entità di servizio la cui credenziale e ciclo di vita sono gestiti dalla piattaforma Azure. Questa identità è quella usata dai comandi di Azure PowerShell o dell'interfaccia della riga di comando di Azure per agire sull'ambiente. Poiché è l'utente che assegna l'identità, controlla anche l'ambito degli elementi su cui può influire una risorsa deploymentScripts.

La risorsa deploymentScripts produce un output che può essere usato da altre risorse nella distribuzione. È quindi possibile cercare informazioni in un sistema esterno o fornire dati in base allo stato corrente dell'ambiente per influire sul resto della distribuzione.

Come funzionano gli script di distribuzione

Una risorsa deploymentScripts accetta uno script fornito dall'utente (dal modello o tramite URI) ed eventualmente alcuni script di supporto, quindi li esegue in un'istanza di contenitore di Azure. A tale istanza di contenitore viene assegnata l'identità gestita specificata. Gli script e il relativo output vengono archiviati in una condivisione file per un account di archiviazione di Azure.

Quando viene eseguita, la distribuzione del modello controlla se è presente una risorsa deploymentScripts esistente nel gruppo di risorse di destinazione. In caso affermativo, confronta le proprietà. Se tutto corrisponde, non succede nulla di nuovo. Se la risorsa non esiste o è stata modificata, Azure Resource Manager crea una nuova istanza del contenitore ed esegue gli script di distribuzione all'interno di tale istanza del contenitore. Qualsiasi output definito viene passato di nuovo ad Azure Resource Manager per usarlo più avanti nella distribuzione.

Struttura degli script di distribuzione

Per aggiungere un comportamento personalizzato a un modello di ARM, si inizia con la risorsa deploymentScripts. Come minimo, è necessario fornire dettagli comuni come:

  • Un oggetto name per la risorsa deploymentScripts.
  • I valori di type e apiVersion.
  • La posizione (location valore) in cui vengono create le risorse di supporto.
  • Un oggetto properties vuoto. Ciò verrà illustrato tra poco.

Sono necessari due valori specifici di deploymentScripts:

  • kind: il tipo di script da eseguire (AzurePowerShell o 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: l'identità gestita utilizzata dall'istanza del contenitore. È possibile creare l'identità gestita in anticipo e specificarla come nell'esempio seguente. In alternativa, è possibile crearlo nel modello e farvi riferimento, che è quello che si esegue nell'esercizio successivo.

    {
  "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': {}
    }
  }
}

Dopo aver impostato tali elementi, è possibile passare alla sezione properties della risorsa deploymentScripts. La parte principale della properties sezione è , scriptContentche specifica lo script effettivo da eseguire:

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

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

Si noti che scriptContent usa una stringa su più righe. In Bicep è possibile specificare una stringa su più righe usando tre virgolette (''') prima e dopo.

È comune che uno script di distribuzione passi gli output alla distribuzione. Ad esempio, se si usa uno script per cercare alcune informazioni in un'API, è possibile passare tali informazioni alla distribuzione come output. Altre risorse della distribuzione potrebbero quindi usare le informazioni nelle proprie definizioni.

Per uno script di PowerShell, si passano gli output creando una variabile denominata $DeploymentScriptOutputs, che deve essere una tabella hash. Lo script di esempio inizializza la tabella hash e quindi crea un output denominato text, che ne accetta il valore dalla variabile locale $output:

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

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

Suggerimento

È anche possibile scrivere script di distribuzione in Bash. Per creare output da uno script Bash, è necessario creare un file JSON in una posizione specificata dalla variabile di ambiente AZ_SCRIPTS_OUTPUT_PATH.

All'interno della sezione properties si definiscono anche le varie opzioni che possono essere accettate da deploymentScripts. In questo modulo viene mantenuto semplice e basta aggiungere abbastanza per ottenere l'esecuzione dello script. Come minimo, è necessario specificare la versione di Azure PowerShell o dell'interfaccia della riga di comando di Azure da usare, uno script da eseguire e un intervallo di conservazione.

L'intervallo di conservazione è il periodo in cui dovranno conservati i risultati se si vogliono mantenere le risorse. Per impostazione predefinita, i risultati vengono rimossi dopo l'esecuzione dello script.

"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'
}

Il modello completo sarà simile al seguente:

{
  "$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

Includi file di script

L'incorporamento di script inline nei modelli può essere complesso, difficile da leggere e comprendere e difficile da modificare. Bicep usa la funzione loadTextContent() per incorporare un file di testo esterno nella distribuzione. Quando Bicep esegue il transpile del modello in JSON, incorpora il file esterno nel modello generato.

Si supponga di avere un file di PowerShell denominato myscript.ps1 nella stessa cartella del modello Bicep. È possibile indicare a Bicep di incorporare il file come segue:

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

È possibile trovare tutte le proprietà per la risorsa deploymentScripts nella documentazione di riferimento del modello di ARM.