Schémas, fonctionnalités et exemples - AWS Systems Manager

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.

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.

Note

Tu dois garder AWS Systems Manager SSM Agent sur vos instances mises à 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.

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.

ne s'applique pas

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 deLinux, 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 la version 2.2 d'un schéma, si precondition ce n'est pas spécifié et que le aws:runShellScript plugin est répertorié, l'étape s'exécute sur des instances Linux, mais le système l'ignore Windows Server instances car elles aws:runShellScript ne sont pas compatibles avec Windows Server instances. Toutefois, pour un document de schéma version 2.0, si vous spécifiez le aws:runShellScript plugin, puis que vous exécutez le document sur un Windows Server instances, 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" ] } } ] }
Version de schéma 2.2 State Manager exemple

Vous pouvez utiliser le document SSM suivant avec State Manager, un outil de Systems Manager, permettant de télécharger et d'installer le logiciel antivirus ClamAV. State Manager applique une configuration spécifique, ce qui signifie que chaque fois que State Manager l'association est exécutée, le système vérifie si le logiciel ClamAV est installé. Dans le cas contraire, 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 des métadonnées d'inventaire concernant 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/amzn-ami-hvm-x86_64-gp2 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}' 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.8 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.8 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