Exécuter des commandes lorsque vous lancez une EC2 instance avec saisie de données utilisateur - Amazon Elastic Compute Cloud

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Exécuter des commandes lorsque vous lancez une EC2 instance avec saisie de données utilisateur

Lorsque vous lancez une EC2 instance Amazon, vous pouvez transmettre les données utilisateur à l'instance qui est utilisée pour effectuer des tâches de configuration automatisées ou pour exécuter des scripts après le démarrage de l'instance.

Si vous êtes intéressé par des scénarios d'automatisation plus complexes, vous pouvez envisager AWS CloudFormation ou AWS OpsWorks. Pour plus d’informations, consultez les ressources suivantes :

Sur les instances Linux, vous pouvez transmettre deux types de données utilisateur à Amazon EC2 : les scripts shell et les directives cloud-init. Vous pouvez également transmettre ces données à l'assistant de lancement d'instance sous forme de texte brut, de fichier (utile pour lancer des instances à l'aide des outils de ligne de commande) ou de texte codé en base64 (pour les API appels).

Sur les instances Windows, les agents de lancement gèrent vos scripts de données utilisateur. Les sections suivantes présentent les différences dans la manière dont les données utilisateur sont traitées sur chaque système d'exploitation.

Données utilisateur dans le AWS Management 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 EBS volume, vous pouvez également arrêter l'instance et mettre à jour ses données utilisateur.

Spécifiez les données utilisateur de l'instance au lancement avec le Launch Wizard

Vous pouvez spécifier les données utilisateur lorsque vous lancez une instance à l'aide du Launch Wizard de la EC2 console. Pour spécifier les données utilisateur lors du lancement, suivez la procédure de lancement d'une instance. Le champ User data (Données utilisateur) se trouve dans la section Détails avancés de l’assistant de lancement d’instance. Entrez votre PowerShell script dans le champ Données utilisateur, puis terminez la procédure de lancement de l'instance.

Dans la capture d’écran suivante du champ Données utilisateur, l’exemple de script 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. Si vous laissez la case à cocher Les données utilisateur ont déjà été encodées en base64 vide, la EC2 console Amazon effectue le codage en base64 pour vous.

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

Pour de plus amples informations, veuillez consulter Spécifiez les données utilisateur de l'instance au lancement avec le Launch Wizard. Pour un exemple de Linux utilisant le AWS CLI, voirLes données de l'utilisateur et le AWS CLI. Pour un exemple de Windows utilisant les outils pour Windows PowerShell, voirLes données utilisateur et les outils pour Windows PowerShell.

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 EC2 console Amazon à 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.

Comment Amazon EC2 gère les données utilisateur pour les instances Linux

Dans les exemples suivants, les commandes d'installation d'un LAMP serveur sur Amazon Linux 2 sont converties en un script shell et en un ensemble de directives cloud-init qui s'exécutent au lancement de l'instance. Dans chaque exemple, les tâches suivantes sont exécutées par les données de l’utilisateur :

  • Les packages logiciels de distribution sont mis à jour.

  • Le serveur web, les packages php et mariadb nécessaires sont installés.

  • Le service httpd est lancé et activé via la commande systemctl.

  • L’utilisateur ec2-user est ajouté au groupe Apache.

  • La propriété et les autorisations sur les fichiers appropriées sont définies pour le répertoire web et les fichiers qu’il contient.

  • Une page Web simple est créée pour tester le serveur Web et le PHP moteur.

Prérequis

Les exemples de cette rubrique supposent ce qui suit :

  • Votre instance possède un DNS nom public accessible depuis Internet.

  • Le groupe de sécurité associé à votre instance est configuré pour autoriser le trafic SSH (port 22) afin que vous puissiez vous connecter à l'instance pour consulter les fichiers journaux de sortie.

  • Votre instance est lancée avec un Amazon Linux 2AMI. Ces instructions sont destinées à Amazon Linux 2, et il se peut que les commandes et les directives ne fonctionnent pas pour d’autres distributions Linux. Pour obtenir plus d’informations sur d’autres distributions, comme leur support pour cloud-init, consultez leur documentation spécifique.

Données utilisateur et scripts shell

Si vous connaissez le scripting de shell, il s’agit de la méthode la plus simple et la plus complète pour envoyer des instructions à une instance lors du lancement. L’ajout de ces tâches au moment du démarrage augmente le temps que cela prend pour démarrer l’instance. Vous devriez laisser s’écouler quelques minutes supplémentaires pour que les tâches s’effectuent avant de vérifier que le script utilisateur a fini avec succès.

Important

Par défaut, les scripts de données utilisateur et les directives cloud init s’exécutent uniquement pendant le cycle de démarrage lorsque vous lancez une instance pour la première fois. Vous pouvez mettre à jour votre configuration pour vous assurer que vos scripts de données utilisateur et vos directives cloud-init s’exécutent chaque fois que vous redémarrez votre instance. Pour plus d'informations, consultez Comment utiliser les données utilisateur pour exécuter automatiquement un script à chaque redémarrage de mon instance Amazon EC2 Linux ? dans le AWS Knowledge Center.

Les scripts shell de données utilisateur doivent commencer par les caractères #! et le chemin vers interpréteur que vous avez choisi pour la lecture du script (généralement /bin/bash)). Pour une introduction aux scripts shell, consultez le manuel de référence Bash sur le site Web du système GNU d'exploitation.

Les scripts entrés en tant que données utilisateur sont exécutés en tant qu’utilisateur root, donc n’utilisez pas la commande sudo dans le script. N’oubliez pas que tous les fichiers que vous créez seront la propriété de l’utilisateur root. Si vous avez besoin qu’un utilisateur non root ait accès aux fichiers, vous devez modifier les autorisations en conséquence dans le script. Par ailleurs, étant donné que le script n’est pas exécuté de façon interactive, vous ne pouvez pas inclure des commandes qui nécessitent les réactions de l’utilisateur (comme yum update sans l’indicateur -y).

Si vous utilisez un AWS API, y compris le 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 AWS informations d'identification appropriées requises par le script de données utilisateur pour émettre l'APIappel. Pour plus d'informations, consultez la section Utilisation des profils d'instance dans le Guide de IAM l'utilisateur. Les autorisations que vous attribuez au IAM rôle dépendent des services que vous appelez avec leAPI. Pour de plus amples informations, veuillez consulter IAMrôles pour Amazon EC2.

Le fichier journal de sortie cloud-init () capture la sortie de la console, si bien que vous pouvez facilement déboguer vos scripts après un lancement si l’instance ne se comporte pas comme vous le vouliez. Pour afficher le fichier journal,connexion à l’instanceet ouvrez/var/log/cloud-init-output.log.

Lorsqu’un script de données utilisateur est traité, il est copié dans et exécuté à partir de l /var/lib/cloud/instances/instance-id/. Le script n’est pas supprimé après son exécution. Assurez-vous de supprimer les scripts de données utilisateur /var/lib/cloud/instances/instance-id/ avant de créer un script AMI à partir de l'instance. Dans le cas contraire, le script existera dans ce répertoire sur n'importe quelle instance lancée depuis leAMI.

Mettre à jour les données utilisateur de l'instance

Pour mettre à jour les données de l’utilisateur de l’instance, vous devez d’abord arrêter l’instance. Si l’instance est en cours d’exécution, vous pouvez afficher les données utilisateur, mais vous ne pouvez pas les modifier.

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.

Pour modifier les données utilisateur d’instance
  1. Ouvrez la EC2 console Amazon à l'adresse https://console.aws.amazon.com/ec2/.

  2. Dans le panneau de navigation, choisissez Instances.

  3. Sélectionnez l’instance et choisissez État de l’instance, Arrêter l’instance. Si cette option est désactivée, l’instance est déjà arrêtée ou son périphérique racine est un volume de stockage d’instances.

  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).

  6. Modifiez les données utilisateur selon vos besoins, puis choisissez Save (Enregistrer).

  7. Démarrez l’instance. Les nouvelles données utilisateur sont visibles sur votre instance, après son démarrage. Par contre, les scripts des données utilisateur ne sont pas exécutés.

Directives sur les données utilisateur et Cloud-Init

Le package cloud-init configure les aspects spécifiques d’une nouvelle instance Amazon Linux lorsqu’elle est lancée. Il configure plus particulièrement le fichier .ssh/authorized_keys pour l’utilisateur ec2 afin que vous puissiez vous connecter avec votre clé privée. Pour plus d'informations sur les tâches de configuration effectuées par le package cloud-init pour les instances Amazon Linux, consultez la section Utilisation de cloud-init sur Amazon Linux 2 dans le guide de l'utilisateur Amazon Linux 2.

Les directives d’utilisateur cloud-init peuvent être transférées vers une instance au moment du lancement tout comme un script, même si la syntaxe est différente. Pour plus d’informations sur cloud-init, consultez http://cloudinit.readthedocs.org/en/latest/index.html.

Important

Par défaut, les scripts de données utilisateur et les directives cloud init s’exécutent uniquement pendant le cycle de démarrage lorsque vous lancez une instance pour la première fois. Vous pouvez mettre à jour votre configuration pour vous assurer que vos scripts de données utilisateur et vos directives cloud-init s’exécutent chaque fois que vous redémarrez votre instance. Pour plus d'informations, consultez Comment utiliser les données utilisateur pour exécuter automatiquement un script à chaque redémarrage de mon instance Amazon EC2 Linux ? dans le AWS Knowledge Center.

L’ajout de ces tâches au moment du démarrage augmente le temps que cela prend pour démarrer une instance. Vous devriez laisser s’écouler quelques minutes supplémentaires pour que les tâches s’effectuent avant de vérifier que vos directives sur les données utilisateur sont terminées.

Pour transférer les directives cloud-init vers une instance avec les données utilisateur
  1. Suivez la procédure pour lancer une instance. Le champ User data (Données utilisateur) se trouve dans la section Détails avancés de l’assistant de lancement d’instance. Saisissez le texte de la directive cloud-init dans le champ User data (Données utilisateur), puis terminez la procédure de lancement de l’instance.

    Pour l’exemple ci-dessous, les directives créent et configurent un serveur Web sur Amazon Linux 2. La ligne #cloud-config en haut est requise pour identifier les commandes en tant que directives cloud-init.

    #cloud-config repo_update: true repo_upgrade: all packages: - httpd - mariadb-server runcmd: - [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ] - systemctl start httpd - sudo systemctl enable httpd - [ sh, -c, "usermod -a -G apache ec2-user" ] - [ sh, -c, "chown -R ec2-user:apache /var/www" ] - chmod 2775 /var/www - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ] - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ] - [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]
  2. Laissez assez de temps à l’instance pour lancer et exécuter les directives dans vos données utilisateur, puis vérifiez que vos directives ont terminé les tâches que vous souhaitiez.

    Pour cet exemple, dans un navigateur Web, entrez le fichier URL de PHP test créé par les directives. Il URL s'agit de l'DNSadresse publique de votre instance suivie d'une barre oblique et du nom du fichier.

    http://my.public.dns.amazonaws.com/phpinfo.php

    Vous devriez voir la page PHP d'information. Si vous ne pouvez pas voir la page PHP d'informations, vérifiez que le groupe de sécurité que vous utilisez contient une règle autorisant le trafic HTTP (port 80). Pour de plus amples informations, veuillez consulter Configuration des règles du groupe de sécurité.

  3. (Facultatif) Si vos directives n’ont pas accompli les tâches que vous attendiez ou si vous voulez uniquement vérifier que vos directives se sont terminées sans erreur, connectez-vous à l’instance, examinez le fichier journal de sortie (/var/log/cloud-init-output.log) et recherchez les messages erronés dans les résultats. Pour plus d’informations sur le débogage, vous pouvez ajouter la ligne suivante à vos directives :

    output : { all : '| tee -a /var/log/cloud-init-output.log' }

    Cette directive envoie le résultat runcmd à /var/log/cloud-init-output.log.

Les données de l'utilisateur et le AWS CLI

Vous pouvez utiliser le AWS CLI 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 Accéder aux métadonnées d'une EC2 instance.

Sous Windows, vous pouvez utiliser le AWS Tools for Windows PowerShell au lieu du AWS CLI. Pour plus d'informations, consultez Les données utilisateur et les outils pour Windows PowerShell.

Exemple : spécification des données utilisateur au moment du lancement

Pour spécifier les données utilisateur lorsque vous lancez l’instance, utilisez la commande run-instances avec le paramètre --user-data. Avecrun-instances, il AWS CLI effectue le codage base64 des données utilisateur pour vous.

L’exemple suivant montre comment définir un script en tant que chaîne sur la ligne de commande :

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \ --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \ --user-data echo user data

L’exemple suivant montre comment définir un script en utilisant un fichier texte. Assurez-vous d’utiliser le préfixe file:// pour spécifier le fichier.

aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \ --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \ --user-data file://my_script.txt

L’exemple suivant est celui d’un fichier texte avec un script shell.

#!/bin/bash yum update -y service httpd start chkconfig httpd on
Exemple : Modification des données utilisateur d’une instance arrêtée

Vous pouvez modifier les données utilisateur d'une instance arrêtée à l'aide de la modify-instance-attributecommande. Avecmodify-instance-attribute, le AWS CLI n'effectue pas le codage base64 des données utilisateur pour vous.

  • Sur un ordinateur Linux utilisez la commande base64 pour encoder les données utilisateur.

    base64 my_script.txt >my_script_base64.txt
  • Sur un ordinateur Windows, utilisez la commande certutil pour encoder les données utilisateur. Avant de pouvoir utiliser ce fichier avec le AWS CLI, vous devez supprimer les première (BEGINCERTIFICATE) et dernière (ENDCERTIFICATE) lignes.

    certutil -encode my_script.txt my_script_base64.txt notepad my_script_base64.txt

Utilisez les paramètres --attribute et --value afin d’utiliser le fichier texte encodé pour spécifier les données utilisateur. Assurez-vous d’utiliser le préfixe file:// pour spécifier le fichier.

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt
Exemple : Effacer les données utilisateur d’une instance arrêtée

Pour supprimer les données utilisateur existantes, utilisez la modify-instance-attributecommande suivante :

aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=
Exemple : Affichage des données utilisateur

Pour récupérer les données utilisateur d'une instance, utilisez la describe-instance-attributecommande. Avecdescribe-instance-attribute, le AWS CLI n'effectue pas de décodage base64 des données utilisateur pour vous.

aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData

Voici un exemple de sortie avec les données utilisateur base64 encodées.

{ "UserData": { "Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg==" }, "InstanceId": "i-1234567890abcdef0" }
  • Sur un ordinateur Linux, utilisez l’option --query pour obtenir les données utilisateur encodées et la commande base64 pour les décoder.

    aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" | base64 --decode
  • Sur un ordinateur Windows, utilisez l’option --query pour obtenir les données utilisateur codées et la commande certutil pour les décoder. Notez que la sortie encodée est stockée dans un fichier et que la sortie décodée est stockée dans un autre fichier.

    aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" >my_output.txt certutil -decode my_output.txt my_output_decoded.txt type my_output_decoded.txt

Voici un exemple de sortie.

#!/bin/bash yum update -y service httpd start chkconfig httpd on

Combiner des scripts shell et des directives cloud-init

Par défaut, vous ne pouvez inclure qu’un seul type de contenu à la fois dans les données utilisateur. Toutefois, vous pouvez utiliser les types de contenu text/cloud-config et text/x-shellscript dans un fichier MIME en plusieurs parties pour inclure à la fois un script shell et des directives cloud-init dans vos données utilisateur.

Le format MIME en plusieurs parties est représenté ci-dessous.

Content-Type: multipart/mixed; boundary="//" MIME-Version: 1.0 --// Content-Type: text/cloud-config; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="cloud-config.txt" #cloud-config cloud-init directives --// Content-Type: text/x-shellscript; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="userdata.txt" #!/bin/bash shell script commands --//--

Par exemple, les données utilisateur suivantes incluent des directives cloud-init et un script shell bash. Les directives cloud-init créent un fichier (/test-cloudinit/cloud-init.txt) et y écrivent Created by cloud-init. Le script shell bash crée un fichier (/test-userscript/userscript.txt) et y écrit Created by bash shell script.

Content-Type: multipart/mixed; boundary="//" MIME-Version: 1.0 --// Content-Type: text/cloud-config; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="cloud-config.txt" #cloud-config runcmd: - [ mkdir, /test-cloudinit ] write_files: - path: /test-cloudinit/cloud-init.txt content: Created by cloud-init --// Content-Type: text/x-shellscript; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="userdata.txt" #!/bin/bash mkdir test-userscript touch /test-userscript/userscript.txt echo "Created by bash shell script" >> /test-userscript/userscript.txt --//--

Comment Amazon EC2 gère les données utilisateur pour les instances Windows

Sur les instances Windows, l'agent de lancement exécute les tâches liées aux données utilisateur. Pour plus d’informations, consultez les ressources suivantes :

Pour des exemples d'assemblage d'une UserData propriété dans un AWS CloudFormation modèle, voir Propriété codée en Base64 et UserData Propriété codée en Base64 avec AccessKey et. UserData SecretKey

Pour un exemple d'exécution de commandes sur une instance au sein d'un groupe Auto Scaling qui fonctionne avec des hooks de cycle de vie, consultez Tutoriel : 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 Amazon EC2 Auto Scaling.

Scripts de données utilisateur

Pour EC2Config ou EC2Launch pour exécuter des scripts, vous devez placer le script dans une balise spéciale lorsque vous l'ajoutez aux données utilisateur. La balise que vous utilisez varie selon que les commandes sont exécutées dans une fenêtre d'invite de commandes (commandes par lots) ou qu'elles utilisent WindowsPowerShell.

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

Si vous utilisez un AWS API, y compris le 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 AWS informations d'identification appropriées requises par le script de données utilisateur pour effectuer l'APIappel. Pour de plus amples informations, veuillez consulter Profils d’instance. Les autorisations que vous attribuez au IAM rôle dépendent des services que vous appelez avec leAPI. Pour de plus amples informations, veuillez consulter IAMrôles 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, comme indiqué dans l’exemple suivant.

<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 s’exécutent 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>
EC2Launchagent v2

Pour exécuter un script de données XML utilisateur en tant que processus détaché avec la executeScript tâche EC2Launch v2 dans l'UserDataétape, ajoutez <detach>true</detach> les données utilisateur.

Note

La detach balise n'est pas prise en charge par les agents de lancement précédents.

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

Syntaxe des PowerShell scripts Windows

AWS Windows AMIs inclut le AWS Tools for Windows PowerShell, afin que vous puissiez spécifier ces applets de commande dans les données utilisateur. Si vous associez un IAM rôle à votre instance, vous n'avez pas besoin de spécifier d'informations d'identification pour les applets de commande, car les applications qui s'exécutent sur l'instance utilisent les informations d'identification du rôle pour accéder aux AWS ressources (par exemple, les compartiments Amazon S3).

Spécifiez un PowerShell script Windows à l'aide de la <powershell> balise. 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 s'exécutent 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>

Vous pouvez spécifier un ou plusieurs PowerShell arguments à l'aide de la <powershellArguments> balise. Si aucun argument n'est passé, EC2Launch et que la EC2Launch v2 ajoute l'argument suivant par défaut :-ExecutionPolicy Unrestricted.

Exemple :

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

Pour exécuter un script de données XML utilisateur en tant que processus détaché avec la executeScript tâche EC2Launch v2 dans l'UserDataétape, ajoutez <detach>true</detach> les données utilisateur.

Note

La detach balise n'est pas prise en charge par les agents de lancement précédents.

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

Syntaxe des scripts YAML de configuration

Si vous utilisez la EC2Launch version 2 pour exécuter des scripts, vous pouvez utiliser le YAML format. Pour consulter les tâches de configuration, les détails et les exemples relatifs à la EC2Launch version 2, consultezEC2Launchconfiguration des tâches v2.

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

Exemple de YAML syntaxe pour exécuter un PowerShell script

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 YAML syntaxe pour exécuter un script batch

version: 1.1 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 Amazon EC2 API ou un outil qui n'effectue pas de codage base64 des données utilisateur, vous devez les encoder vous-même. 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 d'encodage à l'aide de Windows PowerShell.

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

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

$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 AMIs des données utilisateur est activée sur tous les systèmes AWS Windows lors du lancement initial. 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 Exécuter des scripts lors des redémarrages 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.

Scripts de lancement d'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 les EC2Launch versions 2 et 2 EC2Config contiennent le résultat de la sortie standard et des flux d'erreurs standard. EC2Launch

EC2Launch v2

Le fichier journal de la EC2Launch v2 estC:\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 XML format

  • Info: Initialize 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 de 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 de 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

Exécuter des scripts lors des redémarrages 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 la EC2Launch version 2
  • 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
  1. Connectez-vous à votre instance Windows.

  2. Ouvrez une fenêtre de PowerShell commande 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 activer l'exécution des données utilisateur avec EC2Config
  1. Connectez-vous à votre instance Windows.

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

  3. Pour les données utilisateur, sélectionnez Activer UserData l'exécution 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.

Les données utilisateur et les outils pour Windows PowerShell

Vous pouvez utiliser les Outils pour 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 Accéder aux métadonnées d'une EC2 instance. Pour plus d'informations sur les données utilisateur et le AWS CLI, voirLes données de l'utilisateur et le AWS CLI.

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 de l'instance lorsque vous lancez votre instance, utilisez la New-EC2Instancecommande. 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 Edit-EC2InstanceAttributecommande.

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 récupérer les données utilisateur d'une instance, utilisez la Get-EC2InstanceAttributecommande.

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 Get-EC2Tagcommande pour lire la valeur de la balise, renommer l'instance au premier démarrage pour qu'elle corresponde à la valeur de la balise, puis redémarrer. Pour exécuter correctement cette commande, vous devez disposer d'un rôle doté d'ec2:DescribeTagsautorisations associées à l'instance, car les informations de balise sont récupérées par l'APIappel. Pour plus d'informations sur les paramètres des autorisations à l'aide de IAM rôles, consultezAttacher un IAM rôle à une instance.

IMDSv2
<powershell> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri 'http://169.254.169.254/latest/api/token' -UseBasicParsing $instanceId = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 'http://169.254.169.254/latest/meta-data/instance-id' -UseBasicParsing $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>
IMDSv1
<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. Pour de plus amples informations, veuillez consulter Afficher les balises de vos EC2 instances à l'aide des métadonnées de l'instance.

IMDSv2
<powershell> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri 'http://169.254.169.254/latest/api/token' -UseBasicParsing $nameValue = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 'http://169.254.169.254/latest/meta-data/tags/instance/Name' -UseBasicParsing $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>
IMDSv1
<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>