Elementos e parâmetros de dados - AWS Systems Manager
Elementos de dados de nível superiorExemplos de type de parâmetro de documentos SSMVisualizar o conteúdo do documento do SSM Command

Elementos e parâmetros de dados

Este tópico descreve os elementos de dados usados nos documentos do SSM. A versão do esquema usada para criar um documento define a sintaxe e os elementos de dados que o documento aceita. Recomendamos usar a versão 2.2 ou posterior do esquema para documentos do Command. Runbooks de automação usam o esquema versão 0.3. Além disso, runbooksde automação são compatíveis com o uso de Markdown, uma linguagem de marcação, que permite adicionar descrições de estilo wiki a documentos e etapas individuais dentro do documento. Para obter mais informações sobre o uso de Markdown, consulte Usar o Markdown no console no Guia de conceitos básicos do AWS Management Console.

A seção a seguir descreve os elementos de dados que você pode incluir em um documento SSM.

Elementos de dados de nível superior

schemaVersion

A versão do esquema a ser usada.

Tipo: versão

Obrigatório: Sim

description

Informações que você fornece para descrever a finalidade do documento. Você também pode usar esse campo para especificar se um parâmetro requer um valor para que um documento seja executado ou se fornecer um valor para o parâmetro é opcional. Parâmetros obrigatórios e opcionais podem ser vistos nos exemplos neste tópico.

Tipo: string

Obrigatório: Não

parâmetros

Uma estrutura que define os parâmetros que o documento aceita.

Para os parâmetros usados com frequência, recomendamos armazená-los no Parameter Store, uma capacidade do AWS Systems Manager. Em seguida, você pode definir parâmetros em seu documento que façam referência a parâmetros do Parameter Store como o valor padrão deles. Para fazer referência a um parâmetro do Parameter Store, use a sintaxe a seguir. 

{{ssm:parameter-name}}

Você pode usar um parâmetro que faça referência a um parâmetro do Parameter Store da mesma forma que faria com qualquer outro parâmetro de documento. No exemplo a seguir, o valor padrão para o parâmetro commands é o parâmetro myShellCommands do Parameter Store. Ao especificar o parâmetro commands como uma string runCommand, o documento executa os comandos armazenados no parâmetro myShellCommands.

YAML
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
  commands:
    type: StringList
    description: "(Required) The commands to run on the instance."
    default: ["{{ ssm:myShellCommands }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:
    - "{{ commands }}"
JSON
{
    "schemaVersion": "2.2",
    "description": "runShellScript with command strings stored as Parameter Store parameter",
    "parameters": {
      "commands": {
        "type": "StringList",
        "description": "(Required) The commands to run on the instance.",
        "default": ["{{ ssm:myShellCommands }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }
nota

Você pode fazer referência aos parâmetros String e StringList do Parameter Store na seção parameters do seu documento. Você não pode fazer referência a parâmetros SecureString do Parameter Store.

Para obter mais informações sobre o Parameter Store, consulte AWS Systems Manager Parameter Store.

Tipo: estrutura

A estrutura parameters aceita os seguintes campos e valores:

  • type: (obrigatório) os valores permitidos incluem os seguintes: String, StringList, Integer, Boolean, MapList e StringMap. Para ver exemplos de cada tipo, consulte Exemplos de type de parâmetro de documentos SSM na próxima seção.

    nota

    Os documentos do tipo de comando oferecem suporte somente aos tipos de parâmetros String e StringList.

  • description: (opcional) uma descrição do parâmetro.

  • default: (opcional) o valor padrão do parâmetro ou uma referência a um parâmetro no Parameter Store.

  • allowedValues: (opcional) uma matriz de valores permitidos para o parâmetro. A definição de valores permitidos para o parâmetro valida a entrada do usuário. Se um usuário inserir um valor que não é permitido, a execução falhará ao iniciar.

    YAML
    DirectoryType:
  type: String
  description: "(Required) The directory type to launch."
  default: AwsMad
  allowedValues:
  - AdConnector
  - AwsMad
  - SimpleAd
    JSON
    "DirectoryType": {
  "type": "String",
  "description": "(Required) The directory type to launch.",
  "default": "AwsMad",
  "allowedValues": [
    "AdConnector",
    "AwsMad",
    "SimpleAd"
  ]
}

  • allowedPattern: (opcional) uma expressão regular que valida se a entrada do usuário corresponde ao padrão definido para o parâmetro. Se a entrada do usuário não corresponder ao padrão permitido, a execução não será iniciada.

    nota

    O Systems Manager realiza duas validações para allowedPattern. A primeira validação é realizada usando a biblioteca de regex Java no nível da API quando você usa um documento. A segunda validação é realizada no SSM Agent usando a biblioteca de regex GO antes de processar o documento.

    YAML
    InstanceId:
  type: String
  description: "(Required) The instance ID to target."
  allowedPattern: "^i-[a-z0-9]{8,17}$"
  default: ''
    JSON
    "InstanceId": {
  "type": "String",
  "description": "(Required) The instance ID to target.",
  "allowedPattern": "^i-[a-z0-9]{8,17}$",
  "default": ""
}

  • displayType: (opcional) usado para exibir um textfield ou uma textarea no AWS Management Console. textfield é uma caixa de texto de uma única linha. textarea é uma área de texto de várias linhas.

  • minItems: (opcional) o número mínimo de itens permitidos.

  • maxItems: (opcional) o número máximo de itens permitidos.

  • minChars: (opcional) o número mínimo de caracteres de parâmetro permitidos.

  • maxChars: (opcional) o número máximo de caracteres de parâmetro permitidos.

Obrigatório: Não

variables

(Somente na versão 0.3 do esquema) Valores que podem ser referenciados ou atualizados em todas as etapas em um runbook de automação. As variáveis são semelhantes aos parâmetros, mas diferem de uma forma muito importante. Os valores dos parâmetros são estáticos no contexto de um runbook, mas os valores das variáveis podem ser alterados no contexto do runbook. Ao atualizar o valor de uma variável, o tipo de dados deve corresponder ao tipo de dados definido. Para informações sobre como atualizar valores de variáveis em uma automação, consulte aws:updateVariable: atualiza um valor para uma variável do runbook

Tipo: Boolean | Integer | MapList | String | StringList | StringMap

Obrigatório: Não

YAML
variables:
    payload:
        type: StringMap
        default: "{}"
JSON
{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}
runtimeConfig

(Esquema somente para a versão 1.2) A configuração para a instância conforme aplicada por um ou mais plugins do Systems Manager. Não há garantia de execução dos plugins em sequência.

Tipo: Dictionary<string,PluginConfiguration>

Obrigatório: Não

mainSteps

(Somente para versões 0.3, 2.0 e 2.2 do esquema) um objeto que pode incluir várias etapas (plugins). Plugins são definidos dentro de etapas. As etapas são executadas na ordem sequencial listada no documento.

Tipo: Dictionary<string,PluginConfiguration>

Obrigatório: Sim

outputs

(Somente versão 0.3 do esquema) dados gerados pela execução deste documento que podem ser usados em outros processos. Por exemplo, se o documento criar uma nova AMI, você poderá especificar "CreateImage.ImageId" como o valor de saída e usar essa saída para criar novas instâncias em uma execução de automação subsequente. Para obter mais informações sobre saídas, consulte Uso de saídas de ações como entradas.

Tipo: Dictionary<string,OutputConfiguration>

Obrigatório: Não

files

(Somente a versão 0.3 do esquema) os arquivos de script (e as respectivas somas de verificação) anexados ao documento e executados durante uma execução de automação. Aplica-se somente a documentos que incluem a ação aws:executeScript e para os quais anexos foram especificados em uma ou mais etapas.

Para suporte ao runtime de script, os runbooks do Automation atualmente são compatíveis com scripts para Python 3.7, Python 3.8, PowerShell Core 6.0 e PowerShell 7.0. Para obter mais informações sobre como incluir scripts em runbooks do Automation, consulte Uso de scripts em runbooks e Uso do Document Builder para criar runbooks.

Ao criar um runbook de automação com anexos, é necessário especificar arquivos de anexo usando a opção --attachments (na AWS CLI) ou Attachments (na API e no SDK). É possível especificar o local do arquivo para arquivos locais e arquivos armazenados nos buckets do Amazon Simple Storage Service (Amazon S3). Para obter mais informações, consulte Anexos na referência da API da AWS Systems Manager.

YAML
---
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}

Tipo: Dictionary<string,FilesConfiguration>

Obrigatório: Não

Exemplos de type de parâmetro de documentos SSM

Os tipos de parâmetro em documentos SSM são estáticos. Isso significa que o tipo de parâmetro não pode ser alterado depois de definido. Ao usar parâmetros com plugins de documento do , o tipo de um parâmetro não pode ser alterado dinamicamente dentro da entrada de um plugin. Por exemplo, você não pode fazer referência a um parâmetro Integer dentro da entrada runCommand do plugin aws:runShellScript porque essa entrada aceita uma string ou lista de strings. Para usar um parâmetro para uma entrada de plugin, o tipo de parâmetro deve corresponder ao tipo aceito. Por exemplo, você deve especificar um parâmetro de tipo Boolean para a entrada allowDowngrade do plugin aws:updateSsmAgent. Se o tipo de parâmetro não corresponder ao tipo de entrada de um plugin, o documento do não será validado e o sistema não criará o documento. Isso também é verdadeiro ao usar parâmetros downstream dentro de entradas para outros plugins ou ações do AWS Systems Manager Automation. Por exemplo, não é possível fazer referência a um parâmetro StringList dentro da entrada documentParameters do plugin aws:runDocument. A entrada documentParameters aceita um mapa de strings mesmo que o tipo de parâmetro de documento do SSM downtream seja um parâmetro StringList e corresponda ao parâmetro que você está referenciando.

Ao usar parâmetros com ações do Automation do , os tipos de parâmetro não são validados quando você cria o documento SSM na maioria dos casos. Somente quando você usa a ação aws:runCommand, os tipos de parâmetro são validados ao criar o documento SSM. Em todos os outros casos, a validação do parâmetro ocorre durante a execução da automação quando a entrada de uma ação é verificada antes de executar a ação. Por exemplo, se o parâmetro de entrada for uma String e você fizer referência a ele como o valor da entrada MaxInstanceCount da ação aws:runInstances, o documento SSM será criado. No entanto, ao executar o documento, a automação falha ao validar a ação aws:runInstances porque a entrada MaxInstanceCount requer um Integer.

Veja a seguir exemplos de cada parâmetro type.

String

Uma sequência de zero ou mais caracteres Unicode colocados entre aspas. Por exemplo, "i-1234567890abcdef0". Use barras invertidas como caractere de escape.

YAML
---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}
StringList

Uma lista de itens de strings separadas por vírgulas. Por exemplo, ["cd ~", "pwd"].

YAML
---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  minItems: 1
  displayType: textarea
JSON
"commands":{
  "type":"StringList",
  "description":"(Required) Specify a shell script or a command to run.",
  "minItems":1,
  "displayType":"textarea"
}
Booleano

Aceita somente true ou false. Não aceita "true" ou 0.

YAML
---
canRun:
  type: Boolean
  description: ''
  default: true
JSON
"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}
Inteiro

Números inteiros. Não aceita números decimais, como 3,14159, ou números colocados entre aspas, como "3".

YAML
---
timeout:
  type: Integer
  description: The type of action to perform.
  default: 100
JSON
"timeout": {
  "type": "Integer",
  "description": "The type of action to perform.",
  "default": 100    
}
StringMap

Um mapeamento de chaves para valores. Chaves e valores devem ser strings. Por exemplo, {"Env”: “Prod"}.

YAML
---
notificationConfig:
  type: StringMap
  description: The configuration for events to be notified about
  default:
    NotificationType: 'Command'
    NotificationEvents:
    - 'Failed'
    NotificationArn: "$dependency.topicArn"
  maxChars: 150
JSON
"notificationConfig" : {
  "type" : "StringMap",
  "description" : "The configuration for events to be notified about",
  "default" : {
    "NotificationType" : "Command",
    "NotificationEvents" : ["Failed"],
    "NotificationArn" : "$dependency.topicArn"
  },
  "maxChars" : 150
}
MapList

Uma lista de objetos StringMap.

YAML
blockDeviceMappings:
  type: MapList
  description: The mappings for the create image inputs
  default:
  - DeviceName: "/dev/sda1"
    Ebs:
      VolumeSize: "50"
  - DeviceName: "/dev/sdm"
    Ebs:
      VolumeSize: "100"
  maxItems: 2
JSON
"blockDeviceMappings":{
  "type":"MapList",
  "description":"The mappings for the create image inputs",
  "default":[
    {
      "DeviceName":"/dev/sda1",
      "Ebs":{
        "VolumeSize":"50"
      }
    },
    {
      "DeviceName":"/dev/sdm",
      "Ebs":{
        "VolumeSize":"100"
      }
    }
  ],
  "maxItems":2
}

Visualizar o conteúdo do documento do SSM Command

Para visualizar os parâmetros obrigatórios e opcionais para umAWS Systems ManagerDocumento de comando (SSM), além das ações executadas pelo documento, você pode visualizar o conteúdo do documento no console do Systems Manager.

Para visualizar o conteúdo do documento do Comando SSM

  1. Abra o console AWS Systems Manager em https://console.aws.amazon.com/systems-manager/.

  2. No painel de navegação, escolha Documents.

  3. Na caixa de pesquisa, selecioneTipo de documentoe, depois, selecioneComando.

  4. Selecione o nome de um documento existente e, em seguida, escolha a guia Content (Conteúdo).

  5. No campo de conteúdo, revise os parâmetros disponíveis e as etapas de ação para o documento.

    Por exemplo, a seguinte imagem mostra que (1) version e (2) allowDowngrade são parâmetros opcionais para o documento AWS-UpdateSSMAgent e que a primeira ação executada pelo documento é (3) aws:updateSsmAgent.

    Visualizar o conteúdo do documento do SSM no console do Systems Manager