• La AWS Systems Manager CloudWatch dashboard non sarà più disponibile dopo il 30 aprile 2026. I clienti possono continuare a utilizzare la CloudWatch console Amazon per visualizzare, creare e gestire le proprie CloudWatch dashboard Amazon, proprio come fanno oggi. Per ulteriori informazioni, consulta la [documentazione di Amazon CloudWatch Dashboard](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
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 I documenti (SSM) 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 la versione dello schema 1.0.
+ Puoi creare documenti in formato JSON o YAML.
Per ulteriori informazioni sull'utilizzo del documento schema `Session`, consulta [Schema documento di sessione](session-manager-schema.md).
Utilizzando la versione più recente dello schema per documenti `Command` e `Policy`, puoi sfruttare le seguenti funzionalità.
**Funzionalità 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. |
| Controllo delle versioni automatico | 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 sistemi operativi differenti per plugin differenti all'interno dello stesso documento SSM. Il supporto multipiattaforma utilizza il parametro `precondition` all'interno di una fase. |
| Interpolazione dei parametri | Interpolazione significa inserire o sostituire un valore variabile in una stringa. Immagina che sia come riempire uno spazio vuoto con valori effettivi, prima che la stringa venga utilizzata. Nel contesto dei documenti SSM, l'interpolazione dei parametri consente di interpolare i parametri delle stringhe in variabili di ambiente prima dell'esecuzione del comando, offrendo una maggiore sicurezza contro le iniezioni di comandi. Se impostato su `ENV_VAR`, l'agente crea una variabile di ambiente denominata `SSM_parameter-name`, che contiene il valore del parametro. |
**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 documenti SSM. Per ulteriori informazioni, consulta [Aggiornamento di SSM Agent utilizzando Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
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 | operazione | 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 dello schema 2.2 o successiva, è possibile utilizzare il parametro `precondition` per specificare il sistema operativo di destinazione per ciascun plugin o convalidare i parametri di input definiti nel documento SSM. Il parametro `precondition` supporta il riferimento ai parametri di input del documento SSM e `platformType` utilizzando i valori di `Linux`, `MacOS`, 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. Un esempio del parametro Precondition in un documento SSM è disponibile 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 documento SSM che utilizza la versione dello schema 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` plug-in 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 documento SSM è possibile specificare sistemi operativi differenti per plugin differenti. Il supporto multipiattaforma utilizza il parametro `precondition` all'interno di una fase, come mostrato nel seguente esempio. È possibile utilizzare il parametro `precondition` anche per convalidare i parametri di input definiti nel documento SSM. 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 di interpolazione dello schema della versione 2.2 con versioni SSM Agent precedenti alla 3.3.2746.0**
Nelle versioni SSM Agent precedenti alla 3.3.2746.0, l'agente ignora il parametro `interpolationType` ed esegue invece una sostituzione di stringhe non elaborate. Se si fa riferimento in modo esplicito a `SSM_parameter-name`, è necessario impostarlo in modo esplicito. Nell'esempio seguente per Linux, la variabile di ambiente `SSM_Message` viene referenziata in modo esplicito.
```
{
"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"
]
}
}
}
```
**Nota**
`allowedPattern` non è tecnicamente necessario, se un documento SSM non utilizza le parentesi graffe: `{{ }}`
**Esempio con State Manager per la versione dello schema 2.2**
È possibile utilizzare il seguente documento SSM con State Manager, uno strumento di Systems Manager, per scaricare e installare il software antivirus ClamAV. State Manager applica una configurazione specifica, per cui ogni volta che viene eseguita l'associazione a State Manager, 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 documento SSM con State Manager per raccogliere i metadati di inventario sulle 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 SSM `AWS-RunShellScript`. La sezione **runtimeConfig** include il 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 }}"
}
]
}
}
}
```
## Versione dello schema 0.3
**Elementi di primo livello**
L'esempio seguente mostra gli elementi di primo livello di un runbook Automation che utilizza la versione dello schema 0.3 in formato 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
}
}
}
```
**Esempio di runbook Automation YAML**
L'esempio seguente mostra il contenuto di un runbook Automation, in formato YAML. 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/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
```
## Esempi di gestione sicura dei parametri
Gli esempi seguenti illustrano la gestione sicura dei parametri mediante variabili `interpolationType` di ambiente.
### Esecuzione sicura dei comandi di base
Questo esempio mostra come gestire in modo sicuro un parametro di comando:
**Nota**
`allowedPattern` non è tecnicamente necessario, se un documento SSM non utilizza le doppie parentesi graffe: `{{ }}`
------
#### [ 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}}"
]
}
}]
}
```
------
### Utilizzo dei parametri nei linguaggi interpretati
Questo esempio dimostra la gestione sicura dei parametri in 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")
'
```
------
### Esempio di compatibilità retroattiva
Questo esempio mostra come gestire i parametri in modo sicuro mantenendo la compatibilità retroattiva:
------
#### [ 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"
```
------
**Nota**
`allowedPattern` non è tecnicamente necessario, se un documento SSM non utilizza le doppie parentesi graffe: `{{ }}`
## Best practice sulla sicurezza dei parametri
È necessario seguire queste best practice, quando si gestiscono i parametri nei documenti SSM:
+ **Utilizzo dell'interpolazione delle variabili di ambiente**: usare sempre `interpolationType: "ENV_VAR"` per i parametri di stringa che verranno utilizzati nelle esecuzioni dei comandi.
+ **Implementazione della convalida dell'input**: usare `allowedPattern` per limitare i valori dei parametri a modelli sicuri.
+ **Gestione dei sistemi legacy**: includere la logica di fallback per le versioni SSM Agent precedenti, che non supportano l'interpolazione delle variabili di ambiente.
+ **Evitare i caratteri speciali**: quando si utilizzano i valori dei parametri nei comandi, evitare adeguatamente i caratteri speciali, per impedire che la shell li interpreti.
+ **Limitazione dell'ambito dei parametri**: utilizzare i modelli di parametri più restrittivi possibili per il proprio caso d'uso.