Schemi, funzionalità ed esempi - AWS Systems Manager

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Schemi, funzionalità ed esempi

AWS Systems Manager (SSM) i documenti utilizzano le seguenti versioni dello schema.

  • I documenti di tipo Command possono utilizzare le versione dello schema 1.2, 2.0 e 2.2. Se si utilizzano documenti con lo schema 1.2, consigliamo di creare documenti con la versione 2.2 dello schema.

  • I documenti di tipo Policy devono utilizzare la versione dello schema 2.0 o una versione successiva.

  • I documenti di tipo Automation devono utilizzare la versione dello schema 0.3.

  • I documenti di tipo Session devono utilizzare lo schema versione 1.0.

  • È possibile creare documenti in JSON oYAML.

Per ulteriori informazioni sullo schema Session del documento, vedereSchema documento di sessione.

Utilizzando la versione più recente dello schema per documenti Command e Policy, puoi sfruttare le seguenti caratteristiche.

Caratteristiche dei documenti con versione dello schema 2.2
Funzionalità Informazioni

Modifica dei documenti

Ora i documenti possono essere aggiornati. Con la versione 1.2, qualsiasi aggiornamento a un documento doveva essere salvato con un nome diverso.

Funzione Versioni multiple automatica

Qualsiasi aggiornamento a un documento crea una nuova versione. Non si tratta di una versione dello schema, ma di una versione del documento.

Versione predefinita

Se disponi di più versioni di un documento, puoi specificare quale versione è il documento predefinito.

Sequenziamento

I plugin o le fasi in un documento vengono eseguiti nell'ordine specificato.

Supporto multipiattaforma

Il supporto multipiattaforma consente di specificare diversi sistemi operativi per diversi plugin all'interno dello stesso SSM documento. Il supporto multipiattaforma utilizza il parametro precondition all'interno di una fase.

Nota

È necessario mantenere AWS Systems Manager SSM Agent le istanze aggiornate alla versione più recente per utilizzare le nuove funzionalità di Systems Manager e le funzionalità dei SSM documenti. Per ulteriori informazioni, consulta Aggiornamento di SSM Agent utilizzando Run Command.

Nella tabella seguente vengono elencate le differenze tra le versioni principali dello schema.

Versione 1.2 Versione 2.2 (versione più recente) Informazioni

runtimeConfig

mainSteps

Nella versione 2.2, la sezione mainSteps sostituisce runtimeConfig. La sezione mainSteps consente a Systems Manager di eseguire le fasi in sequenza.

properties

inputs

Nella versione 2.2, la sezione inputs sostituisce la sezione properties. La sezione inputs accetta parametri per le fasi.

commands

runCommand

Nella versione 2.2, la sezione inputs richiede il parametro runCommand anziché il parametro commands.

id

action

Nella versione 2.2, Action sostituisce ID. Si tratta di una semplice modifica di nome.

non applicabile

nome

Nella versione 2.2, name è un qualsiasi nome definito dall'utente per una fase.

Utilizzo del parametro Precondition

Con la versione 2.2 o successiva dello schema, è possibile utilizzare il precondition parametro per specificare il sistema operativo di destinazione per ogni plug-in o per convalidare i parametri di input definiti nel documento. SSM Il precondition parametro supporta il riferimento ai parametri di input del SSM documento e platformType l'utilizzo dei valori di LinuxMacOS, e. Windows Soltanto l'operatore StringEquals è supportato.

Per i documenti che utilizzano la versione dello schema 2.2 o successiva, se precondition non è specificato, ogni plugin viene eseguito o ignorato in base alla relativa compatibilità con il sistema operativo. La compatibilità dei plugin con il sistema operativo viene valutata prima di precondition. Per i documenti che utilizzano la versione dello schema 2.0 o precedente, i plugin non compatibili generano un errore.

Ad esempio, in un documento che utilizza la versione dello schema 2.2, se precondition non è specificato e il plugin aws:runShellScript è presente, la fase viene eseguita sulle istanze Linux, ma il sistema la ignora sulle istanze Windows Server, poiché aws:runShellScript non è compatibile con le istanze Windows Server. Tuttavia, per un documento che utilizza la versione dello schema 2.0, se specifichi il plugin aws:runShellScript ed esegui il documento su istanze Windows Server, l'esecuzione non va a buon fine. È possibile vedere un esempio del parametro precondition in un SSM documento più avanti in questa sezione.

Versione dello schema 2.2

Elementi di primo livello

L'esempio seguente mostra gli elementi di primo livello di un SSM documento utilizzando lo schema versione 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 }}" } } ] }
Esempio con per la versione dello schema 2.2

L'esempio seguente utilizza il aws:runPowerShellScript plugin per eseguire un PowerShell comando sulle istanze di destinazione.

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}}" ] } } ] }
Esempi del parametro Precondition per la versione dello schema 2.2

La versione dello schema 2.2 offre il supporto multipiattaforma. Ciò significa che all'interno di un singolo SSM documento è possibile specificare diversi sistemi operativi per diversi plugin. Il supporto multipiattaforma utilizza il parametro precondition all'interno di una fase, come mostrato nel seguente esempio. Puoi anche utilizzare il precondition parametro per convalidare i parametri di input che hai definito nel documentoSSM. Ne è la riprova il secondo dei seguenti esempi.

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" ] } } ] }
Esempio con State Manager per la versione dello schema 2.2

È possibile utilizzare il seguente SSM documento conState Manager, una funzionalità di Systems Manager, per scaricare e installare il software antivirus ClamAV. State Managerimpone una configurazione specifica, il che significa che ogni volta che viene eseguita l'State Managerassociazione, il sistema verifica se il software ClamAV è installato. Se così non fosse, State Manager esegue nuovamente questo documento.

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" ] } } ] }
Esempio di versione dello schema 2.2 per un inventario

È possibile utilizzare il seguente SSM documento State Manager per raccogliere i metadati di inventario relativi alle istanze.

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 }}" } } ] }
Esempio con AWS-ConfigureAWSPackage per la versione dello schema 2.2

L'esempio seguente mostra il documento AWS-ConfigureAWSPackage. La sezione mainSteps include il plugin aws:configurePackage nella fase action.

Nota

Sui sistemi operativi Linux sono supportati solo i pacchetti AmazonCloudWatchAgent e AWSSupport-EC2Rescue.

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 }}" } } ] }

Versione dello schema 1.2

L'esempio seguente mostra gli elementi di primo livello di un documento che utilizza la versione dello schema 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" } ] } } }
Esempio con aws:runShellScript per la versione dello schema 1.2

L'esempio seguente mostra il documento. AWS-RunShellScript SSM La runtimeConfigsezione include il aws:runShellScript plugin.

{ "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 }}" } ] } } }

Versione dello schema 0.3

Elementi di primo livello

L'esempio seguente mostra gli elementi di primo livello di un runbook di automazione dello schema versione 0.3 in JSON formato.

{ "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 } } }
YAMLEsempio di runbook di automazione

L'esempio seguente mostra il contenuto di un runbook di automazione, in YAML formato. Questo esempio d'uso della versione 0.3 dello schema del documento dimostra anche l'utilizzo di Markdown per formattare le descrizioni dei documenti.

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