Uso dell'estensione script personalizzata di Azure con macchine virtuali LinuxUsing the Azure Custom Script Extension with Linux Virtual Machines

L'estensione script personalizzata scarica ed esegue script sulle macchine virtuali di Azure.The Custom Script Extension downloads and executes scripts on Azure virtual machines. Questa estensione è utile per la configurazione post-distribuzione, l'installazione di software o qualsiasi altra attività di configurazione o gestione.This extension is useful for post deployment configuration, software installation, or any other configuration / management task. Gli script possono essere scaricati dall'archiviazione di Azure, o da un altro percorso Internet accessibile, oppure possono essere forniti al runtime dell'estensione.Scripts can be downloaded from Azure storage or other accessible internet location, or provided to the extension run time. L'estensione script personalizzata è integrabile nei modelli di Azure Resource Manager e può essere eseguita anche tramite l'interfaccia della riga di comando di Azure, PowerShell, il portale di Azure o l'API REST di Macchine virtuali di Azure.The Custom Script extension integrates with Azure Resource Manager templates, and can also be run using the Azure CLI, PowerShell, Azure portal, or the Azure Virtual Machine REST API.

Questo documento descrive come usare l'estensione script personalizzata dall'interfaccia della riga di comando di Azure, e da un modello di Azure Resource Manager, e inoltre illustra i passaggi per la risoluzione dei problemi nei sistemi Linux.This document details how to use the Custom Script Extension from the Azure CLI, and an Azure Resource Manager template, and also details troubleshooting steps on Linux systems.

Configurazione dell'estensioneExtension Configuration

La configurazione dell'estensione script personalizzata specifica informazioni come il percorso dello script e il comando da eseguire.The Custom Script Extension configuration specifies things like script location and the command to be run. Questa configurazione può essere archiviata nei file di configurazione, specificata sulla riga di comando o definita in un modello di Azure Resource Manager.This configuration can be stored in configuration files, specified on the command line, or in an Azure Resource Manager template. I dati sensibili possono essere archiviati in una configurazione protetta, che verrà crittografata e decrittografata solo all'interno della macchina virtuale.Sensitive data can be stored in a protected configuration, which is encrypted and only decrypted inside the virtual machine. La configurazione protetta è utile quando il comando di esecuzione include segreti, ad esempio una password.The protected configuration is useful when the execution command includes secrets such as a password.

Configurazione pubblicaPublic Configuration

Schema:Schema:

Nota: questi nomi di proprietà fanno distinzione tra maiuscole e minuscole.Note - these property names are case sensitive. Usare i nomi come sono riportati sotto per evitare problemi di distribuzione.Use the names as seen below to avoid deployment issues.

  • commandToExecute: (obbligatorio, stringa) script del punto di ingresso da eseguire.commandToExecute: (required, string) the entry point script to execute
  • fileUris: (facoltativo, matrice di stringhe) URL relativi ai file da scaricare.fileUris: (optional, string array) the URLs for files to be downloaded.
  • timestamp : (facoltativo, intero) usare questo campo solo per attivare una nuova esecuzione dello script modificando il valore del campo.timestamp (optional, integer) use this field only to trigger a rerun of the script by changing value of this field.
{
  "fileUris": ["<url>"],
  "commandToExecute": "<command-to-execute>"
}

Configurazione protettaProtected Configuration

Schema:Schema:

Nota: questi nomi di proprietà fanno distinzione tra maiuscole e minuscole.Note - these property names are case sensitive. Usare i nomi come sono riportati sotto per evitare problemi di distribuzione.Use the names as seen below to avoid deployment issues.

  • commandToExecute: (facoltativo, stringa) script del punto di ingresso da eseguire.commandToExecute: (optional, string) the entry point script to execute. Usare in alternativa questo campo se il comando contiene segreti, ad esempio password.Use this field instead if your command contains secrets such as passwords.
  • storageAccountName: (facoltativo, stringa) nome dell'account di archiviazione.storageAccountName: (optional, string) the name of storage account. Se si specificano credenziali di archiviazione, tutti i valori di fileUris devono essere URL relativi a BLOB di Azure.If you specify storage credentials, all fileUris must be URLs for Azure Blobs.
  • storageAccountKey: (facoltativo, stringa) chiave di accesso dell'account di archiviazione.storageAccountKey: (optional, string) the access key of storage account.
{
  "commandToExecute": "<command-to-execute>",
  "storageAccountName": "<storage-account-name>",
  "storageAccountKey": "<storage-account-key>"
}

Interfaccia della riga di comando di AzureAzure CLI

Quando si usa l'interfaccia della riga di comando di Azure per eseguire l'estensione script personalizzata, creare uno o più file di configurazione contenenti almeno il relativo URI e il comando di esecuzione dello script.When using the Azure CLI to run the Custom Script Extension, create a configuration file or files containing at minimum the file uri, and the script execution command.

az vm extension set --resource-group myResourceGroup --vm-name myVM --name customScript --publisher Microsoft.Azure.Extensions --settings ./script-config.json

Le impostazioni possono essere specificate facoltativamente nel comando come una stringa in formato JSON.Optionally the settings can be specified in the command as a JSON formatted string. Ciò consente di specificare la configurazione durante l'esecuzione e senza un file di configurazione separato.This allows the configuration to be specified during execution and without a separate configuration file.

az vm extension set '
  --resource-group exttest `
  --vm-name exttest `
  --name customScript `
  --publisher Microsoft.Azure.Extensions `
  --settings '{"fileUris": ["https://raw.githubusercontent.com/neilpeterson/test-extension/master/test.sh"],"commandToExecute": "./test.sh"}'

Esempi di interfaccia della riga di comando di AzureAzure CLI Examples

Esempio 1 : configurazione pubblica con file di script.Example 1 - Public configuration with script file.

{
  "fileUris": ["https://raw.githubusercontent.com/neilpeterson/test-extension/master/test.sh"],
  "commandToExecute": "./test.sh"
}

Comando dell'interfaccia della riga di comando di Azure:Azure CLI command:

az vm extension set --resource-group myResourceGroup --vm-name myVM --name customScript --publisher Microsoft.Azure.Extensions --settings ./script-config.json

Esempio 2 : configurazione pubblica senza file di script.Example 2 - Public configuration with no script file.

{
  "commandToExecute": "apt-get -y update && apt-get install -y apache2"
}

Comando dell'interfaccia della riga di comando di Azure:Azure CLI command:

az vm extension set --resource-group myResourceGroup --vm-name myVM --name customScript --publisher Microsoft.Azure.Extensions --settings ./script-config.json

Esempio 3 : vengono usati un file di configurazione pubblica per specificare l'URI del file di script e un file di configurazione protetta per specificare il comando da eseguire.Example 3 - A public configuration file is used to specify the script file URI, and a protected configuration file is used to specify the command to be executed.

File di configurazione pubblica:Public configuration file:

{
  "fileUris": ["https://gist.github.com/ahmetalpbalkan/b5d4a856fe15464015ae87d5587a4439/raw/466f5c30507c990a4d5a2f5c79f901fa89a80841/hello.sh"]
}

File di configurazione protetta:Protected configuration file:

{
  "commandToExecute": "./hello.sh <password>"
}

Comando dell'interfaccia della riga di comando di Azure:Azure CLI command:

az vm extension set --resource-group myResourceGroup --vm-name myVM --name customScript --publisher Microsoft.Azure.Extensions --settings ./script-config.json --protected-settings ./protected-config.json

Modello di Resource ManagerResource Manager Template

L'estensione script personalizzata di Azure può essere eseguita durante la fase di distribuzione della macchina virtuale usando un modello di Resource Manager.The Azure Custom Script Extension can be run at Virtual Machine deployment time using a Resource Manager template. A tale scopo, aggiungere una risorsa JSON formattata correttamente al modello di distribuzione.To do so, add properly formatted JSON to the deployment template.

Esempi di Resource ManagerResource Manager Examples

Esempio 1 : configurazione pubblica.Example 1 - public configuration.

{
    "name": "scriptextensiondemo",
    "type": "extensions",
    "location": "[resourceGroup().location]",
    "apiVersion": "2015-06-15",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', parameters('scriptextensiondemoName'))]"
    ],
    "tags": {
        "displayName": "scriptextensiondemo"
    },
    "properties": {
        "publisher": "Microsoft.Azure.Extensions",
        "type": "CustomScript",
        "typeHandlerVersion": "2.0",
        "autoUpgradeMinorVersion": true,
      "settings": {
        "fileUris": [
          "https://gist.github.com/ahmetalpbalkan/b5d4a856fe15464015ae87d5587a4439/raw/466f5c30507c990a4d5a2f5c79f901fa89a80841/hello.sh"
        ],
        "commandToExecute": "sh hello.sh"
      }
    }
}

Esempio 2 : comando di esecuzione nella configurazione protetta.Example 2 - execution command in protected configuration.

{
  "name": "config-app",
  "type": "extensions",
  "location": "[resourceGroup().location]",
  "apiVersion": "2015-06-15",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.0",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "fileUris": [
        "https://gist.github.com/ahmetalpbalkan/b5d4a856fe15464015ae87d5587a4439/raw/466f5c30507c990a4d5a2f5c79f901fa89a80841/hello.sh"
      ]              
    },
    "protectedSettings": {
      "commandToExecute": "sh hello.sh <password>"
    }
  }
}

Per un esempio completo, vedere la demo di .NET Core Music Store: Demo di Music Store.See the .Net Core Music Store Demo for a complete example - Music Store Demo.

Risoluzione dei problemiTroubleshooting

Quando viene eseguita l'estensione script personalizzata, lo script viene creato o scaricato in una directory simile all'esempio seguente.When the Custom Script Extension runs, the script is created or downloaded into a directory similar to the following example. Anche l'output del comando viene salvato in questa directory, nei file stdout e stderr.The command output is also saved into this directory in stdout and stderr file.

/var/lib/waagent/custom-script/download/0/

L'estensione script di Azure genera un log che è possibile trovare nella directory seguente.The Azure Script Extension produces a log, which can be found here.

/var/log/azure/custom-script/handler.log

Lo stato dell'esecuzione dell'estensione script personalizzata può essere recuperato anche con l'interfaccia della riga di comando di Azure.The execution state of the Custom Script Extension can also be retrieved with the Azure CLI.

az vm extension list -g myResourceGroup --vm-name myVM

L'output ha un aspetto simile al testo seguente:The output looks like the following text:

info:    Executing command vm extension get
+ Looking up the VM "scripttst001"
data:    Publisher                   Name                                      Version  State
data:    --------------------------  ----------------------------------------  -------  ---------
data:    Microsoft.Azure.Extensions  CustomScript                              2.0      Succeeded
data:    Microsoft.OSTCExtensions    Microsoft.Insights.VMDiagnosticsSettings  2.3      Succeeded
info:    vm extension get command OK

Passaggi successiviNext Steps

Per informazioni su altre estensioni script delle macchine virtuali, vedere Panoramica sulle estensioni script di Azure per Linux.For information on other VM Script Extensions, see Azure Script Extension overview for Linux.