Os documentos do AWS Systems Manager (SSM) usam as versões de esquema a seguir.
-
Os documentos do tipo
Commandpodem 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
Policydevem usar o esquema versão 2.0 ou posterior. -
Os documentos do tipo
Automationdevem usar o esquema versão 0.3. -
Os documentos do tipo
Sessiondevem 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.
Ao usar a versão de esquema mais recentes para documentos Command e Policy, você poderá aproveitar os seguintes recursos.
| Atributo | 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 |
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 ter mais informações, consulte Atualização do SSM Agent por meio de Run Command.
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 |
|
propriedades |
inputs |
Na versão 2.2, a seção |
|
Comandos da do |
runCommand |
Na versão 2.2, a seção |
|
id |
action |
Na versão 2.2, |
|
não aplicável |
nome |
Na versão 2.2, |
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. Opreconditionsuporta referenciar os parâmetros de entrada do documento SSM, eplatformTypeusando valores deLinux,MacOS, eWindows. Somente aStringEqualsé 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 doprecondition. 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.
---
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 do
Veja como o exemplo a seguir usa o plugin aws:runPowerShellScript para executar um comando do PowerShell nas instâncias de destino.
---
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 opreconditionpara validar os parâmetros de entrada definidos no documento do SSM. Veja isso no segundo exemplo a seguir.
---
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---
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-cliExemplo 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.
---
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 clamavExemplo 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.
---
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 }}"Exemplo de esquema versão 2.2 do AWS-ConfigureAWSPackage
O exemplo a seguir mostra o documento AWS-ConfigureAWSPackage. OmainStepsInclui a seçãoaws:configurePackageplugin noactionEtapa.
nota
Nos sistemas operacionais Linux, somente os pacotes AmazonCloudWatchAgent e AWSSupport-EC2Rescue são suportados.
---
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 oAWS-RunShellScriptDocumento 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/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