Verwenden von Version 2 der Azure-Erweiterung für benutzerdefinierte Skripts mit virtuellen Linux-ComputernUse the Azure Custom Script Extension Version 2 with Linux virtual machines

Version 2 der Erweiterung für benutzerdefinierte Skripts lädt Skripts auf virtuelle Azure-Computer herunter und führt sie dort aus.The Custom Script Extension Version 2 downloads and runs scripts on Azure virtual machines. Diese Erweiterung ist hilfreich bei der Konfiguration nach der Bereitstellung, bei der Softwareinstallation oder bei anderen Konfigurations-/Verwaltungsaufgaben.This extension is useful for post-deployment configuration, software installation, or any other configuration/management task. Sie können Skripts von Azure Storage oder einem anderen zugänglichen Speicherort im Internet herunterladen oder sie für die Erweiterungsruntime bereitstellen.You can download scripts from Azure Storage or another accessible internet location, or you can provide them to the extension runtime.

Die Erweiterung für benutzerdefinierte Skripts ist mit Azure Resource Manager-Vorlagen integriert.The Custom Script Extension integrates with Azure Resource Manager templates. Sie können sie auch mithilfe der PowerShell, der Azure-Befehlszeilenschnittstelle oder der Azure Virtual Machines-REST-API ausführen.You can also run it by using Azure CLI, PowerShell, or the Azure Virtual Machines REST API.

In diesem Artikel wird erläutert, wie Sie die Erweiterung für benutzerdefinierte Skripts über die Azure-Befehlszeilenschnittstelle verwenden und die Erweiterung mithilfe einer Azure Resource Manager-Vorlage ausführen.This article details how to use the Custom Script Extension from Azure CLI, and how to run the extension by using an Azure Resource Manager template. Außerdem enthält dieser Artikel Schritte zur Problembehandlung für Linux-Systeme.This article also provides troubleshooting steps for Linux systems.

Die Erweiterung für benutzerdefinierte Linux-Skripts ist in zwei Versionen verfügbar:There are two Linux Custom Script Extensions:

  • Version 1: Microsoft.OSTCExtensions.CustomScriptForLinuxVersion 1 - Microsoft.OSTCExtensions.CustomScriptForLinux
  • Version 2: Microsoft.Azure.Extensions.CustomScriptVersion 2 - Microsoft.Azure.Extensions.CustomScript

Stellen Sie neue und bereits vorhandene Bereitstellungen auf die neue Version 2 um.Please switch new and existing deployments to use the new version 2 instead. Die neue Version ist als direkter Ersatz konzipiert.The new version is intended to be a drop-in replacement. Für die Migration müssen daher lediglich Name und Version geändert werden. Änderungen an der Erweiterungskonfiguration sind nicht erforderlich.Therefore, the migration is as easy as changing the name and version, you do not need to change your extension configuration.

BetriebssystemOperating System

Die Erweiterung für benutzerdefinierte Skripts für Linux wird auf den von Erweiterungen unterstützten Betriebssystemen ausgeführt. Weitere Informationen finden Sie in diesem Artikel.The Custom Script Extension for Linux will run on the extension supported extension OS's, for more information, see this article.

Speicherort des SkriptsScript Location

Mit der Erweiterung können Sie unter Verwendung Ihrer Azure Blob Storage-Anmeldeinformationen auf Azure Blob Storage zugreifen.You can use the extension to use your Azure Blob storage credentials, to access Azure Blob storage. Alternativ kann das Skript an einem beliebigen Ort gespeichert sein, solange der virtuelle Computer ein Routing an diesen Endpunkt (GitHub, interner Dateiserver oder Ähnliches) durchführen kann.Alternatively, the script location can be any where, as long as the VM can route to that end point, such as GitHub, internal file server etc.

InternetverbindungInternet Connectivity

Wenn Sie ein Skript extern herunterladen möchten (etwa im Fall von GitHub oder Azure Storage), müssen zusätzliche Firewall-/Netzwerksicherheitsgruppen-Ports geöffnet werden.If you need to download a script externally such as GitHub or Azure Storage, then additional firewall/Network Security Group ports need to be opened. Wenn sich Ihr Skript also beispielsweise in Azure Storage befindet, können Sie Zugriff über Azure-NSG-Diensttags für Storage gewähren.For example if your script is located in Azure Storage, you can allow access using Azure NSG Service Tags for Storage.

Befindet sich Ihr Skript auf einem lokalen Server, müssen gegebenenfalls noch weitere Firewall-/Netzwerksicherheitsgruppen-Ports geöffnet werden.If your script is on a local server, then you may still need additional firewall/Network Security Group ports need to be opened.

Tipps und TricksTips and Tricks

  • Die meisten Fehler für diese Erweiterung sind auf Syntaxfehler im Skript zurückzuführen. Vergewissern Sie sich, dass das Skript fehlerfrei ausgeführt wird, und versehen Sie es zusätzlich mit einer Protokollierung, um die Fehlersuche zu erleichtern.The highest failure rate for this extension is due to syntax errors in the script, test the script runs without error, and also put in additional logging into the script to make it easier to find where it failed.
  • Schreiben Sie idempotente Skripts, um Systemänderungen zu vermeiden, wenn das Skript versehentlich mehrmals ausgeführt wird.Write scripts that are idempotent, so if they get run again more than once accidentally, it will not cause system changes.
  • Stellen Sie sicher, dass während der Skriptausführung keine Benutzereingaben erforderlich sind.Ensure the scripts do not require user input when they run.
  • Die Skriptausführung darf maximal 90 Minuten dauern. Danach gilt die Bereitstellung der Erweiterung als nicht erfolgreich.There is 90 mins allowed for the script to run, anything longer will result in a failed provision of the extension.
  • Das Skript darf keine Systemneustarts enthalten, da diese zu Problemen mit anderen Erweiterungen führen, die installiert werden. Außerdem wird die Erweiterung nach dem Neustart nicht fortgesetzt.Do not put reboots inside the script, this will cause issues with other extensions that are being installed, and post reboot, the extension will not continue after the restart.
  • Wenn Sie über ein Skript verfügen, das einen Neustart des Systems bewirkt, installieren Sie Anwendungen, und führen Sie Skripts usw. aus. Planen Sie den Neustart des Systems mithilfe eines Cron-Auftrags oder mit einem Tool wie DSC oder Chef oder mit Puppet-Erweiterungen.If you have a script that will cause a reboot, then install applications and run scripts etc. You should schedule the reboot using a Cron job, or using tools such as DSC, or Chef, Puppet extensions.
  • Die Erweiterung führt jedes Skript nur einmal aus. Soll ein Skript bei jedem Neustart des Systems ausgeführt werden, können Sie cloud-init image und ein Modul vom Typ Scripts Per Boot (Skripts pro Boot) verwenden.The extension will only run a script once, if you want to run a script on every boot, then you can use cloud-init image and use a Scripts Per Boot module. Alternativ können Sie mithilfe des Skripts eine systemd-Diensteinheit erstellen.Alternatively, you can use the script to create a SystemD service unit.
  • Wenn Sie den Ausführungszeitpunkt eines Skripts planen möchten, erstellen Sie mithilfe der Erweiterung einen Cron-Auftrag.If you want to schedule when a script will run, you should use the extension to create a Cron job.
  • Während der Skriptausführung wird im Azure-Portal sowie in der CLI nur ein Übergangsstatus für die Erweiterung angezeigt.When the script is running, you will only see a 'transitioning' extension status from the Azure portal or CLI. Sollten Sie häufigere Statusaktualisierungen für ein ausgeführtes Skript benötigen, müssen Sie eine eigene Lösung erstellen.If you want more frequent status updates of a running script, you will need to create your own solution.
  • Die Erweiterung für benutzerdefinierte Skripts verfügt über keine native Proxyserverunterstützung. Sie können innerhalb Ihres Skripts jedoch ein Dateiübertragungstool mit Proxyserverunterstützung verwenden (beispielsweise cURL).Custom Script extension does not natively support proxy servers, however you can use a file transfer tool that supports proxy servers within your script, such as Curl.
  • Achten Sie auf nicht standardmäßige Verzeichnispfade, von denen Ihre Skripts oder Befehle gegebenenfalls abhängen, und verwenden Sie eine entsprechende Logik, um diese zu behandeln.Be aware of non default directory locations that your scripts or commands may rely on, have logic to handle this.
  • Beim Bereitstellen eines benutzerdefinierten Skripts für VMSS-Produktionsinstanzen wird empfohlen, eine JSON-Vorlage zu verwenden und das Skriptspeicherkonto zu speichern, in dem Sie Kontrolle über das SAS-Token haben.When deploying custom script to production VMSS instances it is suggested to deploy via json template and store your script storage account where you have control over the SAS token.

ErweiterungsschemaExtension schema

In der Konfiguration der benutzerdefinierten Skripterweiterung werden Aspekte wie der Skriptspeicherort und der auszuführende Befehl angegeben.The Custom Script Extension configuration specifies things like script location and the command to be run. Sie können diese Konfiguration in Konfigurationsdateien speichern oder sie in der Befehlszeile oder in einer Azure Resource Manager-Vorlage angeben.You can store this configuration in configuration files, specify it on the command line, or specify it in an Azure Resource Manager template.

Sie können sensible Daten in einer geschützten Konfiguration speichern. Diese ist verschlüsselt und wird nur auf dem virtuellen Computer entschlüsselt.You can store sensitive data in a protected configuration, which is encrypted and only decrypted inside the virtual machine. Die geschützte Konfiguration ist hilfreich, wenn der Ausführungsbefehl vertrauliche Informationen (beispielsweise ein Kennwort) enthält.The protected configuration is useful when the execution command includes secrets such as a password.

Diese Elemente müssen als vertrauliche Daten behandelt und in der Konfiguration mit den geschützten Einstellungen der Erweiterung angegeben werden.These items should be treated as sensitive data and specified in the extensions protected setting configuration. Die geschützten Einstellungsdaten der Azure-VM-Erweiterung werden verschlüsselt und nur auf dem virtuellen Zielcomputer entschlüsselt.Azure VM extension protected setting data is encrypted, and only decrypted on the target virtual machine.

{
  "name": "config-app",
  "type": "Extensions",
  "location": "[resourceGroup().location]",
  "apiVersion": "2019-03-01",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "skipDos2Unix":false,
      "timestamp":123456789          
    },
    "protectedSettings": {
       "commandToExecute": "<command-to-execute>",
       "script": "<base64-script-to-execute>",
       "storageAccountName": "<storage-account-name>",
       "storageAccountKey": "<storage-account-key>",
       "fileUris": ["https://.."],
       "managedIdentity" : "<managed-identity-identifier>"
    }
  }
}

Hinweis

Die managedIdentity-Eigenschaft darf nicht in Verbindung mit den Eigenschaften storageAccountName oder storageAccountKey verwendet werden.managedIdentity property must not be used in conjunction with storageAccountName or storageAccountKey properties

EigenschaftswerteProperty values

NameName Wert/BeispielValue / Example DatentypData Type
apiVersionapiVersion 2019-03-012019-03-01 datedate
publisherpublisher Microsoft.Compute.ExtensionsMicrosoft.Compute.Extensions Zeichenfolgestring
typetype CustomScriptCustomScript Zeichenfolgestring
typeHandlerVersiontypeHandlerVersion 2.12.1 INTint
fileUris (Beispiel)fileUris (e.g) https://github.com/MyProject/Archive/MyPythonScript.py arrayarray
commandToExecute (Beispiel)commandToExecute (e.g) python MyPythonScript.py <my-param1>python MyPythonScript.py <my-param1> Zeichenfolgestring
scriptscript IyEvYmluL3NoCmVjaG8gIlVwZGF0aW5nIHBhY2thZ2VzIC4uLiIKYXB0IHVwZGF0ZQphcHQgdXBncmFkZSAteQo=IyEvYmluL3NoCmVjaG8gIlVwZGF0aW5nIHBhY2thZ2VzIC4uLiIKYXB0IHVwZGF0ZQphcHQgdXBncmFkZSAteQo= Zeichenfolgestring
skipDos2Unix (Beispiel)skipDos2Unix (e.g) falsefalse booleanboolean
timestamp (Beispiel)timestamp (e.g) 123456789123456789 32-bit integer32-bit integer
storageAccountName (Beispiel)storageAccountName (e.g) examplestorageacctexamplestorageacct Zeichenfolgestring
storageAccountKey (Beispiel)storageAccountKey (e.g) TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== Zeichenfolgestring
managedIdentity (z. B.)managedIdentity (e.g) { } oder { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } oder { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }{ } or { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } or { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } JSON-Objektjson object

Details zu EigenschaftswertenProperty value details

  • apiVersion: Die aktuelle apiVersion kann über den Ressourcen-Explorer oder über die Azure-Befehlszeilenschnittstelle mit dem Befehl az provider list -o json gefunden werden.apiVersion: The most up to date apiVersion can be found using Resource Explorer or from Azure CLI using the following command az provider list -o json
  • skipDos2Unix (optional, boolesch): Überspringen der dos2unix-Konvertierung von skriptbasierten Datei-URLs oder des Skripts.skipDos2Unix: (optional, boolean) skip dos2unix conversion of script-based file URLs or script.
  • timestamp (optional, 32-Bit-Integer): Durch Ändern dieses Felds können Sie eine erneute Ausführung des Skripts auslösen.timestamp (optional, 32-bit integer) use this field only to trigger a re-run of the script by changing value of this field. Jeder Integerwert ist akzeptabel; er muss sich lediglich vom vorherigen Wert unterscheiden.Any integer value is acceptable; it must only be different than the previous value.
  • commandToExecute (erforderlich, wenn Skript nicht festgelegt; Zeichenfolge): das auszuführende Skript für den Einstiegspunkt.commandToExecute: (required if script not set, string) the entry point script to execute. Verwenden Sie dieses Feld, falls Ihr Befehl vertrauliche Informationen (beispielsweise Kennwörter) enthält.Use this field instead if your command contains secrets such as passwords.
  • script (erforderlich, wenn „commandToExecute“ nicht festgelegt; Zeichenfolge): ein Base64-codiertes (und optional mit Gzip komprimiertes) Skript, das durch „/bin/sh“ ausgeführt wird.script: (required if commandToExecute not set, string)a base64 encoded (and optionally gzip'ed) script executed by /bin/sh.
  • fileUris (optional, Zeichenfolgenarray): die URLs für die herunterzuladenden Dateien.fileUris: (optional, string array) the URLs for file(s) to be downloaded.
  • storageAccountName (optional, Zeichenfolge): der Name des Speicherkontos.storageAccountName: (optional, string) the name of storage account. Wenn Sie Speicheranmeldeinformationen angeben, muss es sich bei allen fileUris um URLs für Azure-Blobs handeln.If you specify storage credentials, all fileUris must be URLs for Azure Blobs.
  • storageAccountKey (optional, Zeichenfolge): der Zugriffsschlüssel des Speicherkontos.storageAccountKey: (optional, string) the access key of storage account
  • managedIdentity (optional, JSON-Objekt): die verwaltete Identität zum Herunterladen von DateienmanagedIdentity: (optional, json object) the managed identity for downloading file(s)
    • clientId (optional, Zeichenfolge): die Client-ID der verwalteten IdentitätclientId: (optional, string) the client ID of the managed identity
    • objectId (optional, Zeichenfolge): die Objekt-ID der verwalteten IdentitätobjectId: (optional, string) the object ID of the managed identity

Die folgenden Werte können in öffentlichen oder geschützten Einstellungen festgelegt werden. Die Erweiterung lehnt jedoch jede Konfiguration ab, bei der die Werte sowohl in öffentlichen als auch in geschützten Einstellungen festgelegt sind.The following values can be set in either public or protected settings, the extension will reject any configuration where the values below are set in both public and protected settings.

  • commandToExecute
  • script
  • fileUris

Die Verwendung öffentlicher Einstellungen kann zwar beim Debuggen hilfreich sein, es wird jedoch dringend empfohlen, geschützte Einstellungen zu verwenden.Using public settings maybe useful for debugging, but it is strongly recommended that you use protected settings.

Öffentliche Einstellungen werden in Klartext an den virtuellen Computer gesendet, auf dem das Skript ausgeführt wird.Public settings are sent in clear text to the VM where the script will be executed. Geschützte Einstellungen werden mit einem Schlüssel verschlüsselt, der nur in Azure und auf dem virtuellen Computer bekannt ist.Protected settings are encrypted using a key known only to the Azure and the VM. Die Einstellungen werden unverändert auf dem virtuellen Computer gespeichert. Waren die Einstellungen also verschlüsselt, werden sie auch verschlüsselt auf dem virtuellen Computer gespeichert.The settings are saved to the VM as they were sent, i.e. if the settings were encrypted they are saved encrypted on the VM. Das Zertifikat zum Entschlüsseln der verschlüsselten Werte wird auf dem virtuellen Computer gespeichert und gegebenenfalls zur Laufzeit zum Entschlüsseln der Einstellungen verwendet.The certificate used to decrypt the encrypted values is stored on the VM, and used to decrypt settings (if necessary) at runtime.

Eigenschaft: skipDos2UnixProperty: skipDos2Unix

Der Standardwert lautet „FALSE“, d.h., die dos2unix-Konvertierung wird ausgeführt.The default value is false, which means dos2unix conversion is executed.

Mit der früheren Version von CustomScript, d.h. mit Microsoft.OSTCExtensions.CustomScriptForLinux, wurden DOS-Dateien durch Umwandlung von \r\n in \n automatisch in UNIX-Dateien konvertiert.The previous version of CustomScript, Microsoft.OSTCExtensions.CustomScriptForLinux, would automatically convert DOS files to UNIX files by translating \r\n to \n. Diese Umwandlung ist noch vorhanden und standardmäßig aktiviert.This translation still exists, and is on by default. Die Konvertierung wird basierend auf den folgenden Kriterien auf alle über fileUris heruntergeladenen Dateien oder die Skripteinstellung angewandt.This conversion is applied to all files downloaded from fileUris or the script setting based on any of the following criteria.

  • Wenn die Erweiterung .sh, .txt, .py oder .pl lautet, wird die Konvertierung durchgeführt.If the extension is one of .sh, .txt, .py, or .pl it will be converted. Die Skripteinstellung erfüllt dieses Kriterium immer, da davon ausgegangen wird, dass das Skript durch „/bin/sh“ ausgeführt und unter „script.sh“ auf dem virtuellen Computer gespeichert wird.The script setting will always match this criteria because it is assumed to be a script executed with /bin/sh, and is saved as script.sh on the VM.
  • Wenn die Datei mit #! beginnt.If the file starts with #!.

Die dos2unix-Konvertierung kann übersprungen werden, indem skipDos2Unix auf TRUE festgelegt wird.The dos2unix conversion can be skipped by setting the skipDos2Unix to true.

{
  "fileUris": ["<url>"],
  "commandToExecute": "<command-to-execute>",
  "skipDos2Unix": true
}

Eigenschaft: scriptProperty: script

CustomScript unterstützt die Ausführung eines benutzerdefinierten Skripts.CustomScript supports execution of a user-defined script. In den Skripteinstellungen werden commandToExecute und fileUris in einer einzelnen Einstellung kombiniert.The script settings to combine commandToExecute and fileUris into a single setting. Anstatt eine Datei für den Download von Azure Storage oder dem GitHub Gist einrichten zu müssen, können Sie das Skript einfach als eine Einstellung codieren.Instead of the having to setup a file for download from Azure storage or GitHub gist, you can simply encode the script as a setting. Das Skript kann verwendet werden, um commandToExecute und fileUris zu ersetzen.Script can be used to replaced commandToExecute and fileUris.

Das Skript muss Base64-codiert sein.The script must be base64 encoded. Das Skript kann optional mit Gzip komprimiert werden.The script can optionally be gzip'ed. Die Skripteinstellung kann in öffentlichen oder geschützten Einstellungen verwendet werden.The script setting can be used in public or protected settings. Die Daten des Skriptparameters können eine Größe von maximal 256 KB aufweisen.The maximum size of the script parameter's data is 256 KB. Wenn das Skript diese Größe überschreitet, wird es nicht ausgeführt.If the script exceeds this size it will not be executed.

Beispielsweise wurde das folgende Skript in der Datei „script.sh“ gespeichert.For example, given the following script saved to the file /script.sh/.

#!/bin/sh
echo "Updating packages ..."
apt update
apt upgrade -y

Die richtige CustomScript-Skripteinstellung wird durch Abrufen der Ausgabe des folgenden Befehls erstellt.The correct CustomScript script setting would be constructed by taking the output of the following command.

cat script.sh | base64 -w0
{
  "script": "IyEvYmluL3NoCmVjaG8gIlVwZGF0aW5nIHBhY2thZ2VzIC4uLiIKYXB0IHVwZGF0ZQphcHQgdXBncmFkZSAteQo="
}

Das Skript kann optional mit Gzip komprimiert werden, um die Größe weiter zu verringern (in den meisten Fällen). (CustomScript erkennt die Verwendung der Gzip-Komprimierung automatisch.)(CustomScript auto-detects the use of gzip compression.)

cat script | gzip -9 | base64 -w 0

CustomScript verwendet den folgenden Algorithmus zum Ausführen eines Skripts.CustomScript uses the following algorithm to execute a script.

  1. Bestätigen, dass die Länge des Skriptwerts 256 KB nicht überschreitet.assert the length of the script's value does not exceed 256 KB.
  2. Base64-Decodierung des Skriptwertsbase64 decode the script's value
  3. Versuchen, für den Base64-decodierten Wert den Befehl „gunzip“ auszuführenattempt to gunzip the base64 decoded value
  4. Schreiben des decodierten (und optional dekomprimierten) Werts auf den Datenträger („/var/lib/waagent/custom-script/#/script.sh“)write the decoded (and optionally decompressed) value to disk (/var/lib/waagent/custom-script/#/script.sh)
  5. Ausführen des Skripts unter Verwendung von „_/bin/sh -c /var/lib/waagent/custom-script/#/script.sh“execute the script using _/bin/sh -c /var/lib/waagent/custom-script/#/script.sh.

Eigenschaft: managedIdentityProperty: managedIdentity

Hinweis

Diese Eigenschaft muss nur in geschützten Einstellungen angegeben werden.This property must be specified in protected settings only.

CustomScript (ab Version 2.1) unterstützt verwaltete Identitäten zum Herunterladen von Dateien von URLs, die in der Einstellung „fileUris“ angegeben werden.CustomScript (version 2.1 onwards) supports managed identity for downloading file(s) from URLs provided in the "fileUris" setting. So kann CustomScript auf private Azure Storage-Blobs oder -Container zugreifen, ohne dass der Benutzer Geheimnisse wie SAS-Token oder Speicherkontoschlüssel übergeben muss.It allows CustomScript to access Azure Storage private blobs or containers without the user having to pass secrets like SAS tokens or storage account keys.

Um diese Funktion verwenden zu können, muss der Benutzer der VM oder VMSS, auf der CustomScript ausgeführt werden soll, eine vom System zugewiesene oder vom Benutzer zugewiesene Identität hinzufügen und der verwalteten Identität Zugriff auf den Azure Storage-Container oder das -Blob gewähren.To use this feature, the user must add a system-assigned or user-assigned identity to the VM or VMSS where CustomScript is expected to run, and grant the managed identity access to the Azure Storage container or blob.

Um die vom System zugewiesene Identität für die Ziel-VM/VMSS zu verwenden, legen Sie das Feld „managedidentity“ auf ein leeres JSON-Objekt fest.To use the system-assigned identity on the target VM/VMSS, set "managedidentity" field to an empty json object.

Beispiel:Example:

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : {}
}

Um die vom Benutzer zugewiesene Identität für die Ziel-VM/VMSS zu verwenden, konfigurieren Sie das Feld „managedidentity“ mit der Client-ID oder der Objekt-ID der verwalteten Identität.To use the user-assigned identity on the target VM/VMSS, configure "managedidentity" field with the client ID or the object ID of the managed identity.

Beispiele:Examples:

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }
}
{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.sh"],
  "commandToExecute": "sh script1.sh",
  "managedIdentity" : { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }
}

Hinweis

Die managedIdentity-Eigenschaft darf nicht in Verbindung mit den Eigenschaften storageAccountName oder storageAccountKey verwendet werden.managedIdentity property must not be used in conjunction with storageAccountName or storageAccountKey properties

Bereitstellung von VorlagenTemplate deployment

Azure-VM-Erweiterungen können mithilfe von Azure Resource Manager-Vorlagen bereitgestellt werden.Azure VM extensions can be deployed with Azure Resource Manager templates. Das im vorherigen Abschnitt erläuterte JSON-Schema kann in einer Azure Resource Manager-Vorlage zum Ausführen der benutzerdefinierten Skripterweiterung im Rahmen einer Azure Resource Manager-Bereitstellung verwendet werden.The JSON schema detailed in the previous section can be used in an Azure Resource Manager template to run the Custom Script Extension during an Azure Resource Manager template deployment. Eine Beispielvorlage, die die benutzerdefinierte Skripterweiterung enthält, finden Sie hier auf GitHub.A sample template that includes the Custom Script Extension can be found here, GitHub.

{
  "name": "config-app",
  "type": "extensions",
  "location": "[resourceGroup().location]",
  "apiVersion": "2019-03-01",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      },
    "protectedSettings": {
      "commandToExecute": "sh hello.sh <param2>",
      "fileUris": ["https://github.com/MyProject/Archive/hello.sh"
      ]  
    }
  }
}

Hinweis

Bei Eigenschaftennamen wird zwischen Groß- und Kleinschreibung unterschieden.These property names are case-sensitive. Um Bereitstellungsprobleme zu vermeiden, verwenden Sie die Namen wie hier gezeigt.To avoid deployment problems, use the names as shown here.

Azure-BefehlszeilenschnittstelleAzure CLI

Wenn Sie die Azure-Befehlszeilenschnittstelle zum Ausführen der Erweiterung für benutzerdefinierte Skripts verwenden, erstellen Sie eine Konfigurationsdatei oder mehrere Konfigurationsdateien.When you're using Azure CLI to run the Custom Script Extension, create a configuration file or files. Es muss mindestens commandToExecute festgelegt sein.At a minimum, you must have 'commandToExecute'.

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

Optional können Sie die Einstellungen im Befehl als JSON-formatierte Zeichenfolge angeben.Optionally, you can specify the settings in the command as a JSON formatted string. Dadurch kann die Konfiguration während der Ausführung und ohne separate Konfigurationsdatei angegeben werden.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 \
  --protected-settings '{"fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"],"commandToExecute": "./config-music.sh"}'

Beispiele für die Azure-BefehlszeilenschnittstelleAzure CLI examples

Öffentliche Konfiguration mit SkriptdateiPublic configuration with script file

{
  "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"],
  "commandToExecute": "./config-music.sh"
}

Befehl für die Azure-Befehlszeilenschnittstelle:Azure CLI command:

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

Öffentliche Konfiguration ohne SkriptdateiPublic configuration with no script file

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

Befehl für die Azure-Befehlszeilenschnittstelle:Azure CLI command:

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

Dateien für die öffentliche und geschützte KonfigurationPublic and protected configuration files

Dateien für die öffentliche Konfiguration werden zum Angeben des Skriptdatei-URI verwendet.You use a public configuration file to specify the script file URI. Dateien für die geschützte Konfiguration werden zum Angeben des auszuführenden Befehls verwendet.You use a protected configuration file to specify the command to be run.

Datei für die öffentliche Konfiguration:Public configuration file:

{
  "fileUris": ["https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"]
}

Datei für die geschützte Konfiguration:Protected configuration file:

{
  "commandToExecute": "./config-music.sh <param1>"
}

Befehl für die Azure-Befehlszeilenschnittstelle: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

ProblembehandlungTroubleshooting

Beim Ausführen der Erweiterung für benutzerdefinierte Skripts wird das Skript erstellt oder wie im folgenden Beispiel in ein Verzeichnis heruntergeladen.When the Custom Script Extension runs, the script is created or downloaded into a directory that's similar to the following example. Die Ausgabe des Befehls wird ebenfalls in diesem Verzeichnis gespeichert (in den Dateien stdout und stderr).The command output is also saved into this directory in stdout and stderr files.

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

Überprüfen Sie zur Problembehandlung zunächst das Protokoll des Linux-Agents, und vergewissern Sie sich, dass die Erweiterung ausgeführt wurde:To troubleshoot, first check the Linux Agent Log, ensure the extension ran, check:

/var/log/waagent.log 

Suchen Sie nach der Erweiterungsausführung. Diese sieht in etwa wie folgt aus:You should look for the extension execution, it will look something like:

2018/04/26 17:47:22.110231 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] [Enable] current handler state is: notinstalled
2018/04/26 17:47:22.306407 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Download, message=Download succeeded, duration=167
2018/04/26 17:47:22.339958 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Initialize extension directory
2018/04/26 17:47:22.368293 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Update settings file: 0.settings
2018/04/26 17:47:22.394482 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Install extension [bin/custom-script-shim install]
2018/04/26 17:47:23.432774 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Install, message=Launch command succeeded: bin/custom-script-shim install, duration=1007
2018/04/26 17:47:23.476151 INFO [Microsoft.Azure.Extensions.customScript-2.0.6] Enable extension [bin/custom-script-shim enable]
2018/04/26 17:47:24.516444 INFO Event: name=Microsoft.Azure.Extensions.customScript, op=Enable, message=Launch command succeeded: bin/custom-sc

Hinweise:Some points to note:

  1. „Enable“ gibt den Beginn der Befehlsausführung an.Enable is when the command starts running.
  2. „Download“ bezieht sich auf das Herunterladen des CustomScript-Erweiterungspakets von Azure (nicht auf die in „fileUris“ angegebenen Skriptdateien).Download relates to the downloading of the CustomScript extension package from Azure, not the script files specified in fileUris.

Das von der Azure-Skripterweiterung erzeugte Protokoll finden Sie hier:The Azure Script Extension produces a log, which you can find here:

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

Suchen Sie nach der jeweiligen Ausführung. Diese ähnelt der folgenden:You should look for the individual execution, it will look something like:

time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=start
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=pre-check
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="comparing seqnum" path=mrseq
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="seqnum saved" path=mrseq
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="reading configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="read configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validating json schema"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="json schema valid"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="parsing configuration json"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="parsed configuration json"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validating configuration logically"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="validated configuration"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="creating output directory" path=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="created output directory"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 files=1
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 file=0 event="download start"
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 file=0 event="download complete" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executing command" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executing protected commandToExecute" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event="executed command" output=/var/lib/waagent/custom-script/download/0
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=enabled
time=2018-04-26T17:47:23Z version=v2.0.6/git@1008306-clean operation=enable seq=0 event=end

Darin sind folgende Informationen enthalten:Here you can see:

  • Der Befehl „Enable“ zum Starten dieses Protokolls.The Enable command starting is this log
  • Die an die Erweiterung übergebenen Einstellungen.The settings passed to the extension
  • Die Downloaddatei der Erweiterung und das entsprechende Ergebnis.The extension downloading file and the result of that.
  • Der ausgeführte Befehl und das Ergebnis.The command being run and the result.

Sie können den Ausführungsstatus der Erweiterung für benutzerdefinierte Skripts einschließlich der als commandToExecute übergebenen Argumente auch über die Azure-Befehlszeilenschnittstelle abrufen:You can also retrieve the execution state of the Custom Script Extension including the actual arguments passed as the commandToExecute by using Azure CLI:

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

Die Ausgabe sieht in etwa wie folgt aus:The output looks like the following text:

[
  {
    "autoUpgradeMinorVersion": true,
    "forceUpdateTag": null,
    "id": "/subscriptions/subscriptionid/resourceGroups/rgname/providers/Microsoft.Compute/virtualMachines/vmname/extensions/customscript",
    "resourceGroup": "rgname",
    "settings": {
      "commandToExecute": "sh script.sh > ",
      "fileUris": [
        "https://catalogartifact.azureedge.net/publicartifacts/scripts/script.sh",
        "https://catalogartifact.azureedge.net/publicartifacts/scripts/script.sh"
      ]
    },
    "tags": null,
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "typeHandlerVersion": "2.0",
    "virtualMachineExtensionType": "CustomScript"
  },
  {
    "autoUpgradeMinorVersion": true,
    "forceUpdateTag": null,
    "id": "/subscriptions/subscriptionid/resourceGroups/rgname/providers/Microsoft.Compute/virtualMachines/vmname/extensions/OmsAgentForLinux",
    "instanceView": null,
    "location": "eastus",
    "name": "OmsAgentForLinux",
    "protectedSettings": null,
    "provisioningState": "Succeeded",
    "publisher": "Microsoft.EnterpriseCloud.Monitoring",
    "resourceGroup": "rgname",
    "settings": {
      "workspaceId": "workspaceid"
    },
    "tags": null,
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "typeHandlerVersion": "1.0",
    "virtualMachineExtensionType": "OmsAgentForLinux"
  }
]

Nächste SchritteNext steps

Den Code sowie aktuelle Probleme und Versionen finden Sie im Repository der CustomScript-Erweiterung für Linux.To see the code, current issues and versions, see custom-script-extension-linux repo.