• Le AWS Systems Manager CloudWatch tableau de bord ne sera plus disponible après le 30 avril 2026. Les clients peuvent continuer à utiliser CloudWatch la console Amazon pour consulter, créer et gérer leurs CloudWatch tableaux de bord Amazon, comme ils le font aujourd'hui. Pour plus d'informations, consultez la [documentation Amazon CloudWatch Dashboard](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
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.
# Composants de document
Cette section comprend des informations sur les éléments qui composent les documents SSM.
**Topics**
+ [Schémas, fonctionnalités et exemples](documents-schemas-features.md)
+ [Éléments de données et paramètres](documents-syntax-data-elements-parameters.md)
+ [Référence de plug-in de document Command](documents-command-ssm-plugin-reference.md)
# Schémas, fonctionnalités et exemples
AWS Systems Manager Les documents (SSM) utilisent les versions de schéma suivantes.
+ Les documents de type `Command` peuvent utiliser la version de schéma 1.2, 2.0, et 2.2. Si vous utilisez des documents de schéma 1.2, nous vous recommandons de créer des documents qui utilisent la version de schéma 2.2.
+ Les documents de type `Policy` doivent utiliser la version de schéma 2.0 ou ultérieure.
+ Les documents de type `Automation` doivent utiliser la version de schéma 0.3.
+ Les documents de type `Session` doivent utiliser la version de schéma 1.0.
+ Vous pouvez créer des documents au format JSON ou YAML.
Pour plus d’informations sur le schéma de document `Session`, consultez [Schéma de document de session](session-manager-schema.md).
En utilisant la dernière version de schéma pour les documents `Command` et `Policy`, vous pouvez profiter des fonctions suivantes.
**Fonctionnalités d'un document de version de schéma 2.2**
| Fonctionnalité | Détails |
| --- | --- |
| Modification du document | Les documents peuvent désormais être mis à jour. Avec la version 1.2, la mise à jour d'un document nécessitait qu'il soit enregistré sous un autre nom. |
| Gestion automatique des versions | Toute mise à jour d'un document crée une nouvelle version. Il ne s'agit pas d'une version de schéma, mais d'une version du document. |
| Version par défaut | Si vous disposez de plusieurs versions d'un document, vous pouvez spécifier la version qui est le document par défaut. |
| Séquençage | Les plug-ins ou *étapes* dans un document s'exécutent dans l'ordre que vous avez spécifié. |
| Support multiplateforme | Le support multiplateforme vous permet de spécifier un système d'exploitation différent pour différents plugins dans le même document SSM. Le support multiplateforme utilise le même paramètre `precondition` dans une étape. |
| Interpolation des paramètres | L’interpolation consiste à insérer ou à remplacer une valeur de variable dans une chaîne. C’est comme si vous remplissiez un espace vide avec des valeurs réelles avant que la chaîne soit utilisée. Dans le contexte des documents SSM, l’interpolation des paramètres permet d’interpoler des paramètres de chaîne dans des variables d’environnement avant l’exécution des commandes, offrant ainsi une meilleure sécurité contre les injections de commandes. Si défini sur `ENV_VAR`, l’agent crée une variable d’environnement nommée `SSM_parameter-name` qui contient la valeur du paramètre. |
**Note**
Vous devez maintenir AWS Systems Manager SSM Agent vos instances à jour avec la dernière version afin d'utiliser les nouvelles fonctionnalités de Systems Manager et les fonctionnalités du document SSM. Pour de plus amples informations, veuillez consulter [Mise à jour de SSM Agent à l'aide de Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
Le tableau suivant répertorie les différences entre les versions majeures du schéma.
****
| Version 1.2 | Version 2.2 (dernière version) | Détails |
| --- | --- | --- |
| runtimeConfig | mainSteps | Dans la version 2.2, la section `mainSteps` remplace `runtimeConfig`. La section `mainSteps` permet à Systems Manager d'exécuter des étapes en séquence. |
| propriétés | inputs | Dans la version 2.2, la section `inputs` remplace la section `properties` . La section `inputs` accepte des paramètres pour les étapes. |
| commands | runCommand | Dans la version 2.2, la section `inputs` prend le paramètre `runCommand` au lieu du paramètre `commands`. |
| id | action | Dans la version 2.2, `Action` remplace `ID`. Il s'agit simplement d'une modification de nom. |
| non applicable | name | Dans la version 2.2, `name` est tout nom défini par l'utilisateur pour une étape. |
**Utilisation du paramètre de condition préalable**
Avec la version de schéma 2.2 ou une version ultérieure, vous pouvez utiliser le paramètre `precondition` pour spécifier le système d'exploitation cible pour chaque plugin ou pour valider les paramètres d'entrée que vous avez définis dans votre document SSM. Le paramètre `precondition` prend en charge le référencement des paramètres d'entrée de votre document SSM, et le `platformType` en utilisant les valeurs de`Linux`, `MacOS` et `Windows`. Seul l'opérateur `StringEquals` est pris en charge.
Pour les documents utilisant la version de schéma 2.2 ou une version ultérieure, si `precondition` n'est pas spécifié, chaque plugin est soit exécuté, soit ignoré en fonction de sa compatibilité avec le système d'exploitation. La compatibilité du plugin avec le système d'exploitation est évaluée avant la `precondition`. Pour les documents utilisant le schéma 2.0 ou antérieur, les plug-ins incompatibles entraînent une erreur.
Par exemple, dans un document de version de schéma 2.2, si `precondition` n'est pas spécifié et que le plugin `aws:runShellScript` figure dans la liste, l'étape s'exécute sur les instances Linux, mais le système l'ignore sur les instances Windows Server, car le `aws:runShellScript` n'est pas compatible avec les instances Windows Server. Néanmoins, pour un document de version de schéma 2.0., si vous spécifiez le plug-in `aws:runShellScript`, puis exécutez le document sur des instances Windows Server, l'exécution échoue. Un exemple du paramètre de condition préalable dans un document SSM est fourni plus loin dans cette section.
## Version de schéma 2.2
**Éléments de niveau supérieur**
L'exemple suivant présente les éléments supérieurs d'un document SSM qui utilise la version de schéma 2.2.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**Exemple de version de schéma 2.2**
L'exemple suivant utilise le `aws:runPowerShellScript` plugin pour exécuter une PowerShell commande sur les instances cibles.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**Exemples de paramètre de condition préalable dans la version de schéma 2.2**
La version de schéma 2.2 fournit le support multiplateforme. Cela signifie que dans un même document SSM, vous pouvez spécifier un système d'exploitation différent pour différents plugins. Le support multiplateforme utilise le même paramètre `precondition` dans une étape, tel que décrit dans l'exemple suivant. Vous pouvez également utiliser le paramètre `precondition` pour valider les paramètres d'entrée que vous avez définis dans votre document SSM. Cela apparaît dans le second des exemples suivants.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**Exemple d’interpolation du schéma version 2.2 avec des versions de SSM Agent antérieures à 3.3.2746.0**
Dans les versions de SSM Agent antérieures à 3.3.2746.0, l’agent ignore le paramètre `interpolationType` et effectue à la place une substitution de chaîne brute. Si vous faites référence à `SSM_parameter-name` de manière explicite, vous devez le définir explicitement. Dans l’exemple suivant pour Linux, la variable d’environnement `SSM_Message` est référencée explicitement.
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**Note**
`allowedPattern` n’est pas techniquement obligatoire si un document SSM n’utilise pas de doubles accolades : `{{ }}`
**Exemple de version de schéma 2.2 State Manager**
Vous pouvez utiliser le document SSM suivant avec State Manager, un des outils de Systems Manager, pour télécharger et installer le logiciel antivirus ClamAV. State Manager applique une configuration spécifique, ce qui signifie qu’à chaque fois que l’association State Manager est exécutée, le système vérifie si le logiciel ClamAV est installé. Si tel n'est pas le cas, State Manager réexécute ce document.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**Exemple d'inventaire de version de schéma 2.2**
Vous pouvez utiliser le document SSM suivant avec State Manager pour collecter les métadonnées d'inventaire relatives à vos instances.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**Exemple de version de schéma 2.2 `AWS-ConfigureAWSPackage`**
L'exemple suivant présente le document `AWS-ConfigureAWSPackage`. La section `mainSteps` inclut le plugin `aws:configurePackage` à l'étape `action`.
**Note**
Sur les systèmes d'exploitation Linux, seuls les packages `AmazonCloudWatchAgent` et `AWSSupport-EC2Rescue` sont pris en charge.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## Version de schéma 1.2
L'exemple suivant présente les éléments supérieurs d'un document de version de schéma 1.2.
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**Exemple de version de schéma 1.2 `aws:runShellScript`**
L'exemple suivant montre le document SSM `AWS-RunShellScript`. La section **runtimeConfig** inclut le plugin `aws:runShellScript`.
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## Version de schéma 0.3
**Éléments de niveau supérieur**
L'exemple suivant présente les éléments supérieurs d'un runbook de version de schéma 0.3 ou ultérieur au format JSON.
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**Exemple de runbook Automation YAML**
L'exemple suivant montre le contenu d'un runbook Automation, au format YAML. Cet exemple fonctionnel de la version 0.3 du schéma de document illustre également l'utilisation de Markdown pour formater les descriptions de documents.
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document continuously checks the instance status check value for the
launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to
perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance.
The default value uses the latest Amazon Linux AMI ID available. | {{
ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## Exemples de gestion sécurisée des paramètres
Les exemples suivants illustrent la gestion sécurisée des paramètres à l’aide de la variable d’environnement `interpolationType`.
### Exécution sécurisée de base des commandes
Cet exemple montre comment gérer un paramètre de commande de façon sécurisée :
**Note**
`allowedPattern` n’est pas techniquement obligatoire dans les documents SSM qui n’utilisent pas de doubles accolades : `{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### Utilisation de paramètres dans les langages interprétés
Cet exemple illustre la gestion sécurisée des paramètres en Python :
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Exemple de rétrocompatibilité
Cet exemple montre comment gérer les paramètres de façon sécurisée tout en préservant la rétrocompatibilité :
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**Note**
`allowedPattern` n’est pas techniquement obligatoire dans les documents SSM qui n’utilisent pas de doubles accolades : `{{ }}`
## Bonnes pratiques de sécurité pour les paramètres
Suivez ces bonnes pratiques lors de la gestion des paramètres dans les documents SSM :
+ **Utiliser l’interpolation des variables d’environnement** : utilisez toujours `interpolationType: "ENV_VAR"` pour les paramètres de chaîne qui seront utilisés lors de l’exécution des commandes.
+ **Implémenter la validation des entrées** : utilisez `allowedPattern` pour limiter les valeurs des paramètres à des modèles sûrs.
+ **Gérer les systèmes hérités** : incluez une logique de secours pour les anciennes versions de SSM Agent qui ne prennent pas en charge l’interpolation des variables d’environnement.
+ **Échapper les caractères spéciaux** : lorsque vous utilisez des valeurs de paramètres dans des commandes, échappez correctement les caractères spéciaux pour empêcher toute interprétation par le shell.
+ **Limiter la portée des paramètres** : utilisez les modèles de paramètres les plus restrictifs possibles pour votre cas d’utilisation.
# Éléments de données et paramètres
Cette rubrique décrit les éléments de données utilisés dans les documents SSM. La version du schéma utilisée pour créer un document définit la syntaxe et les éléments de données que le document accepte. Nous vous recommandons l'utilisation de la version de schéma 2.2 ou celle ultérieure pour les documents de Commande. Les runbooks Automation utilisent la version de schéma 0.3. De plus, les runbooks Automation prennent en charge l'utilisation de Markdown, un langage de balisage, qui vous permet d'ajouter des descriptions de style wiki aux documents et des étapes individuelles au sein du document. Pour plus d'informations relatives à l'utilisation de Markdown, consultez [Utilisation de Markdown dans la console](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html) dans le *Guide de mise en route AWS Management Console *.
La section suivante décrit les éléments de données pouvant être inclut dans un document SSM.
## Éléments de données niveau supérieur
**schemaVersion**
Version de schéma à utiliser.
Type : Version
Obligatoire : oui
**description**
Informations que vous fournissez pour décrire l'objectif du document. Vous pouvez également utiliser ce champ pour spécifier si un paramètre nécessite une valeur pour qu'un document s'exécute ou si la fourniture d'une valeur pour le paramètre est facultative. Les paramètres obligatoires et facultatifs peuvent être consultés dans les exemples de cette rubrique.
Type : chaîne
Obligatoire : non
**parameters**
Structure qui définit les paramètres acceptés par le document.
Pour améliorer la sécurité lors de la gestion des paramètres de chaîne, vous pouvez utiliser l’interpolation des variables d’environnement en spécifiant la propriété `interpolationType`. Si défini sur `ENV_VAR`, le système crée une variable d’environnement nommée `SSM_parameter-name` contenant la valeur du paramètre.
Voici un exemple de paramètre utilisant la variable d’environnement `interpolationType` :
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
`allowedPattern` n’est pas techniquement obligatoire dans les documents SSM qui n’utilisent pas de doubles accolades : `{{ }}`
Pour les paramètres souvent utilisés, nous vous recommandons de les stocker dans Parameter Store, un outil d’ AWS Systems Manager. Ensuite, définissez les paramètres de votre document faisant référence aux paramètres Parameter Store comme valeur par défaut. Pour référencer un paramètre Parameter Store, utilisez la syntaxe suivante.
```
{{ssm:parameter-name}}
```
Utilisez un paramètre faisant référence à un paramètre Parameter Store similaire à tout autre paramètre du document. Dans l'exemple suivant, la valeur par défaut du paramètre `commands` est le paramètre Parameter Store `myShellCommands`. En spécifiant le paramètre `commands` en tant que chaîne `runCommand`, le document exécute les commandes stockées dans le paramètre `myShellCommands`.
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
Vous pouvez référencer les paramètres `String` et `StringList` Parameter Store dans la section `parameters` d'un document. Vous ne pouvez pas référencer les paramètres Parameter Store `SecureString`.
Pour plus d’informations sur Parameter Store, consultez [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md).
Type : Structure
La structure `parameters` accepte les champs et valeurs suivants :
+ `type` : (Obligatoire) les valeurs autorisées sont : `String`, `StringList`, `Integer`, `Boolean`, `MapList` et `StringMap`. Pour consulter des exemples de chaque type, consultez [Exemples de paramètres `type` de document SSM](#top-level-properties-type) dans la section suivante.
**Note**
Les documents de type Command ne prennent en charge que les types de paramètres `String` et `StringList`.
+ `description` : (Facultatif) Description du paramètre.
+ `default` : (Facultatif) Valeur par défaut du paramètre ou référence à un paramètre dans Parameter Store.
+ `allowedValues` : (facultatif) tableau de valeurs autorisées pour le paramètre. La définition des valeurs autorisées pour le paramètre valide l'entrée utilisateur. Si un utilisateur saisit une valeur non autorisée, l'exécution échoue.
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern` : (facultatif) expression régulière qui valide si l'entrée utilisateur correspond au modèle défini pour le paramètre. Si l'entrée utilisateur ne correspond pas au modèle autorisé, l'exécution échoue.
**Note**
Systems Manager effectue deux validations pour `allowedPattern`. La première validation est effectuée à l'aide de la [bibliothèque Java regex](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html) au niveau de l'API lorsque vous utilisez un document. La deuxième validation est effectuée sur SSM Agent en utilisant la [bibliothèque Go regexp](https://pkg.go.dev/regexp)avant de traiter le document.
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (Facultatif) Utilisé pour afficher un `textfield` ou un `textarea` dans le AWS Management Console. `textfield`est une zone de texte d'une seule ligne. `textarea`est une zone de texte multiligne.
+ `minItems` : (Facultatif) Nombre minimum d'éléments autorisés.
+ `maxItems` : (Facultatif) Nombre maximum d'éléments autorisés.
+ `minChars` : (Facultatif) Nombre minimum d'éléments autorisés.
+ `maxChars` : (Facultatif) Nombre maximum de caractères de paramètre autorisés.
+ `interpolationType` : (facultatif) définit la manière dont les valeurs des paramètres sont traitées avant l’exécution de la commande. Si défini sur `ENV_VAR`, la valeur du paramètre est rendue disponible sous forme de variable d’environnement nommée `SSM_parameter-name`. Cette fonctionnalité permet d’empêcher l’injection de commandes en traitant les valeurs des paramètres comme des chaînes littérales.
Type : Chaîne
Valeurs valides : `ENV_VAR`
Obligatoire : non
**variables**
(Schéma version 0.3 uniquement) Valeurs que vous pouvez référencer ou mettre à jour tout au long des étapes d’un runbook d’Automation. Les variables sont similaires aux paramètres, mais diffèrent d’une manière très importante. Les valeurs des paramètres sont statiques dans le contexte d’un runbook, mais les valeurs des variables peuvent être modifiées dans le contexte du runbook. Lors de la mise à jour de la valeur d’une variable, le type de données doit correspondre au type de données défini. Pour plus d’informations sur la mise à jour des valeurs de variables dans une automatisation, veuillez consulter [`aws:updateVariable` : met à jour la valeur d’une variable runbook](automation-action-update-variable.md).
Type : booléen \$1 Entier \$1 \$1 Chaîne MapList \$1 \$1 StringList StringMap
Obligatoire : non
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(Version de schéma 1.2 seulement) Configuration de l'instance telle qu'appliquée par un ou plusieurs plugins Systems Manager. L'exécution en séquence des plugins n'est pas garantie.
Type : Dictionnaire PluginConfiguration
Obligatoire : non
**mainSteps**
(Version de schéma 0.3, 2.0 et 2.2 uniquement) Objet pouvant inclure plusieurs étapes (plug-ins). Les plug-ins sont définis en étapes. Les étapes s'exécutent par ordre séquentiel telles que listées dans le document.
Type : Dictionnaire PluginConfiguration
Obligatoire : oui
**outputs**
(Version de schéma 0.3 uniquement) Données générées par l'exécution de ce document pouvant être utilisées dans d'autres processus. Par exemple, si votre document en crée un nouveauAMI, vous pouvez spécifier « »CreateImage. ImageId« comme valeur de sortie, puis utilisez cette sortie pour créer de nouvelles instances lors d'une exécution d'automatisation ultérieure. Pour plus d'informations sur les sorties, consultez [Utilisation des sorties d'action comme entrées](automation-action-outputs-inputs.md).
Type : Dictionnaire OutputConfiguration
Obligatoire : non
**files**
(Version de schéma 0.3 uniquement) Les fichiers de script (et leurs sommes de contrôle) attachés au document et exécutés lors d'une exécution Automation. S'applique uniquement aux documents qui incluent l'action `aws:executeScript` et pour lesquels des pièces jointes ont été spécifiées dans une ou plusieurs étapes.
Pour en savoir plus sur les durées d’exécution prises en charge par les dossiers d’exploitation Automation, consultez [`aws:executeScript` - Exécuter un script](automation-action-executeScript.md). Pour de plus amples informations sur l'inclusion de scripts dans les runbooks Automation, veuillez consulter [Utilisation de scripts dans des runbooks](automation-document-script-considerations.md) et [Expérience de conception visuelle pour les runbooks d’Automatisation](automation-visual-designer.md).
Lorsque vous créez un runbook d'automatisation avec des pièces jointes, vous devez également spécifier les fichiers joints à l'aide de l'`--attachments`option (pour AWS CLI) ou `Attachments` (pour l'API et le SDK). Vous pouvez spécifier l’emplacement du fichier pour les documents SSM et les fichiers stockés dans les compartiments Amazon Simple Storage Service (Amazon S3). Pour plus d'informations, consultez la section [Pièces jointes](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) dans le Guide de référence de AWS Systems Manager l'API.
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
Type : Dictionnaire FilesConfiguration
Obligatoire : non
## Exemples de paramètres `type` de document SSM
Les types de paramètres des documents SSM sont statiques. Cela signifie que le type de paramètre ne peut pas être modifié après avoir été défini. Lorsque vous utilisez des paramètres avec des plugins de document SSM, le type d'un paramètre ne peut pas être modifié dynamiquement dans l'entrée d'un plugin. Par exemple, vous ne pouvez pas référencer un paramètre `Integer` dans l'entrée `runCommand` du plugin `aws:runShellScript`, car cette entrée accepte une chaîne ou une liste de chaînes. Pour utiliser un paramètre pour une entrée de plugin, le type de paramètre doit correspondre au type accepté. Par exemple, vous devez spécifier un type de paramètre `Boolean` pour l'entrée `allowDowngrade` du plugin `aws:updateSsmAgent`. Si votre type de paramètre ne correspond pas au type d'entrée d'un plugin, le document SSM n'est pas validé et le système ne crée pas le document. Cela est également vrai lorsque vous utilisez des paramètres en aval dans les entrées pour d'autres plugins ou actions AWS Systems Manager d'automatisation. Par exemple, vous ne pouvez pas référencer un paramètre `StringList` dans l'entrée `documentParameters` du plugin `aws:runDocument`. L'entrée `documentParameters` accepte une carte de chaînes même si le type de paramètre de document SSM en aval est un paramètre `StringList` et correspond au paramètre auquel vous faites référence.
Lorsque vous utilisez des paramètres avec des actions Automation, dans la plupart des cas les types de paramètres ne sont pas validés lorsque vous créez le document SSM. Ce n'est que lorsque vous utilisez l'action `aws:runCommand` que les types de paramètres sont validés lors de la création du document SSM. Dans tous les autres cas, la validation des paramètres se produit pendant l'exécution d'automatisation lorsque l'entrée d'une action est vérifiée avant d'exécuter cette dernière. Par exemple, si votre paramètre d'entrée est une `String` et que vous le référencez comme valeur pour l'entrée `MaxInstanceCount` de l'action `aws:runInstances`, le document SSM est créé. Toutefois, lors de l'exécution du document, l'automatisation échoue lors de la validation de l'action `aws:runInstances`, car l'entrée `MaxInstanceCount` nécessite un `Integer`.
Voici des exemples de chaque `type` de paramètre.
String
Une séquence de zéro ou plusieurs caractères Unicode entre guillemets. Par exemple, « i-1234567890abcdef0". Utilisez des barres obliques inverses comme caractères d'échappement.
Les paramètres de chaîne peuvent inclure un champ facultatif `interpolationType` avec la valeur `ENV_VAR` pour permettre l’interpolation des variables d’environnement afin d’améliorer la sécurité.
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
Liste d'éléments String séparés par des virgules. Par exemple, ["cd \$1", "pwd"].
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
Booléen
Accepte uniquement `true` ou `false`. N'accepte pas la valeur « true », ni 0.
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
Entier
Nombres entiers. N'accepte pas de nombres décimaux, par exemple 3,14159, ni de nombres entre guillemets, par exemple « 3 ».
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
Mappage de clés à des valeurs. Les clés et les valeurs doivent être des chaînes. Par exemple, \$1"Env": "Prod"\$1.
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
Liste d' StringMap objets.
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## Affichage du contenu du document SSM Command
Pour prévisualiser les paramètres obligatoires et facultatifs d'un document de commande AWS Systems Manager (SSM), outre les actions exécutées par le document, vous pouvez consulter le contenu du document dans la console Systems Manager.
**Pour afficher le contenu d'un document SSM Command**
1. Ouvrez la AWS Systems Manager console à l'adresse [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. Dans le panneau de navigation, cliquez sur **Documents**.
1. Dans la zone de recherche, sélectionnez **Type de document**, puis sélectionnez **Command**.
1. Sélectionnez le nom d'un document, puis l'onglet **Content (Contenu)**.
1. Dans le champ Contenu, vérifiez les paramètres disponibles et les étapes d'action du document.
Par exemple, l'image suivante montre que (1) `version` et (2) `allowDowngrade` sont des paramètres facultatifs pour le document `AWS-UpdateSSMAgent`, et que la première action exécutée par le document est (3) `aws:updateSsmAgent`.
![\[Afficher le contenu d'un document SSM dans la console Systems Manager\]](http://docs.aws.amazon.com/fr_fr/systems-manager/latest/userguide/images/view-document-content.png)
# Référence de plug-in de document Command
Cette référence décrit les plugins que vous pouvez spécifier dans un document de type commande AWS Systems Manager (SSM). Ces plugins ne peuvent pas être utilisés dans les runbooks Automation SSM qui utilisent des actions Automation. Pour plus d'informations sur les actions AWS Systems Manager d'automatisation, consultez[Référence sur les actions Systems Manager Automation](automation-actions.md).
Systems Manager détermine les actions à effectuer sur une instance gérée en lisant le contenu d'un document SSM. Chaque document comprend une section d'exécution de code. En fonction de la version de schéma de votre document, cette section d'exécution de code peut inclure un ou plusieurs plug-ins, ou bien une ou plusieurs étapes. Dans le cadre de cette rubrique d'aide, les plug-ins et les étapes sont appelés *plug-ins*. Cette section comprend des informations sur chacun des plugins Systems Manager. Pour plus d'informations sur les documents, la création de documents et les différences entre les versions de schéma, consultez [AWS Systems Manager Documents](documents.md).
Pour les plug-ins qui acceptent des paramètres de chaîne, comme `aws:runShellScript` et `aws:runPowerShellScript`, le paramètre `interpolationType` peut être utilisé pour améliorer la sécurité en traitant les entrées de paramètres comme des chaînes littérales plutôt que comme des commandes potentiellement exécutables. Par exemple :
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**Note**
Certains plug-ins décrits ici s'exécutent uniquement sur des instances Windows Server ou sur des instances Linux. Les dépendances de plate-forme sont notées pour chaque plug-in.
Les plugins de document suivants sont pris en charge sur les instances Amazon Elastic Compute Cloud (Amazon EC2) pour macOS :
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [Entrées partagées](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## Entrées partagées
Avec SSM Agent version 3.0.502 et ultérieure uniquement, tous les plugins peuvent utiliser les entrées suivantes :
**finallyStep**
La dernière étape que le document doit exécuter. Si cette entrée est définie pour une étape, elle a priorité sur une valeur `exit` spécifiée dans les entrées `onFailure` ou `onSuccess`. Pour qu'une étape avec cette entrée s'exécute comme prévu, elle doit être la dernière étape définie dans les `mainSteps` de votre document.
Type : Boolean
Valeurs valides : `true` \$1 `false`
Obligatoire : non
**onFailure**
Si vous spécifiez cette entrée pour un plugin avec la valeur `exit` et que l'étape échoue, le statut de l'étape reflète l'échec et le document n'exécute pas les étapes restantes sauf si une `finallyStep` a été définie. Si vous spécifiez cette entrée pour un plugin avec la valeur `successAndExit` et que l'étape échoue, le statut de l'étape affiche la réussite et le document n'exécute pas les étapes restantes sauf si une `finallyStep` a été définie.
Type : Chaîne
Valeurs valides : `exit` \$1 `successAndExit`
Obligatoire : non
**onSuccess**
Si vous spécifiez cette entrée pour un plugin et que l'étape s'exécute correctement, le document n'exécute pas les étapes restantes sauf si une `finallyStep` a été définie.
Type : Chaîne
Valeurs valides : `exit`
Obligatoire : non
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
Installer, réparer ou désinstaller des applications sur une instance EC2. Ce plug-in s'exécute uniquement sur les systèmes d'exploitation Windows Server.
### Syntaxe
#### Schéma 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### Schéma 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### Propriétés
**action**
Action à effectuer.
Type : énumération
Valeurs valides : `Install` \$1 `Repair` \$1 `Uninstall`
Obligatoire : oui
**parameters**
Paramètres pour le programme d'installation.
Type : chaîne
Obligatoire : non
**source**
URL du fichier `.msi` pour l'application.
Type : Chaîne
Obligatoire : oui
**sourceHash**
Le SHA256 hachage du `.msi` fichier.
Type : chaîne
Obligatoire : non
## `aws:cloudWatch`
Exportez des données depuis Windows Server Amazon CloudWatch ou Amazon CloudWatch Logs et surveillez-les à l'aide de CloudWatch métriques. Ce plug-in s'exécute uniquement sur les systèmes d'exploitation Windows Server. Pour plus d'informations sur la configuration de CloudWatch l'intégration avec Amazon Elastic Compute Cloud (Amazon EC2), [consultez la section Collecter des métriques, des journaux et des traces avec CloudWatch l'agent dans le guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) de l'utilisateur *Amazon CloudWatch *.
**Important**
L' CloudWatch agent unifié a été remplacé SSM Agent en tant qu'outil d'envoi des données de journal à Amazon CloudWatch Logs. Le plugin SSM Agent aws:cloudWatch n'est pas pris en charge. Nous vous recommandons de n'utiliser que l' CloudWatch agent unifié pour vos processus de collecte de journaux. Pour plus d’informations, consultez les rubriques suivantes :
[Envoi des journaux des nœuds vers CloudWatch des journaux unifiés (CloudWatch agent)](monitoring-cloudwatch-agent.md)
[Migrer la collecte des journaux des nœuds Windows Server vers l' CloudWatch agent](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
[Collecte de métriques, de journaux et de traces avec l' CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) dans le *guide de CloudWatch l'utilisateur Amazon*.
Vous pouvez exporter et contrôler les types de données suivants :
**ApplicationEventLog**
Envoie les données du journal des événements de l'application à CloudWatch Logs.
**CustomLogs**
Envoie n'importe quel fichier journal sous forme de texte à Amazon CloudWatch Logs. Le CloudWatch plugin crée une empreinte digitale pour les fichiers journaux. Le système associe ensuite un décalage des données à chaque empreinte. Le plug-in charge les fichiers en cas de modifications, enregistre le décalage et associe celui-ci à une empreinte. Cette méthode est utilisée pour éviter que le système charge tous le fichiers si un utilisateur active le plugin et associe le service à un répertoire contenant un grand nombre de fichiers.
N'oubliez pas que si votre application tronque ou tente de nettoyer des journaux au cours d'une interrogation, tous les journaux spécifiés pour `LogDirectoryPath` peuvent perdre des entrées. Si, par exemple, vous souhaitez limiter la taille des fichiers journaux, créez un nouveau fichier lorsque cette limite est atteinte, puis continuez à écrire les données dans le nouveau fichier.
**ETW**
Envoie les données de suivi des événements pour Windows (ETW) aux CloudWatch journaux.
**IIS**
Envoie les données du journal IIS à CloudWatch Logs.
**PerformanceCounter**
Envoie les compteurs de performance Windows à. CloudWatch Vous pouvez sélectionner différentes catégories dans lesquelles vous souhaitez effectuer le téléchargement CloudWatch sous forme de statistiques. Pour chaque compteur de performance que vous souhaitez télécharger, créez une **PerformanceCounter**section avec un identifiant unique (par exemple, « PerformanceCounter 2 », « PerformanceCounter 3 », etc.) et configurez ses propriétés.
Si le plugin AWS Systems Manager SSM Agent ou le CloudWatch plugin est arrêté, les données du compteur de performance ne sont pas enregistrées CloudWatch. Ce comportement est différent des journaux personnalisés ou des journaux d'événements Windows. Les journaux personnalisés et les journaux d'événements Windows préservent les données des compteurs de performance et les CloudWatch téléchargent SSM Agent une fois que le CloudWatch plug-in est disponible.
**SecurityEventLog**
Envoie les données du journal des événements de sécurité à CloudWatch Logs.
**SystemEventLog**
Envoie les données du journal des événements du système à CloudWatch Logs.
Vous pouvez définir les destinations suivantes pour les données :
**CloudWatch**
La destination où vos données de métriques de compteur de performances sont envoyées. Vous pouvez ajouter d'autres sections avec un identifiant unique IDs (par exempleCloudWatch, « 2 », CloudWatch 3, etc.) et spécifier une région différente pour chaque nouvel identifiant afin d'envoyer les mêmes données à différents emplacements.
**CloudWatchLogs**
La destination où vos données de journaux sont envoyées. Vous pouvez ajouter d'autres sections avec un identifiant unique IDs (par exempleCloudWatchLogs, « 2 », CloudWatchLogs 3, etc.) et spécifier une région différente pour chaque nouvel identifiant afin d'envoyer les mêmes données à différents emplacements.
### Syntaxe
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### Paramètres et propriétés
**AccessKey**
Votre ID de clé d’accès . Cette propriété est obligatoire, sauf si vous avez lancé votre instance par l'intermédiaire d'une rôle IAM. Elle ne peut pas être utilisée avec SSM.
Type : chaîne
Obligatoire : non
**CategoryName**
Catégorie du compteur de performances en provenance de Performance Monitor.
Type : Chaîne
Obligatoire : oui
**CounterName**
Nom du compteur de performances en provenance de Performance Monitor.
Type : Chaîne
Obligatoire : oui
**CultureName**
Paramètres régionaux où l'horodatage est consigné. S'il **CultureName**est vide, il utilise par défaut les mêmes paramètres régionaux que ceux utilisés par votre Windows Server instance.
Type : Chaîne
Valeurs valides : pour obtenir une liste des valeurs prises en charge, consultez [Support des langues nationales](https://msdn.microsoft.com/en-us/library/cc233982.aspx) sur le site Web de Microsoft. Les valeurs **div**, **div-MV**, **hu**, et **hu-HU** ne sont pas prises en charge.
Obligatoire : non
**DimensionName**
Une dimension pour votre CloudWatch métrique Amazon. Si vous spécifiez `DimensionName`, vous devez spécifier `DimensionValue`. Ces paramètres offrent une autre vue lors de la création de listes de métriques. Vous pouvez utiliser la même dimension pour plusieurs métriques afin d'afficher toutes les métriques appartenant à une dimension spécifique.
Type : chaîne
Obligatoire : non
**DimensionValue**
Une valeur de dimension pour votre CloudWatch métrique Amazon.
Type : chaîne
Obligatoire : non
**Encodage**
Encodage de fichier à utiliser (par exemple, UTF-8). Utilisez le nom d'encodage, pas le nom complet.
Type : Chaîne
Valeurs valides : pour obtenir une liste des valeurs prises en charge, veuillez consulter la rubrique [Classe d'encodage](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0) dans la bibliothèque Microsoft Learn (langue française non garantie).
Obligatoire : oui
**Filtre**
Préfixe des noms de journaux. Laissez ce paramètre vide de façon à surveiller tous les fichiers.
Type : Chaîne
Valeurs valides : pour obtenir la liste des valeurs prises en charge, consultez la [FileSystemWatcherFilter propriété](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx) dans la bibliothèque MSDN.
Obligatoire : non
**Flux**
Chaque type de données à télécharger, ainsi que la destination des données (CloudWatch ou CloudWatch journaux). Par exemple, pour envoyer un compteur de performance défini sous `"Id": "PerformanceCounter"` vers la CloudWatch destination définie sous`"Id": "CloudWatch"`, entrez **«PerformanceCounter, CloudWatch »**. De même, pour envoyer le journal personnalisé, le journal ETW et le journal système vers la destination CloudWatch des journaux définie ci-dessous`"Id": "ETW"`, entrez **« (ETW), CloudWatchLogs** ». En outre, vous pouvez envoyer le même compteur de performances ou fichier journal à plus d'une destination. Par exemple, pour envoyer le journal de l'application vers deux destinations différentes que vous avez définies sous `"Id": "CloudWatchLogs"` et`"Id": "CloudWatchLogs2"`, entrez **«ApplicationEventLog, (CloudWatchLogs, CloudWatchLogs 2) »**.
Type : Chaîne
Valeurs valides (source) : `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
Valeurs valides (destination) : `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch` *n* \$1 `CloudWatchLogs` *n*
Obligatoire : oui
**FullName**
Nom complet du composant.
Type : Chaîne
Obligatoire : oui
**Id**
Identifie la source ou la destination des données. Cet identificateur doit être unique au sein du fichier de configuration.
Type : Chaîne
Obligatoire : oui
**InstanceName**
Nom de l'instance du compteur de performances. N'utilisez pas d'astérisque (\$1) pour indiquer toutes les instances, car chaque composant du compteur de performance prend en charge un seul élément. Cependant, vous pouvez utiliser **\$1Total**.
Type : Chaîne
Obligatoire : oui
**Niveaux**
Les types de messages à envoyer à Amazon CloudWatch.
Type : chaîne
Valeurs valides :
+ **1** - Uniquement les messages d'erreur chargés.
+ **2** - Uniquement les messages d'avertissement chargés.
+ **4** - Uniquement les messages d'information chargés.
Vous pouvez ajouter des valeurs pour inclure plusieurs types de message. Par exemple, **3** signifie que les messages d'erreur (**1**) et les messages d'avertissement (**2**) sont inclus. Une valeur de **7** signifie que les messages d'erreur (**1**), les messages d'avertissement (**2**) et les messages d'information (**4**) sont inclus.
Obligatoire : oui
Pour les journaux de sécurité Windows, Levels doit être défini sur 7.
**LineCount**
Nombre de lignes de l'en-tête permettant d'identifier le fichier journal. Par exemple, les fichiers journaux IIS ont des en-têtes presque identiques. Vous pouvez entrer **3**, qui lirait les trois premières lignes de l'en-tête du fichier journal pour l'identifier. Dans les fichiers journaux IIS, la troisième ligne correspond à l'horodatage qui diffère d'un fichier journal à l'autre.
Type : Integer
Obligatoire : non
**LogDirectoryPath**
Pour CustomLogs, le chemin où les journaux sont stockés sur votre instance EC2. Pour les journaux IIS, dossier dans lequel les journaux IIS sont stockés pour un site individuel (par exemple, **C : \$1 \$1 inetpub \$1 \$1 logs \$1 \$1 \$1 LogFiles \$1 *n* W3SVC**). Pour les journaux IIS, seul le format de journal W3C est pris en charge. Les formats IIS, NCSA et Personnalisé ne sont pas pris en charge.
Type : Chaîne
Obligatoire : oui
**LogGroup**
Nom de votre groupe de journaux. Ce nom s'affiche sur l'écran **Groupes de journaux** dans la console CloudWatch.
Type : Chaîne
Obligatoire : oui
**LogName**
Nom du fichier journal.
1. Pour trouver le nom du journal, dans l'observateur d'événements, dans le panneau de navigation, sélectionnez **Applications and Services Logs (Journaux d'applications et de services)**.
1. Dans la liste des journaux, cliquez avec le bouton droit de la souris sur le journal que vous voulez télécharger (par exemple, `Microsoft` > `Windows` > `Backup` > `Operational`), puis cliquez sur **Créer une vue personnalisée**.
1. Dans la boîte de dialogue **Create Custom View (Créer une vue personnalisée)**, sélectionnez l'onglet **XML**. Cela **LogName**se trouve dans la balise