• 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.
# 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é. |
| Cross-platform soutien | Cross-platform le support vous permet de spécifier différents systèmes d'exploitation pour différents plugins dans le même document SSM. Cross-platform le support utilise le `precondition` paramètre au cours d'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
**Top-level éléments**
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 différents systèmes d'exploitation pour différents plugins. Cross-platform support utilise le `precondition` paramètre au sein d'une étape, comme illustré 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
**Top-level éléments**
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.