Estensione script personalizzata per Windows
L'estensione per script personalizzati scarica ed esegue script in macchine virtuali di Azure. Usare questa estensione per la configurazione post-distribuzione, l'installazione del software o qualsiasi altra attività di configurazione o gestione. È possibile scaricare gli script da Archiviazione di Azure o GitHub oppure fornirli al portale di Azure in fase di esecuzione dell'estensione.
L'estensione per script personalizzati è integrabile con i modelli di Azure Resource Manager. È anche possibile eseguirlo usando l'interfaccia della riga di comando di Azure, Azure PowerShell, il portale di Azure o l'API REST di Azure Macchine virtuali.
Questo articolo descrive come usare l'estensione per script personalizzati usando il modulo Azure PowerShell e i modelli di Azure Resource Manager. Fornisce anche i passaggi per la risoluzione dei problemi per i sistemi Windows.
Prerequisiti
Nota
Non usare l'estensione per script personalizzati per l'esecuzione Update-AzVM
con la stessa macchina virtuale del relativo parametro. L'estensione attenderà se stessa.
Sistemi operativi Windows supportati
Sistema operativo Windows | x64 |
---|---|
Windows 10 | Supportata |
Windows 11 | Supportata |
Windows Server 2008 SP2 | Supportata |
Windows Server 2008 R2 | Supportata |
Windows Server 2012 | Supportata |
Windows Server 2012 R2 | Supportata |
Windows Server 2016 | Supportata |
Windows Server 2016 Core | Supportata |
Windows Server 2019 | Supportata |
Windows Server 2019 Core | Supportata |
Windows Server 2022 | Supportata |
Windows Server 2022 Core | Supportata |
Posizione degli script
È possibile impostare l'estensione per utilizzare le credenziali di Archiviazione BLOB di Azure per accedere ad Archiviazione BLOB di Azure. La posizione dello script può essere ovunque, purché la macchina virtuale sia in grado di connettersi con l'endpoint, ad esempio GitHub o un file server interno.
Connettività Internet
Per scaricare uno script dall'esterno, ad esempio da GitHub o Archiviazione di Azure, è necessario aprire altri firewall o porte NSG del gruppo di sicurezza di rete. Ad esempio, se lo script si trova in Archiviazione di Azure, è possibile consentire l'accesso utilizzando i tag del servizio Azure NSG per Archiviazione.
L'estensione script personalizzata non ha alcun modo per ignorare la convalida del certificato. Se si esegue il download da un percorso protetto con, ad esempio, un certificato autofirmato, è possibile che si verifichino errori come Il certificato remoto non è valido in base alla procedura di convalida. Assicurarsi che il certificato sia installato correttamente nell'archivio Autorità di certificazione radice attendibili nella macchina virtuale.
Se lo script si trova su un server locale, potrebbe essere necessario aprire altri firewall o porte NSG.
Suggerimenti
- L'output è limitato agli ultimi 4096 byte.
- Il carattere di escape corretto consente di garantire che le stringhe vengano analizzate correttamente. Ad esempio, sono sempre necessarie due barre rovesciata per eseguire l'escape di una singola barra rovesciata letterale quando si gestiscono i percorsi dei file. Esempio:
{"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
- La frequenza di errore più elevata per questa estensione è dovuta a errori di sintassi nello script. Verificare che lo script funzioni senza errori. Inserire un maggior numero di registrazioni nello script per rendere più facile l'individuazione dei problemi.
- Scrivere script idempotenti, in modo che la loro esecuzione accidentale non causi modifiche al sistema.
- Controllare che gli script non richiedano l'input dell'utente durante l'esecuzione.
- Il tempo di esecuzione dello script è di 90 minuti. Una durata superiore comporta il fallimento della fornitura dell'estensione.
- Non inserire riavvio all'interno dello script. Questa azione causa problemi con altre estensioni in fase di installazione e l'estensione non continua dopo il riavvio.
- Se si utilizza uno script che causa un riavvio prima di installare le applicazioni e di eseguire lo script, pianificare il riavvio utilizzando Task Scheduler di Windows o strumenti come DSC, Chef o le estensioni di Puppet.
- Non eseguire uno script che provochi l'arresto o l'aggiornamento di Agente macchina virtuale. Potrebbe lasciare l'estensione in uno stato di transizione e portare a un time-out.
- L'estensione esegue lo script una sola volta. Se si desidera eseguire uno script a ogni avvio, utilizzare l'estensione per creare una task pianificata di Windows.
- Se si desidera programmare l'esecuzione di uno script, utilizzare l'estensione per creare una task pianificata di Windows.
- Quando lo script è in esecuzione, lo stato dell'estensione in transizione viene visualizzato solo dal portale Azure o dalla CLI di Azure. Se si desiderano aggiornamenti di stato più frequenti per uno script in esecuzione, creare la propria soluzione.
- L'estensione Script personalizzato non supporta nativamente i server proxy. Tuttavia, è possibile utilizzare uno strumento di trasferimento di file, come Invoke-WebRequest, che supporta i server proxy all'interno dello script.
- Tenere presente le posizioni delle directory non predefinite su cui potrebbero fare affidamento gli script o i comandi. e includere la logica necessaria per gestirli.
- L'estensione Script personalizzato viene eseguita sotto l'
LocalSystem
account. - Se si vogliono utilizzare le
storageAccountName
proprietà,storageAccountKey
queste devono essere collocateprotectedSettings
. - È possibile avere una sola versione dell'estensione sulla macchina virtuale. Per eseguire un secondo script personalizzato, è possibile aggiornare l'estensione esistente con una nuova configurazione. In alternativa, è possibile rimuovere l'estensione Script personalizzato e riapplicarla con lo script aggiornato.
Schema dell'estensione
La configurazione dell'estensione script personalizzata specifica informazioni come il percorso dello script e il comando da eseguire. È possibile archiviare queste informazioni in file di configurazione, specificarle sulla riga di comando o definirle in un modello di Azure Resource Manager.
È possibile archiviare i dati sensibili in una configurazione protetta, crittografata e decrittografata solo all'interno della macchina virtuale. La configurazione protetta è utile quando il comando di esecuzione include segreti, ad esempio una password o un riferimento a un file di firma di accesso condiviso. Ecco un esempio:
{
"apiVersion": "2018-06-01",
"type": "Microsoft.Compute/virtualMachines/extensions",
"name": "virtualMachineName/config-app",
"location": "[resourceGroup().location]",
"dependsOn": [
"[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
"[variables('musicstoresqlName')]"
],
"tags": {
"displayName": "config-app"
},
"properties": {
"publisher": "Microsoft.Compute",
"type": "CustomScriptExtension",
"typeHandlerVersion": "1.10",
"autoUpgradeMinorVersion": true,
"settings": {
"timestamp":123456789
},
"protectedSettings": {
"commandToExecute": "myExecutionCommand",
"storageAccountName": "myStorageAccountName",
"storageAccountKey": "myStorageAccountKey",
"managedIdentity" : {},
"fileUris": [
"script location"
]
}
}
}
Nota
La managedIdentity
proprietà non deve essere utilizzata insieme alla storageAccountName
proprietà o storageAccountKey
.
È possibile installare una sola versione di un'estensione in una macchina virtuale alla volta. La specifica di uno script personalizzato due volte nello stesso modello di Azure Resource Manager per la stessa macchina virtuale ha esito negativo.
È possibile usare questo schema all'interno della risorsa macchina virtuale o come risorsa autonoma. Se questa estensione viene usata come risorsa autonoma nel modello di Azure Resource Manager, il nome della risorsa deve essere nel formato virtualMachineName/extensionName.
Valori delle proprietà
Nome | Valore o esempio | Tipo di dati |
---|---|---|
apiVersion | 2015-06-15 |
data |
publisher | Microsoft.Compute |
string |
type | CustomScriptExtension |
string |
typeHandlerVersion | 1.10 |
int |
fileUris | https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 |
array |
timestamp | 123456789 |
Intero a 32 bit |
commandToExecute | powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 |
string |
storageAccountName | examplestorageacct |
string |
storageAccountKey | TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== |
string |
managedIdentity | { } o { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } o { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } |
Oggetto JSON |
Nota
Questi nomi di proprietà fanno distinzione tra maiuscole e minuscole. Per evitare problemi nella distribuzione, usare i nomi come indicato di seguito.
Dettagli sui valori delle proprietà
Le impostazioni pubbliche vengono inviate in testo non crittografato alla macchina virtuale in cui viene eseguito lo script. Le impostazioni protette vengono crittografate tramite una chiave nota solo per Azure e per la macchina virtuale. Le impostazioni vengono salvate nella macchina virtuale man mano che sono state inviate. Ovvero, se le impostazioni sono state crittografate, vengono salvate crittografate nella macchina virtuale. Il certificato usato per decrittografare i valori crittografati viene archiviato nella macchina virtuale. Il certificato viene usato anche per decrittografare le impostazioni, se necessario, in fase di esecuzione.
L'uso delle impostazioni pubbliche può essere utile per il debug, ma è consigliabile usare le impostazioni protette.
È possibile impostare i valori seguenti in impostazioni pubbliche o protette. L'estensione rifiuta qualsiasi configurazione in cui questi valori vengono impostati in impostazioni pubbliche e protette.
commandToExecute
fileUris
Proprietà: managedIdentity
Nota
Questa proprietà deve essere specificata solo nelle impostazioni protette.
L'estensione per script personalizzati, versione 1.10 e successive, supporta le identità gestite per scaricare i file dagli URL forniti nell'impostazione fileUris
. La proprietà consente all'estensione per script personalizzati di accedere Archiviazione di Azure BLOB o contenitori privati senza che l'utente deve passare segreti come token di firma di accesso condiviso o chiavi dell'account di archiviazione.
Per usare questa funzionalità, aggiungere un'identità assegnata dal sistema o assegnata dall'utente alla macchina virtuale o al set di scalabilità di macchine virtuali in cui viene eseguita l'estensione di script personalizzata. Concedere quindi all'identità gestita l'accesso al contenitore o al BLOB Archiviazione di Azure.
Per usare l'identità assegnata dal sistema nella macchina virtuale di destinazione o nel set di scalabilità di macchine virtuali, impostare su managedidentity
un oggetto JSON vuoto.
{
"fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
"commandToExecute": "powershell.exe script1.ps1",
"managedIdentity" : {}
}
Per usare l'identità assegnata dall'utente nella macchina virtuale di destinazione o nel set di scalabilità di macchine virtuali, configurare managedidentity
con l'ID client o l'ID oggetto dell'identità gestita.
{
"fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
"commandToExecute": "powershell.exe script1.ps1",
"managedIdentity" : { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }
}
{
"fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
"commandToExecute": "powershell.exe script1.ps1",
"managedIdentity" : { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }
}
Nota
La managedIdentity
proprietà non deve essere utilizzata insieme alla storageAccountName
proprietà o storageAccountKey
.
Distribuzione modelli
È possibile distribuire le estensioni di macchine virtuali di Azure usando i modelli di Azure Resource Manager. Lo schema JSON descritto nella sezione precedente può essere usato in un modello di Azure Resource Manager per eseguire l'estensione script personalizzato durante la distribuzione del modello. Gli esempi seguenti illustrano come usare l'estensione per script personalizzati:
- Distribuire estensioni macchina virtuale con modelli di Azure Resource Manager
- Distribuire un'applicazione a due livelli in Windows e database SQL di Azure
Distribuzione PowerShell
È possibile usare il Set-AzVMCustomScriptExtension
comando per aggiungere l'estensione script personalizzato a una macchina virtuale esistente. Per altre informazioni, vedere Set-AzVMCustomScriptExtension.
Set-AzVMCustomScriptExtension -ResourceGroupName <resourceGroupName> `
-VMName <vmName> `
-Location myLocation `
-FileUri <fileUrl> `
-Run 'myScript.ps1' `
-Name DemoScriptExtension
Esempi
Uso di più script
In questo esempio vengono usati tre script per compilare il server. La commandToExecute
proprietà chiama il primo script. Si hanno quindi opzioni su come vengono chiamati gli altri. Ad esempio, è possibile avere uno script lead che controlla l'esecuzione, con la corretta gestione degli errori, registrazione e gestione dello stato. Gli script vengono scaricati nel computer locale per l'esecuzione.
Ad esempio, in 1_Add_Tools.ps1 chiamare 2_Add_Features.ps1 aggiungendo .\2_Add_Features.ps1
allo script. Ripetere questo processo per gli altri script definiti in $settings
.
$fileUri = @("https://xxxxxxx.blob.core.windows.net/buildServer1/1_Add_Tools.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/2_Add_Features.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/3_CompleteInstall.ps1")
$settings = @{"fileUris" = $fileUri};
$storageAcctName = "xxxxxxx"
$storageKey = "1234ABCD"
$protectedSettings = @{"storageAccountName" = $storageAcctName; "storageAccountKey" = $storageKey; "commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File 1_Add_Tools.ps1"};
#run command
Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
-Location <locationName> `
-VMName <vmName> `
-Name "buildserver1" `
-Publisher "Microsoft.Compute" `
-ExtensionType "CustomScriptExtension" `
-TypeHandlerVersion "1.10" `
-Settings $settings `
-ProtectedSettings $protectedSettings;
Esecuzione di script da una condivisione locale
In questo esempio potrebbe essere necessario usare un server SMB (Server Message Block) locale per il percorso dello script. Non è quindi necessario specificare altre impostazioni, ad eccezione commandToExecute
di .
$protectedSettings = @{"commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File \\filesvr\build\serverUpdate1.ps1"};
Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
-Location <locationName> `
-VMName <vmName> `
-Name "serverUpdate"
-Publisher "Microsoft.Compute" `
-ExtensionType "CustomScriptExtension" `
-TypeHandlerVersion "1.10" `
-ProtectedSettings $protectedSettings
Esecuzione di uno script personalizzato più volte usando l'interfaccia della riga di comando
Il gestore dell'estensione script personalizzato impedisce di riesecure uno script se sono state passate le stesse impostazioni. Questo comportamento impedisce l'esecuzione accidentale, che potrebbe causare comportamenti imprevisti se lo script non è idempotente. Per verificare se il gestore ha bloccato la riesecuzione, esaminare C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*
. Ricerca di un avviso simile al seguente:
Current sequence number, <SequenceNumber>, is not greater than the sequence number
of the most recently executed configuration. Exiting...
Se si vuole eseguire l'estensione script personalizzata più di una volta, è possibile farlo solo in queste condizioni:
- Il parametro dell'estensione
Name
è uguale alla distribuzione precedente dell'estensione. - La configurazione è stata aggiornata. È possibile aggiungere una proprietà dinamica al comando, ad esempio un timestamp. Se il gestore rileva una modifica nelle impostazioni di configurazione, considera tale modifica come un desiderio esplicito di rieseguire lo script.
In alternativa, è possibile impostare la proprietà ForceUpdateTag su true
.
Uso di Invoke-WebRequest
Se si usa Invoke-WebRequest nello script, è necessario specificare il parametro -UseBasicParsing
. Se non si specifica il parametro , viene visualizzato l'errore seguente durante il controllo dello stato dettagliato:
The response content cannot be parsed because the Internet Explorer engine
is not available, or Internet Explorer's first-launch configuration
is not complete. Specify the UseBasicParsing parameter and try again.
Set di scalabilità di macchine virtuali
Se si distribuisce l'estensione script personalizzata dal portale di Azure, non si ha il controllo sulla scadenza del token di firma di accesso condiviso per l'accesso allo script nell'account di archiviazione. La distribuzione iniziale funziona, ma quando scade il token di firma di accesso condiviso dell'account di archiviazione, qualsiasi operazione di ridimensionamento successiva ha esito negativo perché l'estensione per script personalizzati non può più accedere all'account di archiviazione.
È consigliabile usare PowerShell, l'interfaccia della riga di comando di Azure o un modello di Azure Resource Manager quando si distribuisce l'estensione script personalizzata in un set di scalabilità di macchine virtuali. In questo modo, è possibile scegliere di usare un'identità gestita o di avere il controllo diretto della scadenza del token di firma di accesso condiviso per l'accesso allo script nell'account di archiviazione, purché sia necessario.
Risoluzione dei problemi e supporto
È possibile recuperare i dati sullo stato delle distribuzioni di estensioni dal portale di Azure e usando il modulo Azure PowerShell. Per visualizzare lo stato di distribuzione delle estensioni per una macchina virtuale, eseguire il comando seguente:
Get-AzVMExtension -ResourceGroupName <resourceGroupName> `
-VMName <vmName> -Name myExtensionName
L'output dell'estensione viene registrato nei file presenti nella cartella seguente nella macchina virtuale di destinazione:
C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension
I file specificati vengono scaricati nella cartella seguente nella macchina virtuale di destinazione:
C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>
Nel percorso precedente è <n>
un numero intero decimale che potrebbe cambiare tra le esecuzioni dell'estensione. Il valore 1.*
corrisponde al valore effettivo attuale typeHandlerVersion
dell'estensione. Ad esempio, la directory effettiva potrebbe essere C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2
.
Quando si esegue il commandToExecute
comando , l'estensione imposta questa directory, ad esempio , ...\Downloads\2
come directory di lavoro corrente. Questo processo consente l'uso di percorsi relativi per individuare i file scaricati tramite la fileURIs
proprietà . Ecco alcuni esempi di file scaricati:
URI in fileUris |
Percorso di download relativo | Percorso di download assoluto |
---|---|---|
https://someAcct.blob.core.windows.net/aContainer/scripts/myscript.ps1 |
./scripts/myscript.ps1 |
C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\scripts\myscript.ps1 |
https://someAcct.blob.core.windows.net/aContainer/topLevel.ps1 |
./topLevel.ps1 |
C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\topLevel.ps1 |
I percorsi di directory assoluti cambiano per tutta la durata della macchina virtuale, ma non all'interno di una singola esecuzione dell'estensione script personalizzata.
Poiché il percorso di download assoluto può variare nel tempo, è preferibile scegliere percorsi di script/file relativi nella commandToExecute
stringa, quando possibile. Ad esempio:
"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""
Le informazioni sul percorso dopo il primo segmento URI vengono mantenute per i file scaricati usando l'elenco delle fileUris
proprietà. Come illustrato nella tabella precedente, i file scaricati vengono mappati nelle sottodirectory di download per riflettere la struttura dei fileUris
valori.
Supporto tecnico
Per assistenza in qualsiasi parte di questo articolo, contattare gli esperti di Azure nel supporto della community di Azure.
Per inviare un evento imprevisto supporto tecnico di Azure, passare al sito supporto tecnico di Azure e selezionare Ottieni supporto.
Per informazioni sull'uso del supporto di Azure, leggere le Domande frequenti sul supporto tecnico di Azure.