Planifier les associations Créer une association (console)Créer une association (ligne de commande)

Création d'associations

State Manager, une fonctionnalité de AWS Systems Manager, vous aide à maintenir vos AWS ressources dans un état qui vous permet de définir et de réduire la dérive de configuration. Pour ce faire, State Manager utilise des associations. Une association est une configuration que vous attribuez à vos AWS ressources. La configuration définit le statut que vous souhaitez conserver sur vos ressources. Par exemple, une association peut spécifier qu'un logiciel antivirus doit être installé et s'exécuter sur un nœud géré, ou que certains ports doivent être fermés.

Une association spécifie une planification indiquant quand appliquer la configuration et quelles sont les cibles de l'association. Par exemple, une association pour un logiciel antivirus peut s'exécuter une fois par jour sur tous les nœuds gérés d'un Compte AWS. Si le logiciel n'est pas installé sur un nœud, l'association pourrait demander à State Manager de l'installer. Si le logiciel est installé, mais que le service ne s'exécute pas, l'association pourrait demander à State Manager de démarrer le service.

Avertissement

Lorsque vous créez une association, vous pouvez choisir un groupe de AWS ressources de nœuds gérés comme cible pour l'association. Si un utilisateur, un groupe ou un rôle AWS Identity and Access Management (IAM) est autorisé à créer une association qui cible un groupe de ressources de nœuds gérés, cet utilisateur, ce groupe ou ce rôle contrôle automatiquement au niveau racine tous les nœuds du groupe. Seuls les administrateurs approuvés doivent être autorisés à créer des associations.

Objectifs des associations et contrôles du débit

Une association spécifie également quels nœuds gérés, ou cibles, doivent recevoir l'association. State Manager inclut plusieurs fonctions pour vous aider à cibler vos nœuds gérés et à contrôler la façon dont l'association est déployée sur ces cibles. Pour de plus amples informations sur les cibles et les contrôles du débit, consultez À propos des cibles et des contrôles du débit dans les associations State Manager.

Associations de balisage

Vous pouvez attribuer des balises à une association lorsque vous la créez à l'aide d'un outil de ligne de commande tel que le AWS CLI ou AWS Tools for PowerShell. L'ajout de balises à une association à l'aide de la console Systems Manager n'est pas pris en charge. Pour en savoir plus sur les identifications, consultez Balisage des ressources Systems Manager.

Exécuter les associations

Par défaut, State Manager exécute une association immédiatement après sa création, puis selon le calendrier que vous avez défini.

Le système exécute également les associations selon les règles suivantes :

State Manager tente d'exécuter l'association sur tous les nœuds spécifiés ou ciblés au cours d'un intervalle.
Si une association n'est pas exécutée au cours d'un intervalle (par exemple, parce qu'une valeur de simultanéité a limité par le nombre de nœuds pouvant traiter l'association simultanément), State Manager tente d'exécuter l'association lors du prochain intervalle.
State Manager exécute l'association après avoir modifié la configuration, les nœuds cibles, les documents ou les paramètres de l'association. Pour de plus amples informations, consultez Quand les associations sont-elles appliquées aux ressources ?.
State Manager enregistre un historique pour tous les intervalles ignorés. Vous pouvez consulter l'historique dans l'onglet Execution History (Historique d'exécution).

Planifier les associations

Vous pouvez planifier des associations pour qu'elles s'exécutent à des intervalles de base, par exemple toutes les 10 heures, ou vous pouvez créer des planifications plus avancées à l'aide d'expressions cron et rate personnalisées. Vous pouvez également empêcher les associations de s'exécuter lorsque vous les créez pour la première fois.

Utiliser les expressions cron et rate pour planifier les exécutions des associations

Outre les expressions cron ou rate standard, State Manager prend également en charge les expressions cron qui incluent un jour de la semaine et le signe numérique (#) pour désigner le ne jour d'un mois pour exécuter une association. Voici un exemple qui exécute un calendrier cron le troisième mardi de chaque mois à 23h30 : UTC

cron(30 23 ? * TUE#3 *)

Voici un exemple diffusé le deuxième jeudi de chaque mois à minuit UTC :

cron(0 0 ? * THU#2 *)

State Manager prend également en charge le signe (L) pour indiquer le dernier X jour du mois. Voici un exemple qui exécute un calendrier cron le dernier mardi de chaque mois à minuit UTC :

cron(0 0 ? * 3L *)

Pour contrôler davantage l'exécution d'une association, par exemple si vous souhaitez exécuter une association deux jours après le correctif mardi, vous pouvez spécifier un décalage. Un offset (décalage) définit le nombre de jours d'attente après le jour prévu pour exécuter une association. Par exemple, si vous avez spécifié une planification cron de cron(0 0 ? * THU#2 *), vous pouvez spécifier le numéro 3 dans le champ Schedule offset (Décalage de planification) pour exécuter l'association tous les dimanches après le deuxième jeudi du mois.

Note

Pour utiliser des décalages, vous devez sélectionner Appliquer l'association uniquement à l'intervalle Cron spécifié suivant dans la console ou vous devez spécifier le paramètre ApplyOnlyAtCronInterval dans la ligne de commande. Lorsque l'une de ces options est activée, State Manager n'exécute pas d'association immédiatement après sa création.

Pour plus d'informations sur les expressions de type cron et rate, consultez Référence : Expressions Cron et Rate pour Systems Manager.

Créer une association (console)

La procédure suivante décrit comment utiliser la console Systems Manager pour créer une association State Manager.

Important

Cette procédure décrit comment créer une association qui utilise un Command ou un Policy document pour cibler les nœuds gérés. Pour plus d'informations sur la création d'une association utilisant un runbook d'automatisation pour cibler des nœuds ou d'autres types de AWS ressources, consultezExécution des automatisations avec les associations State Manager.

Pour créer une association State Manager

Ouvrez la AWS Systems Manager console à l'adresse https://console.aws.amazon.com/systems-manager/.
Dans le panneau de navigation, sélectionnez State Manager.
Sélectionnez Créer une association.
Dans le champ Nom, spécifiez un nom.
Dans la liste Document, sélectionnez l'option en regard du nom d'un document. Notez le type de document. Cette procédure s'applique aux documents Policy et Command. Pour plus d'informations sur la création d'une association qui utilise un runbook Automation, consultez Exécution des automatisations avec les associations State Manager.

Important
State Manager ne prend pas en charge l'exécution d'associations utilisant une nouvelle version d'un document si ce document est partagé à partir d'un autre compte. State Manager exécute toujours la version default d'un document s'il est partagé depuis un autre compte, même si la console Systems Manager indique qu'une nouvelle version a été traitée. Si vous souhaitez exécuter une association à l'aide d'une nouvelle version d'un document partagé à partir d'un autre compte, vous devez définir la version du document sur default.
Pour Parameters (Paramètres), spécifiez les paramètres d'entrée requis.
(Facultatif) Choisissez une CloudWatch alarme à appliquer à votre association à des fins de surveillance.
Note
Notez les informations suivantes concernant ce passage.
- La liste des alarmes affiche 100 alarmes maximum. Si votre alarme ne figure pas dans la liste, utilisez le AWS Command Line Interface pour créer l'association. Pour de plus amples informations, veuillez consulter Créer une association (ligne de commande).
- Pour associer une CloudWatch alarme à votre commande, le IAM principal qui crée l'association doit être autorisé à effectuer l'iam:createServiceLinkedRoleaction. Pour plus d'informations sur les CloudWatch alarmes, consultez la section Utilisation des CloudWatch alarmes Amazon.
- Si votre alarme se déclenche, toute invocation ou automatisme de commande en attente ne s’exécute pas.
Pour Targets (Cibles), sélectionnez une option. Pour plus d'informations sur l'utilisation des cibles, consultez À propos des cibles et des contrôles du débit dans les associations State Manager.
Dans la section Specify schedule (Spécifier le programme), sélectionnez On Schedule (Selon le calendrier) ou No schedule (Pas de calendrier). Si vous sélectionnez On Schedule (Selon planification), utilisez les boutons fournis pour créer une planification de type cron ou rate pour l'association.

Si vous ne souhaitez pas que l'association s'exécute immédiatement après sa création, sélectionnez Appliquer l'association uniquement à l'intervalle Cron spécifié suivant.
(Facultatif) Dans le Schedule offset (Décalage de planification), spécifiez un nombre compris entre 1 et 6.
Dans la section Options avancées utilisez Compliance severity (Sévérité de la conformité) pour choisir un niveau de sévérité pour l'association, et utilisez Change Calendriers (Calendriers de modifications) pour choisir un calendrier des modifications pour l'association.

Les rapports de conformité indiquent si l'état de l'association est conforme ou non conforme, ainsi que le niveau de sévérité que vous spécifiez ici. Pour de plus amples informations, veuillez consulter A propos de la conformité des associations State Manager.

Le calendrier des modifications détermine l'instant d'exécution de l'association. Si le calendrier est fermé, l'association n'est pas appliquée. Si le calendrier est ouvert, l'association s'exécute en conséquence. Pour de plus amples informations, veuillez consulter AWS Systems Manager Change Calendar.
Dans la section Rate control (Contrôle du rythme), sélectionnez les options permettant de contrôler la façon dont l'association s'exécute sur plusieurs nœuds gérés. Pour de plus amples informations sur l'utilisation des contrôles de débit, consultez À propos des cibles et des contrôles du débit dans les associations State Manager.

Dans la section Simultanéité, sélectionnez une option :
- Sélectionnez targets (cibles) pour entrer un nombre absolu de cibles pouvant exécuter l'association simultanément.
- Sélectionnez percentage (pourcentage) pour saisir un pourcentage de l'ensemble de cibles pouvant exécuter l'association simultanément.
Dans la section Error threshold (Seuil d'erreurs), sélectionnez une option :
- Sélectionnez errors (erreurs) pour saisir un nombre absolu d'erreurs autorisées avant que State Manager ne cesse d'exécuter des associations sur des cibles supplémentaires.
- Sélectionnez percentage (pourcentage) pour saisir un pourcentage d'erreurs autorisées avant que State Manager ne cesse d'exécuter des associations sur des cibles supplémentaires.
(Facultatif) Dans Output options (Options de sortie), pour enregistrer la sortie de la commande dans un fichier, sélectionnez Enable writing to an S3 bucket (Autoriser l'écriture dans un compartiment S3) Saisissez les noms de compartiment et de préfixe (dossier) dans les zones.

Note
Les autorisations S3 qui permettent d'écrire les données dans un compartiment S3 sont celles du profil d'instance attribué au nœud géré, et non celles de l'IAMutilisateur effectuant cette tâche. Pour plus d'informations, consultez Configurer les autorisations d'instance requises pour Systems Manager ou Créer un rôle de IAM service pour un environnement hybride. En outre, si le compartiment S3 spécifié se trouve dans un autre compartiment Compte AWS, vérifiez que le profil d'instance ou le rôle de IAM service associé au nœud géré dispose des autorisations nécessaires pour écrire dans ce compartiment.

Voici les autorisations minimales requises pour activer la sortie Amazon S3 pour une association. Vous pouvez restreindre davantage l'accès en associant des IAM politiques aux utilisateurs ou aux rôles au sein d'un compte. Au minimum, un profil d'EC2instance Amazon doit avoir un IAM rôle dans la politique AmazonSSMManagedInstanceCore gérée et dans la politique en ligne suivante.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
        }
    ]
}
```
Pour des autorisations minimales, le compartiment Amazon S3 vers lequel s'effectue l'exportation doit disposer des paramètres par défaut définis par la console Amazon S3. Pour plus d'informations sur la création de compartiments Amazon S3, consultez Création d'un compartiment dans le Guide de l'utilisateur Amazon S3.

Note
APIles opérations initiées par le SSM document lors de l'exécution d'une association ne sont pas connectées AWS CloudTrail.
Sélectionnez Create Association (Créer une association).

Note

Si vous supprimez l'association que vous avez créée, celle-ci ne s'exécute plus sur aucune cible de cette association.

Créer une association (ligne de commande)

La procédure suivante décrit comment utiliser AWS CLI (sous Linux ou Windows) ou les outils PowerShell pour créer une State Manager association. Cette section présente plusieurs exemples qui montrent comment utiliser les cibles et les contrôles du débit. Les cibles et les contrôles du rythme vous permettent d'affecter une association à des dizaines ou des centaines de nœuds, tout en contrôlant l'exécution de ces associations. Pour de plus amples informations sur les cibles et les contrôles du débit, consultez À propos des cibles et des contrôles du débit dans les associations State Manager.

Important

Avant de commencer

Le paramètre targets est un tableau de critères de recherche qui cible les instances en utilisant une combinaison Key,Value (Clé-Valeur) que vous spécifiez. Si vous prévoyez de créer une association sur des dizaines ou des centaines de nœuds à l'aide du paramètre targets, passez en revue les options de ciblage suivantes avant de commencer la procédure.

Ciblez des nœuds spécifiques en spécifiant IDs


--targets Key=InstanceIds,Values=instance-id-1,instance-id-2,instance-id-3


--targets Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE

Cibler les instances à l'aide de balises


--targets Key=tag:tag-key,Values=tag-value-1,tag-value-2,tag-value-3


--targets Key=tag:Environment,Values=Development,Test,Pre-production

Ciblez des nœuds en utilisant AWS Resource Groups


--targets Key=resource-groups:Name,Values=resource-group-name


--targets Key=resource-groups:Name,Values=WindowsInstancesGroup

Ciblez toutes les instances dans les environnements actuels Compte AWS et Région AWS


--targets Key=InstanceIds,Values=*

Note

Notez les informations suivantes.

State Manager ne prend pas en charge l'exécution d'associations utilisant une nouvelle version d'un document si ce document est partagé à partir d'un autre compte. State Manager exécute toujours la version default d'un document s'il est partagé depuis un autre compte, même si la console Systems Manager indique qu'une nouvelle version a été traitée. Si vous souhaitez exécuter une association à l'aide d'une nouvelle version d'un document partagé à partir d'un autre compte, vous devez définir la version du document sur default.
Vous pouvez spécifier un maximum de cinq clés de balise en utilisant la AWS CLI. Si vous utilisez le AWS CLI, toutes les clés de balise spécifiées dans la create-association commande doivent être actuellement attribuées au nœud. Si elles ne le sont pas, State Manager ne parvient pas à cibler le nœud pour une association. Pour plus d'informations sur l'affectation d'identifications à vos nœuds, consultez Balisage des ressources Systems Manager.
Lorsque vous créez une association, vous spécifiez à quel moment le programme s'exécute. Spécifiez le programme à l'aide d'une expression de type cron ou rate. Pour plus d'informations sur les expressions de type cron et rate, consultez Expressions cron et rate pour les associations.

Créer une association

Installez et configurez le AWS CLI ou le AWS Tools for PowerShell, si ce n'est pas déjà fait.

Pour plus d'informations, consultez la section Installation ou mise à jour de la version la plus récente de l' AWS CLI et Installation d' AWS Tools for PowerShell.

Utilisez le format suivant pour créer une commande qui crée une association State Manager. Remplacez chacun example resource placeholder avec vos propres informations.

Linux & macOS


aws ssm create-association \
    --name document_name \
    --document-version version_of_document_applied \
    --instance-id instances_to_apply_association_on \
    --parameters (if any) \
    --targets target_options \
    --schedule-expression "cron_or_rate_expression" \
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets \
    --schedule-offset number_between_1_and_6 \
    --output-location s3_bucket_to_store_output_details \
    --association-name association_name \
    --max-errors a_number_of_errors_or_a_percentage_of_target_set \
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
    --compliance-severity severity_level \
    --calendar-names change_calendar_names \
    --target-locations aws_region_or_account \
    --tags "Key=tag_key,Value=tag_value"

Windows


aws ssm create-association ^
    --name document_name ^
    --document-version version_of_document_applied ^
    --instance-id instances_to_apply_association_on ^
    --parameters (if any) ^
    --targets target_options ^
    --schedule-expression "cron_or_rate_expression" ^
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets ^
    --schedule-offset number_between_1_and_6 ^
    --output-location s3_bucket_to_store_output_details ^
    --association-name association_name ^
    --max-errors a_number_of_errors_or_a_percentage_of_target_set ^
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
    --compliance-severity severity_level ^
    --calendar-names change_calendar_names ^
    --target-locations aws_region_or_account ^
    --tags "Key=tag_key,Value=tag_value"

PowerShell


New-SSMAssociation `
    -Name document_name `
    -DocumentVersion version_of_document_applied `
    -InstanceId instances_to_apply_association_on `
    -Parameters (if any) `
    -Target target_options `
    -ScheduleExpression "cron_or_rate_expression" `
    -ApplyOnlyAtCronInterval required_parameter_for_schedule_offsets `
    -ScheduleOffSet number_between_1_and_6 `
    -OutputLocation s3_bucket_to_store_output_details `
    -AssociationName association_name `
    -MaxError  a_number_of_errors_or_a_percentage_of_target_set
    -MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
    -ComplianceSeverity severity_level `
    -CalendarNames change_calendar_names `
    -TargetLocations aws_region_or_account `
    -Tags "Key=tag_key,Value=tag_value"

L'exemple suivant crée une association sur des nœuds labélisés avec "Environment,Linux". L'association utilise le AWS-UpdateSSMAgent document pour mettre à jour SSM Agent les nœuds ciblés à 2h00 UTC tous les dimanches matins. Cette association s'exécute simultanément sur 10 nœuds maximum à un moment donné. En outre, cette association cesse d'être exécutée sur des nœuds supplémentaires pour un intervalle d'exécution particulier si le nombre d'erreurs dépasse 5. Pour les rapports de conformité, cette association se voit attribuer un niveau de sévérité Medium (Moyenne).

L'exemple suivant cible le nœud IDs en spécifiant une valeur générique (*). Cela permet à Systems Manager de créer une association sur tous les nœuds de l'actuel Compte AWS et Région AWS. Cette association s'exécute simultanément sur 10 nœuds maximum à un moment donné. En outre, cette association cesse d'être exécutée sur des nœuds supplémentaires pour un intervalle d'exécution particulier si le nombre d'erreurs dépasse 5. Pour les rapports de conformité, cette association se voit attribuer un niveau de sévérité Medium (Moyenne). Cette association utilise un décalage de planification, ce qui signifie qu'elle s'exécute deux jours après la planification cron spécifiée. Elle inclut également le paramètre ApplyOnlyAtCronInterval, qui est requis pour utiliser le décalage de planification, ce qui signifie que l'association ne sera pas exécutée immédiatement après sa création.

L'exemple suivant crée une association sur des nœuds dans des groupes de ressources. Le groupe est nommé « HR-Department ». L'association utilise le AWS-UpdateSSMAgent document pour faire le point SSM Agent sur les nœuds ciblés à 2 h UTC tous les dimanches matins. Cette association s'exécute simultanément sur 10 nœuds maximum à un moment donné. En outre, cette association cesse d'être exécutée sur des nœuds supplémentaires pour un intervalle d'exécution particulier si le nombre d'erreurs dépasse 5. Pour les rapports de conformité, cette association se voit attribuer un niveau de sévérité Medium (Moyenne). Cette association s'exécute selon la planification Cron spécifiée. Il ne s'exécute pas immédiatement après la création de l'association.

L'exemple suivant crée une association qui s'exécute sur des nœuds balisés avec un ID de nœud spécifique. L'association utilise le document SSM Agent pour mettre à jour l'SSM Agent sur les nœuds ciblés une fois, lorsque le calendrier des modifications est ouvert. L'association vérifie l'état du calendrier lorsqu'elle s'exécute. Si le calendrier est fermé au moment du lancement et que l'association ne s'exécute qu'une seule fois, elle ne s'exécutera plus car la fenêtre d'exécution de l'association est passée. Si le calendrier est ouvert, l'association s'exécute en conséquence.

Note

Si vous ajoutez de nouveaux nœuds aux identifications ou aux groupes de ressources sur lesquels une association agit lorsque le calendrier des modifications est fermé, l'association est appliquée à ces nœuds une fois que le calendrier des modifications s'ouvre.

L'exemple suivant crée une association qui s'exécute sur des nœuds balisés avec un ID de nœud spécifique. L'association utilise le document SSM Agent pour mettre à jour SSM Agent sur les nœuds ciblés à 2 h chaque dimanche matin. Cette association s'exécute uniquement selon la planification cron spécifiée lorsque le calendrier des modifications est ouvert. Lorsque l'association est créée, elle vérifie l'état du calendrier. Si le calendrier est fermé, l'association n'est pas appliquée. Lorsque l'intervalle d'application de l'association commence à 2h00 le dimanche, l'association vérifie si le calendrier est ouvert. Si le calendrier est ouvert, l'association s'exécute en conséquence.

Note

Si vous supprimez l'association que vous avez créée, celle-ci ne s'exécute plus sur aucune cible de cette association. En outre, si vous avez spécifié le paramètre apply-only-at-cron-interval, vous pouvez réinitialiser cette option. Pour ce faire, spécifiez le paramètre no-apply-only-at-cron-interval lorsque vous mettez à jour l'association à partir de la ligne de commande. Ce paramètre force l'association à s'exécuter immédiatement après la mise à jour de l'association et selon l'intervalle spécifié.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Utilisation de cibles et du contrôle du débit

Modification d'une association