• O AWS Systems Manager CloudWatch Dashboard não estará mais disponível a partir de 30 de abril de 2026. Os clientes podem continuar usando o console do Amazon CloudWatch para visualizar, criar e gerenciar os painéis do Amazon CloudWatch exatamente como fazem hoje. Para obter mais informações, consulte a [documentação do Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Esquemas, atributos e exemplos
AWS Systems ManagerOs documentos do (SSM) usam as versões de esquema a seguir.
+ Os documentos do tipo `Command` podem usar o esquema versão 1.2, 2.0 e 2.2. Se você usa documentos do esquema 1.2, recomendamos criar documentos que utilizem o esquema versão 2.2.
+ Os documentos do tipo `Policy` devem usar o esquema versão 2.0 ou posterior.
+ Os documentos do tipo `Automation` devem usar o esquema versão 0.3.
+ Os documentos do tipo `Session` devem usar o esquema versão 1.0.
+ Você pode criar documentos em JSON ou YAML.
Para obter mais informações sobre o esquema de documentos do `Session`, consulte [Esquema do documento de sessão](session-manager-schema.md).
Ao usar a versão de esquema mais recentes para documentos `Command` e `Policy`, você poderá aproveitar os seguintes recursos.
**Recursos de documentos da versão 2.2 do esquema**
| Recurso | Detalhes |
| --- | --- |
| Edição de documentos | Agora, documentos podem ser atualizados. Com a versão 1.2, qualquer atualização de um documento exigia que você o salvasse com um nome diferente. |
| Versionamento automático | Qualquer atualização de um documento cria uma nova versão. Esta não é uma versão de esquema, mas uma versão do documento. |
| Versão padrão | Se você possui várias versões de um documento, pode especificar qual delas é o documento padrão. |
| Sequenciamento | Os plugins ou as *etapas* em um documento são executados na ordem que você especificou. |
| Suporte entre plataformas | O suporte entre plataformas permite que você especifique diferentes sistemas operacionais para diferentes plugins dentro do mesmo documento do SSM. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa. |
| Interpolação de parâmetros | Interpolação significa inserir ou substituir um valor variável em uma string. Pense nisso como preencher um espaço em branco com valores reais antes que a string seja usada. No contexto de documentos do SSM, a interpolação de parâmetros permite que parâmetros de string sejam interpolados em variáveis de ambiente antes da execução do comando, fornecendo melhor segurança contra injeções de comando. Quando definido como `ENV_VAR`, o agente cria uma variável de ambiente denominada `SSM_{{parameter-name}}` que contém o valor do parâmetro. |
**nota**
Você deve manter o AWS Systems Manager SSM Agent atualizado em suas instâncias com a versão mais recente para usar os novos recursos do Systems Manager e os recursos de documento do SSM. Para obter mais informações, consulte [Atualização do SSM Agent por meio de Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
A tabela a seguir lista as diferenças entre as principais versões de esquema.
****
| Versão 1.2 | Versão 2.2 (versão mais recente) | Detalhes |
| --- | --- | --- |
| runtimeConfig | mainSteps | Na versão 2.2, a seção `mainSteps` substitui `runtimeConfig`. O`mainSteps`A seção permite que o Systems Manager execute etapas em sequência. |
| propriedades | inputs | Na versão 2.2, a seção `inputs` substitui a seção `properties`. A seção `inputs` aceita parâmetros para as etapas. |
| comandos | runCommand | Na versão 2.2, a seção `inputs` usa o parâmetro `runCommand` em vez do parâmetro `commands`. |
| id | ação | Na versão 2.2, `Action` substitui `ID`. Esta é apenas uma mudança de nome. |
| não aplicável | name | Na versão 2.2, `name` é um nome definido pelo usuário para uma etapa. |
**Usar o parâmetro precondition**
Com o esquema versão 2.2 ou superior, você pode usar o parâmetro `precondition` para especificar o sistema operacional de destino de cada plugin ou para validar parâmetros de entrada que você definiu em seu documento do SSM. O`precondition`suporta referenciar os parâmetros de entrada do documento SSM, e`platformType`usando valores de`Linux`,`MacOS`, e`Windows`. Somente a`StringEquals`é suportado.
Para documentos que utilizam o esquema versão 2.2 ou posterior, se a `precondition` não for especificada, cada plugin será executado ou ignorado com base na compatibilidade do plugin com o sistema operacional. Compatibilidade de plugins com o sistema operacional é avaliada antes do `precondition`. Para documentos que utilizam o esquema 2.0 ou anterior, os plugins incompatíveis geram um erro.
Por exemplo, em um documento com a versão 2.2 do esquema, se `precondition` não for especificado e o plugin `aws:runShellScript` estiver relacionado, a etapa será executada em instâncias do Linux, mas será ignorada pelo sistema em instâncias do Windows Server porque o `aws:runShellScript` não é compatível com instâncias do Windows Server. No entanto, para um documento de esquema versão 2.0, se você especificar o plugin `aws:runShellScript` e depois executar o documento em instâncias do Windows Server, a execução falhará. Você poderá ver um exemplo do parâmetro de pré-condição em um documento do SSM ainda nesta seção.
## Versão 2.2 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um documento do SSM usando o esquema versão 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}} }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2**
Veja como o exemplo a seguir usa o plugin `aws:runPowerShellScript` para executar um comando do PowerShell nas instâncias de destino.
------
#### [ 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}}"
]
}
}
]
}
```
------
**Exemplos do parâmetro precondition da versão 2.2 do esquema**
O esquema versão 2.2 fornece suporte para várias plataformas. Isso significa que, dentro de um único documento do SSM, você pode especificar diferentes sistemas operacionais para diferentes plugins. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa, como mostra o exemplo a seguir. Você também pode usar o`precondition`para validar os parâmetros de entrada definidos no documento do SSM. Veja isso no segundo exemplo a seguir.
------
#### [ 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"
]
}
}
]
}
```
------
**Exemplo de interpolação do esquema versão 2.2 com versões do SSM Agent anteriores à 3.3.2746.0**
Nas versões do SSM Agent anteriores à 3.3.2746.0, o agente ignora o parâmetro `interpolationType` e, em vez disso, executa uma substituição de string bruta. Se estiver referenciando `SSM_{{parameter-name}}` de forma explícita, você deve definir explicitamente. No exemplo a seguir para Linux, a variável de ambiente `SSM_Message` é referenciada explicitamente.
```
{
"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` não será tecnicamente necessário se um documento do SSM não usar chaves duplas: `{{ }}`
**Exemplo de esquema versão 2.2 do State Manager**
Você pode usar o seguinte documento do SSM com o State Manager, uma ferramenta do Systems Manager, para baixar e instalar o software antivírus ClamAV. O State Manager impõe uma configuração específica, o que significa que cada vez que a associação do State Manager for executada, o sistema verificará se o software ClamAV está instalado. Se não, o State Manager executa novamente esse 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"
]
}
}
]
}
```
------
**Exemplo de inventário do esquema versão 2.2**
Você pode usar o documento SSM a seguir com o State Manager para coletar metadados de inventário sobre suas instâncias.
------
#### [ 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 }}"
}
}
]
}
```
------
**Exemplo de esquema versão 2.2 do `AWS-ConfigureAWSPackage`**
O exemplo a seguir mostra o documento `AWS-ConfigureAWSPackage`. O`mainSteps`Inclui a seção`aws:configurePackage`plugin no`action`Etapa.
**nota**
Nos sistemas operacionais Linux, somente os pacotes `AmazonCloudWatchAgent` e `AWSSupport-EC2Rescue` são suportados.
------
#### [ 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 }}"
}
}
]
}
```
------
## Versão 1.2 do esquema
O exemplo a seguir mostra os elementos de nível superior de um documento do esquema versão 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}}"
}
]
}
}
}
```
**Exemplo de esquema versão 1.2 do `aws:runShellScript`**
O exemplo a seguir mostra o`AWS-RunShellScript`Documento do MUS do. A seção **runtimeConfig** inclui o 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 }}"
}
]
}
}
}
```
## Versão 0.3 do esquema
**Elementos de nível superior**
O exemplo a seguir mostra os elementos de nível superior de um runbook do Automation versão 0.3 do esquema no 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}}
}
}
}
```
**Exemplo de runbook de automação YAML**
O exemplo a seguir mostra o conteúdo de um runbook do Automation, no formato YAML. Este exemplo funcional da versão 0.3 do esquema do documento também demonstra o uso do Markdown para formatar descrições de documentos.
```
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
```
## Exemplos de tratamento seguro de parâmetros
Os exemplos a seguir demonstram o tratamento seguro de parâmetros usando a variável de ambiente `interpolationType`.
### Execução segura básica de comandos
Este exemplo mostra como tratar com segurança um parâmetro de comando:
**nota**
`allowedPattern` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
------
#### [ 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}}"
]
}
}]
}
```
------
### Uso de parâmetros em linguagens interpretadas
Este exemplo demonstra o tratamento seguro de parâmetros em 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")
'
```
------
### Exemplo de compatibilidade com versões anteriores
Este exemplo mostra como tratar parâmetros de forma segura enquanto mantém a compatibilidade com versões anteriores:
------
#### [ 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` não é tecnicamente exigido em documentos do SSM que não usam chaves duplas: `{{ }}`
## Práticas recomendadas de segurança de parâmetros
Siga estas práticas recomendadas ao tratar parâmetros em documentos do SSM:
+ **Use a interpolação de variáveis de ambiente**: sempre use `interpolationType: "ENV_VAR"` para parâmetros de string que serão usados na execução do comando.
+ **Implemente uma validação de entrada**: use `allowedPattern` para restringir os valores dos parâmetros a padrões seguros.
+ **Lide com sistemas legados**: inclua lógica de fallback para as versões anteriores do SSM Agent que não são compatíveis com a interpolação de variáveis de ambiente.
+ **Escape de caracteres especiais**: ao usar valores de parâmetros em comandos, escape adequadamente dos caracteres especiais para evitar a interpretação pelo shell.
+ **Limite o escopo do parâmetro**: use os padrões de parâmetros mais restritivos possíveis para seu caso de uso.