Exécuter des commandes au lancement sur votre instance Windows - Amazon Elastic Compute Cloud

Exécuter des commandes au lancement sur votre instance Windows

Lorsque vous lancez une instance Windows à l'aide d'Amazon EC2, vous pouvez transmettre les données utilisateur à l'instance qui peut être utilisée pour effectuer des tâches de configuration automatisées ou exécuter des scripts après le démarrage de l'instance. Les données utilisateur d'instance sont traitées comme des données opaques ; l'instance se charge de les interpréter. Les données utilisateur sont traitées par EC2Launch v2 sur Windows Server 2022, EC2Launch sur Windows Server 2016 et 2019, et EC2Config sur Windows Server 2012 R2 et antérieur.

Pour obtenir des exemples d'assemblage d'une propriété UserData dans un modèle AWS CloudFormation, consultez les informations sur la propriété UserData codée en Base64 et sur la propriété UserData codée en Base64 avec AccessKey et SecretKey.

Pour plus d'informations sur l'exécution de commandes sur votre instance Linux lors du lancement, consultez Exécution de commandes sur votre instance Linux lors du lancement dans le Amazon EC2 Guide de l'utilisateur pour les instances Linux.

Pour un exemple d'exécution de commandes sur une instance au sein d'Auto Scaling qui fonctionnent avec des hooks de cycle de vie, veuillez consulter Didacticiel : configurer les données utilisateur pour récupérer l'état du cycle de vie cible via les métadonnées de l'instance dans le Guide de l'utilisateur d'Amazon EC2 Auto Scaling.

Scripts de données utilisateur

Pour qu'EC2Config ou EC2Launch exécute un script, vous devez l'inclure dans une balise spéciale lorsque vous l'ajoutez aux données utilisateur. La balise que vous utilisez diffère si les commandes s'exécutent dans une fenêtre d'invite de commande (commandes par lots) ou si elles utilisent Windows PowerShell.

Si vous spécifiez un script par lots et un script Windows PowerShell, le script par lots s'exécute en premier et le script Windows PowerShell s'exécute ensuite quel que soit l'ordre dans lequel ils apparaissent dans les données utilisateur d'instance.

Si vous utilisez une API AWS, y compris l'interface de ligne de commande AWS CLI, dans un script de données utilisateur, vous devez utiliser un profil d'instance lors du lancement de l'instance. Un profil d'instance fournit les informations d'identification AWS appropriées requises par le script de données utilisateur pour émettre l'appel d'API. Pour plus d'informations, consultez Profils d'instance. Les autorisations que vous attribuez au rôle IAM dépendent des services que vous appelez avec l'API. Pour plus d'informations, consultez Rôles IAM pour Amazon EC2.

Syntaxe des scripts par lots

Spécifiez un script par lots à l'aide de la balise script. Séparez les commandes à l'aide de sauts de ligne. Exemples :

<script> echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log </script>

Par défaut, les scripts de données utilisateur sont exécutés une seule fois, lorsque vous lancez l'instance. Pour exécuter des scripts de données utilisateur chaque fois que vous redémarrez ou démarrez l'instance, ajoutez <persist>true</persist> aux données utilisateur.

<script> echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log </script> <persist>true</persist>

Syntaxe des scripts Windows PowerShell

Les AMI AWS Windows comprennent AWS Tools for Windows PowerShell. Vous pouvez donc spécifier ces cmdlets dans les données utilisateur. Si vous associez un rôle IAM à votre instance, vous n'avez pas à spécifier d'informations d'identification dans les cmdlets, car les applications qui s'exécutent sur l'instance utilisent les informations d'identification du rôle pour accéder aux ressources AWS (par exemple, des compartiments Amazon S3).

Spécifiez un script Windows PowerShell à l'aide de la balise <powershell>. Séparez les commandes à l'aide de sauts de ligne. La balise <powershell> est sensible à la casse.

Par exemple :

<powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell>

Par défaut, les scripts de données utilisateur sont exécutés une seule fois, lorsque vous lancez l'instance. Pour exécuter des scripts de données utilisateur chaque fois que vous redémarrez ou démarrez l'instance, ajoutez <persist>true</persist> aux données utilisateur.

<powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>

Syntaxe pour les scripts de configuration YAML

Si vous utilisez EC2Launch v2 pour exécuter des scripts, vous pouvez utiliser le format YAML. Pour afficher les tâches de configuration, les détails et les exemples pour EC2Launch v2, consultez Configuration de tâche EC2Launch v2.

Spécifiez un script YAML avec la tâche executeScript.

Exemple de syntaxe YAML pour exécuter un script PowerShell

version: 1.0 tasks: - task: executeScript inputs: - frequency: always type: powershell runAs: localSystem content: |- $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file

Exemple de syntaxe YAML pour exécuter un script Batch

version: 1.0 tasks: - task: executeScript inputs: - frequency: always type: batch runAs: localSystem content: |- echo Current date and time >> %SystemRoot%\Temp\test.log echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log

Encodage Base64

Si vous utilisez l'API Amazon EC2 ou un outil qui n'effectue pas l'encodage base64 des données utilisateur, vous devez encoder les données utilisateur. Si ce n'est pas le cas, une erreur indiquant qu'aucune balise script ou powershell à exécuter n'a été trouvée est consignée. Voici un exemple qui encode à l'aide de Windows PowerShell.

$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

Voici un exemple qui décode à l'aide de PowerShell.

$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))

Pour plus d'informations sur l'encodage base64, consultez https://www.ietf.org/rfc/rfc4648.txt.

Exécution de données utilisateur

Par défaut, l'exécution de données utilisateur est activée pour le lancement initial sur toutes les AMI AWS Windows. Vous pouvez spécifier que les scripts de données utilisateur doivent être exécutés au prochain réamorçage ou redémarrage de l'instance. Vous pouvez également spécifier que les scripts de données utilisateur doivent être exécutés chaque fois que l'instance est réamorcée ou redémarre.

Note

Les données utilisateur ne sont pas activées pour être exécutées par défaut après le lancement initial. Pour activer l'exécution des données utilisateur lorsque vous redémarrez ou démarrez l'instance, consultez Réamorçages ou démarrages suivants.

Les scripts de données utilisateur sont exécutés depuis le compte de l'administrateur local quand un mot de passe aléatoire est généré. Sinon, les scripts de données utilisateur sont exécutés depuis le compte système.

Lancement d'une instance

Les scripts figurant dans les données utilisateur d'instance sont exécutés lors du lancement initial de l'instance. Si la balise persist est trouvée, l'exécution des données utilisateur est activée pour les réamorçages ou démarrages suivants. Les fichiers journaux pour EC2Launch v2, EC2Launch et EC2Config contiennent les résultats de sortie standard ainsi que les flux d'erreurs standard.

EC2Launch v2

Le fichier journal de EC2Launch v2 est C:\ProgramData\Amazon\EC2Launch\log\agent.log.

Note

Le dossier C:\ProgramData peut être masqué. Pour afficher le dossier, vous devez afficher les fichiers et les dossiers masqués.

Les informations suivantes sont enregistrées lorsque les données utilisateur sont exécutées :

  • Info: Converting user-data to yaml format – Si les données utilisateur ont été fournies au format XML

  • Info: Initializing user-data state – Début de l'exécution des données utilisateur

  • Info: Frequency is: always – Si la tâche de données utilisateur est en cours d'exécution à chaque démarrage

  • Info: Frequency is: once – Si la tâche de données utilisateur est exécutée une seule fois

  • Stage: postReadyUserData execution completed – Fin de l'exécution des données utilisateur

EC2Launch

Le fichier journal pour EC2Launch est C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log.

Le dossier C:\ProgramData peut être masqué. Pour afficher le dossier, vous devez afficher les fichiers et les dossiers masqués.

Les informations suivantes sont enregistrées lorsque les données utilisateur sont exécutées :

  • Userdata execution begins – Début de l'exécution des données utilisateur

  • <persist> tag was provided: true – Si l'identification persist est trouvée

  • Running userdata on every boot – Si l'identification persist est trouvée

  • <powershell> tag was provided.. running powershell content – Si la balise powershell est trouvée

  • <script> tag was provided.. running script content – Si l'identification script est trouvée

  • Message: The output from user scripts – Si des scripts de données utilisateur sont exécutés, leur sortie est journalisée

EC2Config

Le fichier journal pour EC2Config est C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log. Les informations suivantes sont enregistrées lorsque les données utilisateur sont exécutées :

  • Ec2HandleUserData: Message: Start running user scripts – Début de l'exécution des données utilisateur

  • Ec2HandleUserData: Message: Re-enabled userdata execution – Si l'identification persist est trouvée

  • Ec2HandleUserData: Message: Could not find <persist> and </persist> – Si la balise persist n'est pas trouvée

  • Ec2HandleUserData: Message: The output from user scripts – Si des scripts de données utilisateur sont exécutés, leur sortie est journalisée

Réamorçages ou démarrages suivants

Lorsque vous mettez à jour des données utilisateur d'instance, les scripts de données utilisateur sont exécutés automatiquement lorsque vous redémarrez ou démarrez l'instance. Toutefois, vous pouvez activer l'exécution des données utilisateur pour que les scripts de données utilisateur soient exécutés une seule fois lorsque vous redémarrez ou démarrez l'instance ou chaque fois que vous redémarrez ou démarrez l'instance.

Si vous choisissez l'option Arrêter avec Sysprep, les scripts de données utilisateur sont exécutés quand l'instance est redémarrée ou démarrée, même si vous n'avez pas activé l'exécution des données utilisateur pour les redémarrages ou démarrages suivants. Les scripts de données utilisateur ne seront pas exécutés lors des redémarrages ou démarrages ultérieurs.

Pour activer l'exécution des données utilisateur avec EC2Launch v2 (AMI d'aperçu)
  • Pour exécuter une tâche dans les données utilisateur au premier démarrage, définissez frequency sur once.

  • Pour exécuter une tâche dans les données utilisateur à chaque démarrage, définissez frequency sur always.

Pour activer l'exécution des données utilisateur avec EC2Launch (Windows Server 2016 ou version ultérieure)
  1. Connectez-vous à votre instance Windows.

  2. Ouvrez une fenêtre de commande PowerShell et exécutez la commande suivante :

    C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 –Schedule
  3. Déconnectez-vous de votre instance Windows. Pour exécuter les scripts mis à jour au démarrage suivant de l'instance, arrêtez l'instance et mettez à jour les données utilisateur. Pour plus d'informations, consultez Affichage et mise à jour des données utilisateur d'instance.

Pour activer l'exécution des données utilisateur avec EC2Config (Windows Server 2012 R2 et versions antérieures)
  1. Connectez-vous à votre instance Windows.

  2. Ouvrir C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSetting.exe.

  3. Pour User Data (Données utilisateur), sélectionnez Enable UserData execution for next service start (Activer l'exécution des données utilisateur pour le prochain démarrage du service).

  4. Déconnectez-vous de votre instance Windows. Pour exécuter les scripts mis à jour au démarrage suivant de l'instance, arrêtez l'instance et mettez à jour les données utilisateur. Pour plus d'informations, consultez Affichage et mise à jour des données utilisateur d'instance.

Données utilisateur et console

Vous pouvez spécifier des données utilisateur d'instance lorsque vous lancez l'instance. Si le volume racine de l'instance est un volume EBS, vous pouvez également arrêter l'instance et mettre à jour ses données utilisateur.

Spécification des données utilisateur d'instance au moment du lancement

Lorsque vous lancez une instance, vous spécifiez le script dans Détails avancés, Données utilisateur sur la page Étape 3 : Configurer les détails de l'instance de l'assistant Lancer une instance. L'exemple de l'image suivante crée un fichier dans le dossier temporaire Windows, en utilisant la date et l'heure actuelles dans le nom de fichier. Lorsque vous incluez <persist>true</persist>, le script est exécuté chaque fois que vous redémarrez ou démarrez l'instance. Lorsque vous sélectionnez Sous forme de texte, la console Amazon EC2 effectue l'encodage base64 pour vous.


					Champ de texte des données utilisateur Advance Details (Détails avancés).

Affichage et mise à jour des données utilisateur d'instance

Vous pouvez afficher les données utilisateur d'instance pour n'importe quelle instance, et vous pouvez mettre à jour les données utilisateur d'instance pour une instance arrêtée.

Pour mettre à jour les données utilisateur pour une instance à l'aide de la console
  1. Ouvrez la console Amazon EC2 à l'adresse https://console.aws.amazon.com/ec2/.

  2. Dans le panneau de navigation, choisissez Instances.

  3. Sélectionnez l'instance et choisissez Actions, État de l'instance, Arrêter l'instance.

    Avertissement

    Lorsque vous arrêtez une instance, les données contenues sur les volumes de stockage d'instances sont effacées. Pour conserver les données provenant des volumes de stockage d'instances, sauvegardez-les sur un stockage permanent.

  4. Lorsque vous êtes invité à confirmer l'opération, choisissez Arrêter. L'arrêt de l'instance peut prendre quelques minutes.

  5. Alors que l'instance est toujours sélectionnée, choisissez Actions, Instance settings (Paramètres de l'instance), Edit user data (Modifier les données utilisateur). Vous ne pouvez changer les données utilisateur si l'instance est en cours d'exécution, mais vous pouvez les voir.

  6. Dans la boîte de dialogue Modifier les données utilisateur, mettez à jour les données utilisateur, puis cliquez sur Enregistrer. Pour exécuter des scripts de données utilisateur chaque fois que vous redémarrez ou démarrez l'instance, ajoutez <persist>true</persist>, comme illustré dans l'exemple suivant.

    
							Boîte de dialogue Edit User Data (Modifier les données utilisateur).
  7. Démarrez l'instance. Si vous avez activé l'exécution des données utilisateur pour les redémarrages ou démarrages suivants, les scripts de données utilisateur mis à jour sont exécutés dans le cadre du processus de démarrage de l'instance.

Données utilisateur et Tools for Windows PowerShell

Vous pouvez utiliser Tools for Windows PowerShell pour spécifier, modifier et afficher les données utilisateur de votre instance. Pour plus d'informations sur l'affichage des données utilisateur de votre instance à l'aide des métadonnées d'instance, consultez Récupération des données utilisateur d'instance. Pour plus d'informations sur les données utilisateur et AWS CLI, consultez Données utilisateur et AWS CLI dans le Guide de l'utilisateur Amazon EC2 pour les instances Linux.

Exemple : Spécification des données utilisateur d'instance au moment du lancement

Créez un fichier texte avec les données utilisateur d'instance. Pour exécuter des scripts de données utilisateur chaque fois que vous redémarrez ou démarrez l'instance, ajoutez <persist>true</persist>, comme illustré dans l'exemple suivant.

<powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>

Pour spécifier les données utilisateur d'instance lorsque vous lancez l'instance, utilisez la commande New-EC2Instance. Cette commande n'effectue pas l'encodage base64 des données utilisateur pour vous. Utilisez les commandes suivantes pour encoder les données utilisateur dans un fichier texte nommé script.txt.

PS C:\> $Script = Get-Content -Raw script.txt PS C:\> $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

Utilisez le paramètre -UserData pour transmettre les données utilisateur à la commande New-EC2Instance.

PS C:\> New-EC2Instance -ImageId ami-abcd1234 -MinCount 1 -MaxCount 1 -InstanceType m3.medium \ -KeyName my-key-pair -SubnetId subnet-12345678 -SecurityGroupIds sg-1a2b3c4d \ -UserData $UserData
Exemple : Mise à jour des données utilisateur d'instance pour une instance arrêtée

Vous pouvez modifier les données utilisateur d'une instance arrêtée à l'aide de la commande Edit-EC2InstanceAttribute.

Créez un fichier texte contenant le nouveau script. Utilisez les commandes suivantes pour encoder les données utilisateur dans le fichier texte nommé new-script.txt.

PS C:\> $NewScript = Get-Content -Raw new-script.txt PS C:\> $NewUserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($NewScript))

Utilisez les paramètres -UserData et -Value pour spécifier les données utilisateur.

PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData
Exemple : Affichage des données utilisateur d'instance

Pour extraire les données utilisateur pour une instance, utilisez la commande Get-EC2InstanceAttribute.

PS C:\> (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData

Voici un exemple de sortie. Notez que les données utilisateur sont encodées.

PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=

Utilisez les commandes suivantes pour stocker les données utilisateur encodées dans une variable, puis les décoder.

PS C:\> $UserData_encoded = (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData_encoded))

Voici un exemple de sortie.

<powershell> $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm") New-Item $file -ItemType file </powershell> <persist>true</persist>
Exemple : Attribution d'un nouveau nom à l'instance pour correspondre à la valeur de la balise

Vous pouvez utiliser la commande Get-EC2Tag pour lire la valeur de l'identification, renommer l'instance au premier démarrage pour que son nom corresponde à la valeur de l'identification et la redémarrer. Pour exécuter cette commande avec succès, vous devez avoir un rôle avec les autorisations ec2:DescribeTags attachées à l'instance, car les informations sur les identifications sont extraites par l'appel d'API. Pour plus d'informations sur les autorisations de configuration à l'aide des rôles IAM, consultez Attacher un rôle IAM à une instance.

Note

Le script échoue avec les versions Windows Server antérieures à 2008.

<powershell> $instanceId = (invoke-webrequest http://169.254.169.254/latest/meta-data/instance-id -UseBasicParsing).content $nameValue = (get-ec2tag -filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value $pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$" #Verify Name Value satisfies best practices for Windows hostnames If ($nameValue -match $pattern) {Try {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} Catch {$ErrorMessage = $_.Exception.Message Write-Output "Rename failed: $ErrorMessage"}} Else {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"} </powershell>

Vous pouvez également renommer l'instance à l'aide d'identifications dans les métadonnées d'instance si votre instance est configurée pour accéder aux identifications à partir des métadonnées d'instance.

Note

Le script échoue avec les versions Windows Server antérieures à 2008.

<powershell> $nameValue = Get-EC2InstanceMetadata -Path /tags/instance/Name $pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$" #Verify Name Value satisfies best practices for Windows hostnames If ($nameValue -match $pattern) {Try {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} Catch {$ErrorMessage = $_.Exception.Message Write-Output "Rename failed: $ErrorMessage"}} Else {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"} </powershell>