Paramètres EC2Launch v2 - Amazon Elastic Compute Cloud
Modifier les paramètres à l’aide de la boîte de dialogue des paramètres EC2Launch v2Structure du répertoire EC2Launch v2Configurer EC2Launch v2 avec la CLIConfiguration de tâche EC2Launch v2Codes de sortie EC2Launch v2 et redémarragesEC2Launch v2 et Sysprep

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.

Paramètres EC2Launch v2

Cette section contient des informations sur la configuration des paramètres pour EC2Launch v2.

Modifier les paramètres à l’aide de la boîte de dialogue des paramètres EC2Launch v2

La procédure suivante décrit la manière d’utiliser le service la boîte de dialogue des paramètres EC2Launch v2 pour activer ou désactiver les paramètres.

Note

Si vous configurez incorrectement les tâches personnalisées dans le fichier agent-config.yml et que vous tentez d’ouvrir la boîte de dialogue des paramètres Amazon EC2Launch, vous recevrez une erreur. Pour un exemple de schéma, consultez Exemple : agent-config.yml.

  1. Lancez et connectez-vous à votre instance Windows.

  2. Dans le menu Démarrer, choisissez Tous les programmes, puis accédez aux paramètres EC2Launch.

    Application des paramètres de lancement EC2.

  3. Sur l’onglet Général de la boîte de dialogue Paramètres de lancement EC2, vous pouvez activer ou désactiver les paramètres suivants.

    1. Set Computer Name (Définir le nom de l’ordinateur)

      Si ce paramètre est activé (il est désactivé par défaut), le nom d’hôte actuel est comparé au nom d’hôte souhaité à chaque démarrage. Si les noms d’hôte ne correspondent pas, le nom d’hôte est réinitialisé et le système redémarre éventuellement pour récupérer le nouveau nom d’hôte. Si un nom d’hôte personnalisé n’est pas spécifié, il est généré à l’aide de l’adresse IPv4 privée au format hexadécimal, par exemple ip-AC1F4E6. Pour empêcher que votre nom d’hôte existant ne soit modifié, n’activez pas ce paramètre.

    2. Étendre le volume de démarrage

      Ce paramètre étend de manière dynamique Disk 0/Volume 0 pour inclure l’espace non partitionné. Cela peut être utile lorsque l’instance est démarrée à partir d’un volume du périphérique racine doté d’une taille personnalisée.

    3. Définir le compte administrateur

      Lorsque cette option est activée, vous pouvez définir les attributs de nom d’utilisateur et de mot de passe pour le compte d’administrateur créé sur votre ordinateur local. Si cette fonctionnalité n’est pas activée, un compte d’administrateur n’est pas créé sur le système après Sysprep. Indiquez un mot de passe dans adminPassword uniquement si adminPasswordtype est Specify.

      Les types de mots de passe sont définis comme suit :

      1. Random

        EC2Launch génère un mot de passe et le chiffre à l’aide de la clé de l’utilisateur. Le système désactive ce paramètre après le lancement de l’instance afin que ce mot de passe persiste si l’instance est redémarrée, arrêtée ou démarrée.

      2. Specify

        EC2Launch utilise le mot de passe que vous spécifiez dans adminPassword. Si ce mot de passe ne répond pas aux exigences du système, EC2Launch génère un mot de passe aléatoire à la place. Le mot de passe est stocké dans le fichier agent-config.yml sous forme de texte clair et est supprimé une fois que le mot de passe est défini par Sysprep. EC2Launch chiffre le mot de passe à l’aide de la clé de l’utilisateur.

      3. Do not set

        EC2Launch utilise le mot de passe que vous spécifiez dans le fichier unattend.xml. Si vous ne spécifiez pas de mot de passe dans unattend.xml, le compte d’administrateur est désactivé.

    4. Démarrer le service SSM

      Lorsque cette option est sélectionnée, le service Systems Manager est activé pour démarrer à la suite de Sysprep. EC2Launch v2 exécute toutes les tâches décrites précédemment, et SSM Agent traite les requêtes des fonctionnalités Systems Manager telles que Run Command et State Manager.

      Vous pouvez utiliser la fonctionnalité Run Command pour mettre à niveau les instances existantes et utiliser la dernière version du service EC2Launch v2 et de SSM Agent. Pour plus d’informations, consultez Update SSM Agent by using Run Command dans le Guide de l’utilisateur AWS Systems Manager.

    5. Optimiser ENA

      Lorsque cette option est sélectionnée, les paramètres ENA sont configurés pour garantir que les paramètres ENA de dimensionnement côté réception et de profondeur de file d'attente de réception sont optimisés pour AWS. Pour plus d’informations, consultez Configuration de l’affinité d’UC RSS.

    6. Activer SSH

      Ce paramètre permet à OpenSSH pour les versions ultérieures de Windows d’autoriser l’administration du système à distance.

    7. Activer les trames Jumbo

      Sélectionnez cette option pour activer les trames Jumbo. Les trames Jumbo peuvent avoir des effets inattendus sur vos communications réseau. Assurez-vous donc de comprendre comment les trames Jumbo auront un impact sur votre système avant de les activer. Pour plus d’informations sur les trames jumbo, consultez Trames jumbo (MTU de 9001).

    8. Préparer l’imagerie

      Indiquez si vous souhaitez que votre instance EC2 s’arrête avec ou sans Sysprep. Lorsque vous souhaitez exécuter Sysprep avec EC2Launch v2, choisissez Arrêter avec Sysprep.

  4. Dans l’onglet Suffixe DNS vous pouvez sélectionner si vous souhaitez ajouter une liste de suffixe DNS pour la résolution DNS des serveurs exécutés dans EC2, sans fournir le nom de domaine complet. Les suffixes DNS peuvent contenir les variables $REGION et $AZ. Seuls les suffixes qui n’existent pas déjà seront ajoutés à la liste.

    Application des paramètres de lancement EC2.

  5. Dans l’onglet Fond d’écran, vous pouvez configurer le fond d’écran de votre instance avec une image d’arrière-plan et spécifier les détails de l’instance à afficher dans le fond d’écran. Amazon EC2 génère les détails à chaque fois que vous vous connectez.

    Vous pouvez configurer votre fond d’écran à l’aide des commandes suivantes.

    • Afficher les détails de l’instance sur le fond d’écran – Cette case à cocher active ou désactive l’affichage des détails de l’instance sur le fond d’écran.

    • Chemin de l’image (.jpg) – Spécifiez le chemin d’accès à l’image à utiliser comme fond d’écran.

    • Sélectionner les attributs à afficher sur le fond d’écran – Cochez les cases correspondant aux détails de l’instance que vous voulez voir apparaître sur le fond d’écran. Décochez les cases des détails d’instance précédemment sélectionnés que vous voulez supprimer du fond d’écran.

    • Afficher les balises d’instance sur le fond d’écran – Sélectionnez l’un des paramètres suivants pour afficher les balises d’instance sur le fond d’écran :

      • Aucun : n’affichez aucune balise d’instance sur le fond d’écran.

      • Afficher tout : affiche toutes les balises d’instance sur le fond d’écran.

      • Afficher avec filtre : affiche les balises d’instance spécifiées sur le fond d’écran. Lorsque vous sélectionnez ce paramètre, vous pouvez ajouter les balises d’instance que vous souhaitez voir s’afficher sur votre fond d’écran dans la zone Filtre de balise d’instance.

        Note

        Vous devez activer les balises dans les métadonnées pour afficher les balises sur le fond d’écran. Pour plus d’informations sur les balises et métadonnées d’instance, consultez Utiliser les identifications d’instance dans les métadonnées d’instance.

    Onglet Fond d’écran des paramètres de lancement d’EC2.

  6. Sous l’onglet Volumes, indiquez si vous souhaitez initialiser les volumes attachés à l’instance. L’activation définit les lettres de lecteur pour tous les volumes supplémentaires et les étend pour utiliser l’espace disponible. Si vous sélectionnez Tous, tous les volumes de stockage sont initialisés. Si vous sélectionnez Appareils, seuls les appareils spécifiés dans la liste sont initialisés. Vous devez entrer l’appareil pour chaque appareil à initialiser. Utilisez les appareils répertoriés sur la console EC2, par exemple, xvdb ou /dev/nvme0n1. La liste déroulante affiche les volumes de stockage attachés à l’instance. Pour entrer un appareil qui n’est pas attaché à l’instance, saisissez-le dans le champ de texte.

    Nom, Lettre et Partition sont des champs facultatifs. Si aucune valeur n'est spécifiée pour Partition, les volumes de stockage supérieurs à 2 To sont initialisés avec le type de gpt partition, et ceux inférieurs à 2 To sont initialisés avec le type de mbr partition. Si des appareils sont configurés et qu’un appareil non NTFS contient une table de partitions ou que les 4 premiers Ko du disque contiennent des données, le disque est ignoré et l’action est consignée.

    Application des paramètres de lancement EC2.

Voici un exemple de fichier YAML de configuration créé à partir des paramètres saisis dans la boîte de dialogue EC2Launch.

version: 1.0
config:
  - stage: boot
	tasks:
      - task: extendRootPartition
  - stage: preReady
    tasks:
      - task: activateWindows
        inputs:
          activation:
            type: amazon
      - task: setDnsSuffix
        inputs:
          suffixes:
            - $REGION.ec2-utilities.amazonaws.com
      - task: setAdminAccount
        inputs:
          password:
            type: random
      - task: setWallpaper
        inputs:
          path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
          attributes:
            - hostName
            - instanceId
            - privateIpAddress
            - publicIpAddress
            - instanceSize
            - availabilityZone
            - architecture
            - memory
            - network
  - stage: postReady
    tasks:
      - task: startSsm

Structure du répertoire EC2Launch v2

EC2Launch v2 doit être installé dans les répertoires suivants :

  • Binaires de service : %ProgramFiles%\Amazon\EC2Launch

  • Données de service (paramètres, fichiers journaux et fichiers d’état) : %ProgramData%\Amazon\EC2Launch

Note

Par défaut, Windows masque les fichiers et les dossiers qui se trouvent sous C:\ProgramData. Pour afficher les fichiers et les répertoires EC2Launch v2, vous devez entrer le chemin d’accès dans l’explorateur Windows ou modifier les propriétés de dossier afin d’afficher les fichiers et les dossiers cachés.

Le répertoire %ProgramFiles%\Amazon\EC2Launch contient des binaires et des bibliothèques de support. Il comprend les sous-répertoires suivants :

  • settings

    • EC2LaunchSettingsUI.exe — Interface utilisateur pour modifier le fichier agent-config.yml

    • YamlDotNet.dll — DLL pour prendre en charge certaines opérations dans l’interface utilisateur

  • tools

    • ebsnvme-id.exe — Outil pour examiner les métadonnées des volumes EBS sur l’instance

    • AWSAcpiSpcrReader.exe — Outil pour déterminer le port COM correct à utiliser

    • EC2LaunchEventMessage.dll — DLL pour prendre en charge la journalisation des événements Windows pour EC2Launch

  • service

    • EC2LaunchService.exe — Exécutable de service Windows qui est lancé lorsque l’agent de lancement s’exécute en tant que service.

  • EC2Launch.exe — Exécutable principal EC2Launch

  • EC2LaunchAgentAttribution.txt — Attribution du code utilisé dans EC2 Launch

Le répertoire %ProgramData%\Amazon\EC2Launch contient les sous-répertoires suivants. Toutes les données produites par le service, y compris les journaux, la configuration et l’état, sont stockées dans ce répertoire.

  • config — Configuration

    Le fichier de configuration du service est stocké dans ce répertoire sous la forme de agent-config.yml. Ce fichier peut être mis à jour pour modifier, ajouter ou supprimer des tâches exécutées par le service par défaut. L’autorisation de créer des fichiers dans ce répertoire est limitée au compte administrateur pour empêcher l’escalade des privilèges.

  • log — Journaux d’instances

    Les journaux pour le service (agent.log), la console (console.log), les performances (bench.log) et les erreurs (error.log) sont stockés dans ce répertoire. Les fichiers journaux sont ajoutés lors des exécutions ultérieures du service.

  • state — Données sur l’état du service

    L’état utilisé par le service pour déterminer les tâches à exécuter est stocké ici. Il existe un fichier .run-once qui indique si le service a déjà été exécuté après Sysprep (donc les tâches avec une fréquence d’une fois seront ignorées lors de la prochaine exécution). Ce sous-répertoire inclut un state.json et previous-state.json pour suivre l’état de chaque tâche.

  • sysprep — Sysprep

    Ce répertoire contient des fichiers qui sont utilisés pour déterminer les opérations à effectuer par Sysprep lorsqu’il crée une AMI Windows personnalisée qui peut être réutilisée.

Configurer EC2Launch v2 avec la CLI

Vous pouvez utiliser la CLI (CLI) pour configurer vos paramètres EC2Launch et gérer le service. La section suivante contient des descriptions et des informations d’utilisation des commandes CLI que vous pouvez utiliser pour gérer EC2Launch v2.

collect-logs

Collecte les fichiers journaux pour EC2Launch, compile les fichiers et les place dans un répertoire spécifié.

Exemple

ec2launch collect-logs -o C:\Mylogs.zip

Utilisation

ec2launch collect-logs [flags]

Indicateurs

-h, --help

aide pour collect-logs

-o, --output string

chemin d’accès aux fichiers journaux de sortie compressés

get-agent-config

Imprime agent-config.yml au format spécifié (JSON ou YAML). Si aucun format n’est spécifié, agent-config.yml est imprimé dans le format précédemment spécifié.

Exemple

ec2launch get-agent-config -f json

Exemple 2

Les PowerShell commandes suivantes indiquent comment modifier et enregistrer le agent-config fichier au format JSON.

$config = & "$env:ProgramFiles/Amazon/EC2Launch/EC2Launch.exe" --format json | ConvertFrom-Json
$jumboFrame =@"
{
   "task": "enableJumboFrames"
}
"@
$config.config | %{if($_.stage -eq 'postReady'){$_.tasks += (ConvertFrom-Json -InputObject $jumboFrame)}}
$config | ConvertTo-Json -Depth 6 | Out-File -encoding UTF8
$env:ProgramData/Amazon/EC2Launch/config/agent-config.yml

Utilisation

ec2launch get-agent-config [flags]

Indicateurs

-h, --help

aide pour get-agent-config

-f, --format string

format de sortie du fichier agent-config : json, yaml

list-volumes

Répertorie tous les volumes de stockage attachés à l’instance, y compris les volumes éphémères et EBS.

Exemple

ec2launch list-volumes

Utilisation

ec2launch list-volumes

Indicateurs

-h, --help

aide pour list-volumes

reset

L’objectif principal de cette tâche est de réinitialiser l’agent pour sa prochaine exécution. Pour ce faire, la commande reset supprime toutes les données d’état de l’agent pour EC2Launch v2 du répertoire EC2Launch local (consultez Structure du répertoire EC2Launch v2). Reset supprime éventuellement le service et les journaux Sysprep.

Le comportement des scripts dépend du mode dans lequel l’agent exécute les scripts : en ligne ou détaché.

En ligne (par défaut)

L’agent EC2Launch v2 exécute les scripts un par un (detach: false). Il s’agit du paramètre par défaut.

Note

Lorsque votre script en ligne émet une commande reset ou sysprep, il s’exécute immédiatement et réinitialise l’agent. La tâche en cours se termine, puis l’agent s’arrête sans exécuter d’autres tâches.

Par exemple, si la tâche qui émet la commande aurait été suivie d’une tâche startSsm (incluse par défaut après l’exécution des données utilisateur), la tâche ne s’exécute pas et le service Systems Manager ne démarre jamais.

Detached

L’agent EC2Launch v2 exécute des scripts simultanément avec d’autres tâches (detach: true).

Note

Lorsque votre script détaché émet une commande reset ou sysprep, ces commandes attendent que l’agent ait terminé leur exécution avant de s’exécuter. Les tâches exécutées après executeScript se poursuivront.

Exemple

ec2launch reset -c

Utilisation

ec2launch reset [flags]

Indicateurs

-c, --clean

nettoie les journaux d’instance avant la reset

-h, --help

aide pour reset

run

Exécutions d’EC2Launch v2.

Exemple

ec2launch run

Utilisation

ec2launch run [flags]

Indicateurs

-h, --help

aide pour run

status

Obtient le statut de l’agent EC2Launch v2. Il est possible de bloquer le processus jusqu’à ce que l’agent soit terminé. Le code de sortie du processus détermine l’état de l’agent :

  • 0 : l’agent a été exécuté avec succès.

  • 1 : l’agent a été exécuté et a échoué.

  • 2 : l’agent est toujours en cours d’exécution.

  • 3 : l’agent est dans un état inconnu. L’état de l’agent n’est pas en cours d’exécution ou arrêté.

  • 4 : une erreur s’est produite lors de la tentative de récupération de l’état de l’agent.

  • 5 : l’agent n’est pas en cours d’exécution et l’état de la dernière exécution connue est inconnu. Cela peut signifier :

    • qu’à la fois state.json et previous-state.json sont supprimés.

    • que previous-state.json est corrompu.

    Il s’agit de l’état de l’agent après l’exécution de la commande reset.

Exemple :

ec2launch status -b

Utilisation

ec2launch status [flags]

Indicateurs

-b,--block

bloque le processus jusqu’à la fin de l’exécution de l’agent

-h,--help

aide pour status

sysprep

L’objectif principal de cette tâche est de réinitialiser l’agent pour sa prochaine exécution. Pour ce faire, la commande sysprep réinitialise l’état de l’agent, met à jour le fichier unattend.xml, désactive RDP et exécute Sysprep.

Le comportement des scripts dépend du mode dans lequel l’agent exécute les scripts : en ligne ou détaché.

En ligne (par défaut)

L’agent EC2Launch v2 exécute les scripts un par un (detach: false). Il s’agit du paramètre par défaut.

Note

Lorsque votre script en ligne émet une commande reset ou sysprep, il s’exécute immédiatement et réinitialise l’agent. La tâche en cours se termine, puis l’agent s’arrête sans exécuter d’autres tâches.

Par exemple, si la tâche qui émet la commande aurait été suivie d’une tâche startSsm (incluse par défaut après l’exécution des données utilisateur), la tâche ne s’exécute pas et le service Systems Manager ne démarre jamais.

Detached

L’agent EC2Launch v2 exécute des scripts simultanément avec d’autres tâches (detach: true).

Note

Lorsque votre script détaché émet une commande reset ou sysprep, ces commandes attendent que l’agent ait terminé leur exécution avant de s’exécuter. Les tâches exécutées après executeScript se poursuivront.

Exemple :

ec2launch sysprep

Utilisation

ec2launch sysprep [flags]

Indicateurs

-c,--clean

nettoie les journaux d’instance avant la sysprep

-h,--help

aide pour Sysprep

-s,--shutdown

arrête l’instance après l’exécution de sysprep

valider

Valide le fichier agent-config C:\ProgramData\Amazon\EC2Launch\config\agent-config.yml.

Exemple

ec2launch validate

Utilisation

ec2launch validate [flags]

Indicateurs

-h , --help

aide pour validate

version

Obtient la version exécutable.

Exemple

ec2launch version

Utilisation

ec2launch version [flags]

Indicateurs

-h, --help

aide pour version

fond d’écran

Définit le nouveau fond d’écran sur le chemin d’écran fourni (fichier .jpg) et affiche les détails de l’instance sélectionnée.

Syntaxe

ec2launch wallpaper ^
--path="C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg" ^
--all-tags ^
--attributes=hostName,instanceId,privateIpAddress,publicIpAddress,instanceSize,availabilityZone,architecture,memory,network

Inputs

Paramètres
--allowed-tags [tag-name-1, tag-name-n]

(Facultatif) Tableau JSON codé en Base64 contenant les noms des balises d’instance à afficher sur le fond d’écran. Vous pouvez utiliser cette balise ou l’option --all-tags, mais pas les deux.

--attributes attribute-string-1, attribute-string-n

(Facultatif) Une liste de chaînes d’attributs wallpaper séparées par des virgules pour appliquer des paramètres au fond d’écran.

[--path | -p] path-string

(Obligatoire) Spécifie le chemin du fichier image d’arrière-plan wallpaper.

Indicateurs
--all-tags

(Facultatif) Affiche toutes les balises d’instance sur le fond d’écran. Vous pouvez utiliser cette balise ou l’option --allowed-tags, mais pas les deux.

[--help | -h]

Affiche l’aide concernant la commande wallpaper.

Configuration de tâche EC2Launch v2

Cette section inclut les schémas de configuration, les tâches, les détails et les exemples pour agent-config.yml et les données utilisateur.

Schéma : agent-config.yml

La structure du fichier agent-config.yml est illustrée ci-dessous. Notez qu’une tâche ne peut pas être répétée dans la même étape. Pour connaître les propriétés des tâches, consultez les descriptions de tâches suivantes.

Structure du document : agent-config.yml

JSON

{
	"version": "1.0",
	"config": [
		{
			"stage": "string",
			"tasks": [
				{
					"task": "string",
					"inputs": {
						...
					}
				},
				...
			]
		},
		...
	]
}

YAML

version: 1.0
config:
- stage: string
  tasks:
  - task: string
	inputs:
	  ...
  ...
...

Exemple : agent-config.yml

L’exemple suivant montre les paramètres du fichier de configuration agent-config.yml.

version: 1.0
config:
- stage: boot
  tasks:
  - task: extendRootPartition
- stage: preReady
  tasks:
  - task: activateWindows
    inputs:
      activation:
        type: amazon
  - task: setDnsSuffix
    inputs:
      suffixes:
      - $REGION.ec2-utilities.amazonaws.com
  - task: setAdminAccount
    inputs:
      password:
        type: random
  - task: setWallpaper
    inputs:
      path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
      attributes:
      - hostName
      - instanceId
      - privateIpAddress
      - publicIpAddress
      - instanceSize
      - availabilityZone
      - architecture
      - memory
      - network
- stage: postReady
  tasks:
  - task: startSsm

Schéma : données utilisateur

Les exemples JSON et YAML suivants illustrent la structure du document pour les données utilisateur. Amazon EC2 analyse chaque tâche nommée du tableau tasks que vous spécifiez dans le document. Chaque tâche possède son propre ensemble de propriétés et d’exigences. Pour obtenir des détails, veuillez consulter le Définitions de tâche.

Note

Une tâche ne doit apparaître qu’une seule fois dans le tableau des tâches de données utilisateur.

Structure du document : données utilisateur

JSON

{
	"version": "1.1",
	"tasks": [
		{
			"task": "string",
			"inputs": {
				...
			},
		},
		...
	]
}

YAML

version: 1.1
tasks:
- task: string
  inputs:
    ...
...

Exemple : données utilisateur

Pour plus d’informations sur les rôles d’utilisateur, consultez Comment Amazon EC2 gère les données utilisateur pour les instances Windows.

L'exemple de document YAML suivant montre un PowerShell script qu'EC2Launch v2 exécute sous forme de données utilisateur pour créer un fichier.

version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

Vous pouvez utiliser un format XML pour les données utilisateur compatible avec les versions précédentes de l’agent de lancement. EC2Launch v2 exécute le script en tant que tâche executeScript dans l’étape UserData. Pour se conformer au comportement d’EC2Launch v1 et d’EC2Config, le script de données utilisateur s’exécute par défaut en tant que processus attaché/en ligne.

Vous pouvez ajouter des balises facultatives pour personnaliser l’exécution de votre script. Par exemple, pour exécuter le script de données utilisateur lors du redémarrage de l’instance et lors du lancement de l’instance, vous pouvez utiliser la balise suivante :

<persist>true</persist>

Exemple :

<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 transmis, 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>

Pour exécuter un script de données utilisateur XML en tant que processus détaché, ajoutez la balise suivante à vos données utilisateur.

<detach>true</detach>

Exemple :

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

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

Journal des modifications : données utilisateur

Le tableau suivant répertorie les modifications apportées aux données utilisateur et les recoupe à la version de l’agent EC2Launch v2 qui s’applique.

Version des données utilisateur Détails Présenté dans
1.1

  • Les tâches relatives aux données utilisateur s’exécutent avant l’étape PostReady dans le fichier de configuration de l’agent.

  • Exécute les données utilisateur avant de démarrer l’agent Systems Manager (même comportement que EC2Launch v1 et EC2Config).*

 EC2Launch v2 version 2.0.1245
1.0

  • Deviendra obsolète.

  • Les tâches relatives aux données utilisateur s’exécutent après l’étape PostReady dans le fichier de configuration de l’agent. Ce n’est pas rétrocompatible avec EC2Launch v1.

  • Affecté par une condition de concurrence entre les tâches de démarrage et de données utilisateur de l’agent Systems Manager.

 EC2Launch v2 version 2.0.0

* Lorsqu’il est utilisé avec le fichier agent-config.yml par défaut.

Définitions de tâche

Chaque tâche possède son propre ensemble de propriétés et d’exigences. Pour plus de détails, consultez les tâches individuelles à inclure dans votre document.

activateWindows

Active Windows sur un ensemble de AWS KMS serveurs. L’activation est ignorée si l’instance est détectée comme étant de type Apportez votre propre licence (BYOL).

Fréquence — Une fois

AllowedStages — [PreReady]

Entrées —

activation : (carte)

type : type d’activation (string) à utiliser, défini sur amazon

Exemple

task: activateWindows
inputs:
  activation:
    type: amazon

enableJumboFrames

Active les trames Jumbo, qui augmentent l’unité de transmission maximale (MTU) de la carte réseau. Pour plus d’informations, consultez Trames jumbo (MTU de 9001).

Fréquence — Toujours

AllowedStages — [PostReady, UserData]

Entrées — Aucune

Exemple

task: enableJumboFrames

enableOpenSsh

Active Windows OpenSSH et ajoute la clé publique de l’instance au dossier des clés autorisées.

Fréquence — Une fois

AllowedStages — [PreReady, UserData]

Entrées — Aucune

Exemple

L’exemple suivant montre comment activer OpenSSH sur une instance et ajouter la clé publique de l’instance au dossier des clés autorisées. Cette configuration fonctionne uniquement sur les instances exécutant Windows Server 2019 et versions ultérieures.

task: enableOpenSsh

executeProgram

Exécute un programme avec des arguments facultatifs et une fréquence spécifiée.

Étapes : vous pouvez exécuter la tâche executeProgram pendant les étapes PreReady, PostReady et UserData.

Fréquence : configurable, voir Entrées.

Inputs

Vous pouvez configurer les paramètres d’exécution comme suit :

fréquence (chaîne)

(Obligatoire) Spécifiez exactement l’une des valeurs suivantes :

  • once

  • always

chemin (chaîne)

(Obligatoire) Le chemin d’accès au fichier de l’exécutable à exécuter.

arguments (liste de chaînes)

(Facultatif) Liste d’arguments séparés par des virgules à fournir au programme en entrée.

runAs (chaîne)

(Obligatoire) Doit être défini sur localSystem

Sortie

Toutes les tâches écrivent des entrées du fichier journal dans le fichier agent.log. Les résultats supplémentaires de la tâche executeProgram sont stockés séparément dans un dossier nommé dynamiquement, comme suit :

%LocalAppData%\Temp\EC2Launch#########\outputfilename.tmp

Le chemin exact vers les fichiers de sortie est inclus dans le fichier agent.log, par exemple :

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Fichiers de sortie pour la tâche executeProgram
ExecuteProgramInputs.tmp

Contient le chemin de l’exécutable et tous les paramètres d’entrée que la tâche executeProgram lui transmet lors de son exécution.

Output.tmp

Contient la sortie d’exécution du programme exécuté par la tâche executeProgram.

Err.tmp

Contient les messages d’erreur d’exécution du programme exécuté par la tâche executeProgram.

Exemples

Les exemples suivants montrent comment exécuter un fichier exécutable à partir d’un répertoire local sur une instance avec la tâche executeProgram.

Exemple 1 : configuration d’un exécutable avec un seul argument

Cet exemple montre une tâche executeProgram qui exécute un exécutable d’installation en mode silencieux.

task: executeProgram
inputs:
- frequency: always
  path: C:\Users\Administrator\Desktop\setup.exe
  arguments: ['-quiet']
Exemple 2 : exécutable VLC avec deux arguments

Cet exemple montre une tâche executeProgram qui exécute un fichier exécutable VLC avec deux arguments transmis en tant que paramètres d’entrée.

task: executeProgram
inputs:
- frequency: always
  path: C:\vlc-3.0.11-win64.exe 
  arguments: ['/L=1033','/S']
  runAs: localSystem

executeScript

Exécute un script avec des arguments facultatifs et une fréquence spécifiée. Le comportement des scripts dépend du mode dans lequel l’agent exécute les scripts : en ligne ou détaché.

En ligne (par défaut)

L’agent EC2Launch v2 exécute les scripts un par un (detach: false). Il s’agit du paramètre par défaut.

Note

Lorsque votre script en ligne émet une commande reset ou sysprep, il s’exécute immédiatement et réinitialise l’agent. La tâche en cours se termine, puis l’agent s’arrête sans exécuter d’autres tâches.

Par exemple, si la tâche qui émet la commande aurait été suivie d’une tâche startSsm (incluse par défaut après l’exécution des données utilisateur), la tâche ne s’exécute pas et le service Systems Manager ne démarre jamais.

Detached

L’agent EC2Launch v2 exécute des scripts simultanément avec d’autres tâches (detach: true).

Note

Lorsque votre script détaché émet une commande reset ou sysprep, ces commandes attendent que l’agent ait terminé leur exécution avant de s’exécuter. Les tâches exécutées après executeScript se poursuivront.

Étapes : vous pouvez exécuter la tâche executeScript pendant les étapes PreReady, PostReady et UserData.

Fréquence : configurable, voir Entrées.

Inputs

Vous pouvez configurer les paramètres d’exécution comme suit :

fréquence (chaîne)

(Obligatoire) Spécifiez exactement l’une des valeurs suivantes :

  • once

  • always

type (chaîne)

(Obligatoire) Spécifiez exactement l’une des valeurs suivantes :

  • batch

  • powershell

arguments (liste de chaînes)

(Facultatif) Une liste d’arguments de chaîne à passer au shell. Ce paramètre n’est pas pris en charge pour type: batch. Si aucun argument n'est transmis, EC2Launch v2 ajoute l'argument suivant par défaut :. -ExecutionPolicy Unrestricted

contenu (chaîne)

(Obligatoire) Contenu du script.

runAs (chaîne)

(Obligatoire) Spécifiez exactement l’une des valeurs suivantes :

  • admin

  • localSystem

detach (booléen)

(Facultatif) L’agent EC2Launch v2 exécute par défaut les scripts un par un (detach: false). Pour exécuter le script en même temps que d’autres tâches, définissez la valeur sur true (detach: true).

Note

Codes de sortie de script (y compris 3010) n’ont aucun effet lorsque detach a la valeur true.

Sortie

Toutes les tâches écrivent des entrées du fichier journal dans le fichier agent.log. Les résultats supplémentaires du script exécuté par la tâche executeScript sont stockés séparément dans un dossier nommé dynamiquement, comme suit :

%LocalAppData%\Temp\EC2Launch#########\outputfilename.ext

Le chemin exact vers les fichiers de sortie est inclus dans le fichier agent.log, par exemple :

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Fichiers de sortie pour la tâche executeScript
UserScript.ext

Contient le script exécuté par la tâche executeScript. L’extension de fichier dépend du type de script que vous avez spécifié dans le paramètre type de la tâche executeScript, comme suit :

  • Si le type est batch, l’extension du fichier est .bat.

  • Si le type est powershell, l’extension du fichier est .ps1.

Output.tmp

Contient la sortie d’exécution du script exécuté par la tâche executeScript.

Err.tmp

Contient les messages d’erreur d’exécution du script exécuté par la tâche executeScript.

Exemples

Les exemples suivants montrent comment exécuter un script en ligne avec la tâche executeScript.

Exemple 1 : fichier texte de sortie Hello World

Cet exemple montre une executeScript tâche qui exécute un PowerShell script pour créer un fichier texte « Hello world » sur le C: lecteur.

task: executeScript
inputs:
- frequency: always
  type: powershell
  runAs: admin
  content: |-
    New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
    Set-Content 'C:\PowerShellTest.txt' "Hello world"
Exemple 2 : exécuter deux scripts

Cet exemple montre que la tâche executeScript peut exécuter plusieurs scripts et que le type de script ne doit pas nécessairement correspondre.

Le premier script (type: powershell) écrit un résumé des processus en cours d’exécution sur l’instance dans un fichier texte situé sur le lecteur C:.

Le second script (batch) écrit les informations système dans le fichier Output.tmp.

task: executeScript
inputs:
- frequency: always
  type: powershell
  content: |
    Get-Process | Out-File -FilePath C:\Process.txt
  runAs: localSystem
- frequency: always
  type: batch
  content: |
    systeminfo
Exemple 3 : configuration d’un système idempotent avec redémarrages

Cet exemple montre une tâche executeScript qui exécute un script idempotent pour effectuer la configuration système suivante avec un redémarrage entre chaque étape :

  • Renommer l’ordinateur.

  • Joindre l’ordinateur au domaine.

  • Activer Telnet.

Le script garantit que chaque opération ne s’exécute qu’une seule fois. Cela empêche une boucle de redémarrage et rend le script idempotent.

task: executeScript
inputs:
- frequency: always
  type: powershell
  runAs: localSystem
  content: |-
    $name = $env:ComputerName
     if ($name -ne $desiredName) {
       Rename-Computer -NewName $desiredName
       exit 3010
     }
     $domain = Get-ADDomain
     if ($domain -ne $desiredDomain) 
     {
       Add-Computer -DomainName $desiredDomain
       exit 3010
     }
    $telnet = Get-WindowsFeature -Name Telnet-Client
    if (-not $telnet.Installed)
    {
      Install-WindowsFeature -Name "Telnet-Client"
      exit 3010 
    }

extendRootPartition

Étend le volume racine pour utiliser tout l’espace disponible sur le disque.

Fréquence — Une fois

AllowedStages — [Boot]

Entrées — Aucune

Exemple 

task: extendRootPartition

initializeVolume

Initialise les volumes vides attachés à l’instance afin qu’ils soient activés et partitionnés. L’agent de lancement ignore l’initialisation s’il détecte que le volume n’est pas vide. Un volume est considéré comme vide si les 4 premiers Kio d’un volume sont vides ou si un volume n’a pas de disposition de lecteur reconnaissable par Windows.

Le paramètre d’entrée letter est toujours appliqué lors de l’exécution de cette tâche, que le lecteur soit déjà initialisé ou non.

La tâche initializeVolume effectue ensuite les actions suivantes.

  • Définissez les attributs de disque offline et readonly sur False.

  • Créez une partition. Si aucun type de partition n’est spécifié dans le paramètre d’entrée partition, les valeurs par défaut suivantes s’appliquent :

    • Si la taille de disque est inférieure à 2 To, définissez le type de partition sur mbr.

    • Si la taille de disque est supérieure ou égale à 2 To, définissez le type de partition sur gpt.

  • Formatez le volume au format NTFS.

  • Définissez l’étiquette du volume comme suit :

    • Utilisez la valeur du paramètre d’entrée name, le cas échéant.

    • Si le volume est éphémère et qu’aucun nom n’a été spécifié, définissez l’étiquette du volume sur Temporary Storage Z.

  • Si le volume est éphémère (SSD ou HDD, pas Amazon EBS), créez un fichier Important.txt à la racine du volume avec le contenu suivant :

    This is an 'Instance Store' disk and is provided at no additional charge.

*This disk offers increased performance since it is local to the host
*The number of Instance Store disks available to an instance vary by instance type
*DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY

For more information, please refer to: Stockage d’instances Amazon EC2.

  • Réglez la lettre de lecteur sur la valeur spécifiée dans le paramètre d’entrée letter.

Étapes : vous pouvez exécuter la tâche initializeVolume pendant les étapes PostReady et UserData.

Fréquence : toujours.

Inputs

Vous pouvez configurer les paramètres d’exécution comme suit :

appareils (liste de cartes)

(Condition) Configuration pour chaque appareil initialisé par l’agent de lancement. Ceci est obligatoire si le paramètre d’entrée initialize est défini sur devices.

  • appareil (chaîne, obligatoire) : identifie l’appareil lors de la création de l’instance. Par exemple, xvdb, xvdf ou \dev\nvme0n1.

  • lettre (chaîne, facultatif) : un caractère. La lettre de lecteur à attribuer.

  • nom (chaîne, facultatif) : le nom de volume à attribuer.

  • partition (chaîne, facultatif) : spécifiez l’une des valeurs suivantes pour le type de partition à créer, ou laissez l’agent de lancement par défaut en fonction de la taille du volume :

    • mbr

    • tpt

initialiser (chaîne)

(Obligatoire) Spécifiez exactement l’une des valeurs suivantes :

  • all

  • devices

Exemples

Voici des exemples de configurations d’entrée pour la tâche initializeVolume.

Exemple 1 : Initialiser deux volumes sur une instance

Cet exemple montre une tâche initializeVolume qui initialise deux volumes secondaires sur une instance. L’appareil nommé DataVolume2 dans l’exemple est éphémère.

task: initializeVolume
inputs:
  initialize: devices
  devices:
  - device: xvdb
    name: DataVolume1
    letter: D
    partition: mbr
  - device: /dev/nvme0n1
    name: DataVolume2
    letter: E
    partition: gpt
Exemple 2 : Initialiser des volumes EBS attachés à une instance

Cet exemple montre une tâche initializeVolume qui initialise tous les volumes EBS vides qui sont attachés à l’instance.

task: initializeVolume
inputs:
  initialize: all

optimizeEna

Optimise les paramètres ENA en fonction du type d’instance actuel ; peut redémarrer l’instance.

Fréquence — Toujours

AllowedStages — [PostReady, UserData]

Entrées — Aucune

Exemple 

task: optimizeEna

ensemble AdminAccount

Définit les attributs du compte d’administrateur par défaut créé sur la machine locale.

Fréquence — Une fois

AllowedStages — [PreReady]

Entrées —

name : nom (chaîne) du compte administrateur

password : (carte)

type : stratégie (chaîne) pour définir le mot de passe, comme static, random ou doNothing

data : (chaîne) stocke les données si le champ type est statique

Exemple

task: setAdminAccount
inputs:
  name: Administrator
  password:
    type: random

setDnsSuffix

Ajoute les suffixes DNS à la liste des suffixes de recherche. Seuls les suffixes qui n’existent pas déjà sont ajoutés à la liste. Pour plus d'informations sur la façon dont les agents de lancement définissent les suffixes DNS, consultez. Configurer le suffixe DNS pour les agents de lancement Windows

Fréquence — Toujours

AllowedStages — [PreReady]

Entrées —

suffixes : (liste de chaînes) liste d’un ou plusieurs suffixes DNS valides ; les variables de substitution valides sont $REGION et $AZ

Exemple

task: setDnsSuffix
inputs:
  suffixes:
  - $REGION.ec2-utilities.amazonaws.com

setHostName

Définit le nom d’hôte de l’ordinateur sur une chaîne personnalisée ou, si hostName n’est pas spécifié, l’adresse IPv4 privée.

Fréquence — Toujours

AllowedStages — [PostReady, UserData]

Entrées —

hostName : (chaîne) nom d’hôte facultatif, qui doit être formaté comme suit.

  • Doit contenir 15 caractères ou moins

  • Doit contenir uniquement des caractères alphanumériques (a-z, A-Z, 0-9) et tiret (-).

  • Ne doit pas être entièrement composé de caractères numériques.

reboot : (booléen) indique si un redémarrage est autorisé lorsque le nom d’hôte est modifié

Exemple

task: setHostName
inputs:
  reboot: true

setWallpaper

Crée le fichier de raccourci setwallpaper.lnk dans le dossier de démarrage de chaque utilisateur existant, sauf pour Default User. Ce fichier de raccourci s’exécute lorsque l’utilisateur se connecte pour la première fois après le démarrage de l’instance. Il configure l’instance avec un fond d’écran personnalisé qui affiche les attributs de l’instance.

Le chemin du fichier de raccourci est le suivant :

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk
Note

Lorsque vous supprimez la tâche setWallpaper, ce fichier de raccourci n’est pas supprimé. Pour plus d’informations, consultez La tâche setWallpaper n’est pas activée, mais le fond d’écran se réinitialise au redémarrage.

Étapes : vous pouvez configurer le fond d’écran au cours des étapes PreReady et UserData.

Fréquence : always

Configuration du fond d’écran

Vous pouvez utiliser les paramètres suivants pour configurer votre fond d’écran.

Inputs

Paramètres d’entrée que vous fournissez et attributs que vous pouvez définir pour configurer votre fond d’écran :

attributs (liste de chaînes)

(Facultatif) Vous pouvez ajouter un ou plusieurs des attributs suivants à votre fond d’écran :

  • architecture

  • availabilityZone

  • hostName

  • instanceId

  • instanceSize

  • memory

  • network

  • privateIpAddress

  • publicIpAddress

instanceTags

(Facultatif) Vous pouvez utiliser exactement l’une des options suivantes pour ce paramètre.

  • AllTags(string) — Ajoutez toutes les balises d'instance à votre fond d'écran.

    instanceTags: AllTags

  • instanceTags (liste de chaînes) – Spécifiez une liste de noms de balises d’instance à ajouter à votre fond d’écran. Par exemple :

    instanceTags:
  - Tag 1
  - Tag 2
chemin (chaîne)

(Obligatoire) Le chemin du nom du fichier image au format .jpg local à utiliser pour votre image de fond d’écran.

Exemple

L’exemple suivant montre les entrées de configuration du fond d’écran qui définissent le chemin du fichier pour l’image d’arrière-plan du fond d’écran, ainsi que les balises d’instance nommées Tag 1 et Tag 2, ainsi que les attributs qui incluent le nom d’hôte, l’ID d’instance et les adresses IP privées et publiques de l’instance.

task: setWallpaper
inputs:
  path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
  attributes:
  - hostName
  - instanceId
  - privateIpAddress
  - publicIpAddress
  instanceTags:
  - Tag 1
  - Tag 2
Note

Vous devez activer les balises dans les métadonnées pour afficher les balises sur le fond d’écran. Pour plus d’informations sur les balises et métadonnées d’instance, consultez Utiliser les identifications d’instance dans les métadonnées d’instance.

startSsm

Démarrez le service Systems Manager (SSM) après Sysprep.

Fréquence — Toujours

AllowedStages — [PostReady, UserData]

Entrées — Aucune

Exemple

task: startSsm

sysprep

Réinitialise l’état du service, met à jour unattend.xml, désactive RDP et exécute Sysprep. Cette tâche s’exécute uniquement une fois que toutes les autres tâches sont terminées.

Fréquence — Une fois

AllowedStages — [UserData]

Entrées —

clean : (booléen) nettoie les journaux d’instance avant d’exécuter Sysprep

shutdown : (booléen) arrête l’instance après avoir exécuté Sysprep

Exemple

task: sysprep
inputs:
  clean: true
  shutdown: true

writeFile

Écrit un fichier vers une destination.

Fréquence — voir Entrées

AllowedStages — [PostReady, UserData]

Entrées —

frequency : (chaîne) once ou always

destination : (chaîne) chemin vers lequel écrire le contenu

content : (chaîne) texte à écrire dans la destination

Exemple

task: writeFile
inputs:
- frequency: once
  destination: C:\Users\Administrator\Desktop\booted.txt
  content: Windows Has Booted

Codes de sortie EC2Launch v2 et redémarrages

Vous pouvez utiliser EC2Launch v2 pour définir la manière dont les codes de sortie sont gérés par vos scripts. Par défaut, le code de sortie de la dernière commande exécutée dans un script est signalé comme le code de sortie pour l’ensemble du script. Par exemple, si un script inclut trois commandes et que la première commande échoue mais que les suivantes réussissent, le statut d’exécution est signalé comme success étant donné que la commande finale a réussi.

Si vous souhaitez qu’un script redémarre une instance, vous devez spécifier exit 3010 dans votre script, même lorsque le redémarrage est la dernière étape de votre script. exit 3010 indique à EC2Launch v2 de redémarrer l’instance et d’appeler à nouveau le script jusqu’à ce qu’il renvoie un code de sortie qui n’est pas 3010, ou jusqu’à ce que le nombre maximum de redémarrage ait été atteint. EC2Launch v2 permet un maximum de 5 redémarrages par tâche. Si vous tentez de redémarrer une instance à partir d’un script à l’aide d’un mécanisme différent, tel que Restart-Computer, le statut d’exécution du script sera incohérent. Par exemple, il peut être bloqué dans une boucle de redémarrage ou ne pas effectuer le redémarrage.

Si vous utilisez un format de données utilisateur XML qui est compatible avec les anciens agents, les données utilisateur peuvent s’exécuter plus de fois que vous le souhaitez. Pour plus d’informations, consultez Le service exécute les données utilisateur plus d’une fois dans la section de résolution des problèmes.

EC2Launch v2 et Sysprep

Le service EC2Launch v2 exécute Sysprep, un outil Microsoft qui vous permet de créer une AMI Windows personnalisée qui peut être réutilisée. Quand EC2Launch v2 appelle Sysprep, il utilise les fichiers présents dans %ProgramData%\Amazon\EC2Launch pour déterminer les opérations à effectuer. Vous pouvez modifier ces fichiers indirectement à l’aide de la boîte de dialogue des paramètres EC2Launch ou directement à l’aide d’un éditeur YAML ou d’un éditeur de texte. Toutefois, certains paramètres avancés ne sont pas disponibles dans la boîte de dialogue Propriétés du service EC2Launch ; vous devez donc modifier ces entrées directement.

Si vous créez une AMI directement dans une instance après avoir mis à jour ses paramètres, ceux-ci sont appliqués à n’importe quelle instance lancée dans la nouvelle AMI. Pour plus d’informations sur la création d’une AMI, consultez Création d'une AMI basée sur Amazon EBS.