Elementi di dati e parametri

Questo argomento descrive gli elementi di dati utilizzati nei documenti SSM. La versione dello schema utilizzata per creare un documento definisce la sintassi e gli elementi di dati accettati. Per i documenti di comando è consigliabile utilizzare la versione dello schema 2.2 o successiva. I runbook di automazione utilizzano la versione dello schema 0.3. Inoltre, i runbook di automazione supportano l'uso di Markdown, un linguaggio di markup, che consente di aggiungere descrizioni in stile wiki ai documenti e alle singole fasi all'interno del documento. Per ulteriori informazioni sull'utilizzo di Markdown, consulta Utilizzo di Markdown nella console nella Guida alle operazioni di base di AWS Management Console .

La sezione seguente descrive gli elementi di dati che si possono includere in un documento SSM.

Elementi di dati di primo livello

schemaVersion

La versione dello schema da utilizzare.

Tipo: Versione

Campo obbligatorio: sì

description

Le informazioni fornite per descrivere lo scopo del documento. È inoltre possibile utilizzare questo campo per specificare se un parametro richiede un valore per l'esecuzione di un documento o se è facoltativo fornire un valore per il parametro. I parametri obbligatori e facoltativi possono essere visualizzati negli esempi in questo argomento.

▬Tipo: stringa

Campo obbligatorio: no

parametri

Una struttura che definisce i parametri accettati dal documento.

Per i parametri che usi spesso, ti consigliamo di memorizzare tali parametri inParameter Store, una capacità di AWS Systems Manager. Puoi quindi definire i parametri nel tuo documento che si riferiscono ai parametri Parameter Store come valore predefinito. Per fare riferimento al parametro Parameter Store, utilizza la sintassi seguente.

{{ssm:parameter-name}}

È possibile utilizzare un parametro che fa riferimento al parametro Parameter Store allo stesso modo di qualsiasi altro parametro del documento. Nell'esempio seguente, il valore predefinito per il parametro commands è il valore del parametro Parameter Store myShellCommands. Specificando il valore del parametro commands come stringa runCommand, il documento esegue i comandi memorizzati nel parametro 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

Puoi fare riferimento ai parametri String, StringList e Parameter Store nella sezione parameters del documento. Non si può fare riferimento ai parametri SecureString Parameter Store.

Per ulteriori informazioni su Parameter Store, consulta AWS Systems Manager Parameter Store.

Tipo: Struttura

La struttura parameters accetta i seguenti campi e valori:

• type: (Obbligatorio) I valori consentiti sono i seguenti: String, StringList, Integer, Boolean, MapList e StringMap. Per visualizzare esempi di ciascun tipo, consulta Esempi type di parametri di documenti SSM nella sezione successiva.

  Nota

  I documenti di tipo di comando supportano solo i tipi di parametri String e StringList.

• description: (facoltativo) La descrizione del parametro.

• default: (facoltativo) Il valore predefinito del parametro o un riferimento a un parametro in Parameter Store.

• allowedValues: (facoltativo) una matrice dei valori consentiti per il parametro. La definizione dei valori consentiti per il parametro convalida l'input dell'utente. Se un utente inserisce un valore non consentito, l'esecuzione non viene avviata.

  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: (facoltativo) un'espressione regolare che convalida se l'input dell'utente corrisponde al modello definito per il parametro. Se l'input dell'utente non corrisponde al modello consentito, l'esecuzione non viene avviata.

  Nota

  Systems Manager esegue due convalide per allowedPattern. La prima convalida viene eseguita utilizzando la libreria Java regex a livello di API quando si utilizza un documento. La seconda convalida viene eseguita su SSM Agent utilizzando la libreria di GO regexp prima di elaborare il 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: (Facoltativo) Utilizzato per visualizzare un textfield o un textarea in AWS Management Console. textfieldè una casella di testo a riga singola. textareaè un'area di testo su più righe.

• minItems: (facoltativo) Il numero minimo di elementi consentiti.

• maxItems: (facoltativo) Il numero massimo di elementi consentiti.

• minChars: (facoltativo) Il numero minimo di caratteri del parametro consentiti.

• maxChars: (facoltativo) Il numero massimo di caratteri del parametro consentiti.

Campo obbligatorio: no

variables

(Solo versione 0.3 dello schema) Valori a cui è possibile fare riferimento o da aggiornare durante i passaggi di un runbook di automazione. Le variabili sono simili ai parametri, ma presentano una differenza molto rilevante. Nel contesto di un runbook, i valori dei parametri sono statici mentre quelli delle variabili possono essere modificati. Quando si aggiorna il valore di una variabile, il tipo di dati deve corrispondere al tipo di dati definito. Per informazioni sull'aggiornamento dei valori delle variabili in un'automazione, consulta la pagina aws:updateVariable: aggiorna un valore per una variabile di runbook

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

Campo obbligatorio: no

YAML

variables:
    payload:
        type: StringMap
        default: "{}"

JSON

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

runtimeConfig

(Solo versione dello schema 1.2) La configurazione per l'istanza applicata da uno o più plugin di Systems Manager. Non è garantito che l'esecuzione dei plugin avvenga in sequenza.

Tipo: Dictionary<String, > PluginConfiguration

Campo obbligatorio: no

mainSteps

(Solo versione dello schema 0.3, 2.0 e 2.2) Un oggetto che può includere più fasi (plugin). I plugin sono definiti all'interno delle fasi. Le fasi vengono eseguite nell'ordine sequenziale indicato nel documento.

Tipo: Dictionary<String, > PluginConfiguration

Campo obbligatorio: sì

outputs

(Solo versione dello schema 0.3) Dati generati dall'esecuzione di questo documento che possono essere utilizzati in altri processi. Ad esempio, se il documento ne crea uno nuovoAMI, puoi specificare ". CreateImage ImageId"come valore di output, quindi utilizzate questo output per creare nuove istanze in una successiva esecuzione di automazione. Per ulteriori informazioni sugli output, consulta Utilizzo degli output delle operazioni come input.

Tipo: Dictionary<string, > OutputConfiguration

Campo obbligatorio: no

files

(Solo versione dello schema 0.3) I file di script (e i relativi checksum) collegati al documento ed eseguiti durante un'esecuzione dell'automazione. Si applica solo ai documenti che includono l'operazione aws:executeScript e per i quali gli allegati sono stati specificati in una o più fasi.

Per il supporto del runtime degli script, i runbook di automazione supportano gli script per Python 3.7, Python 3.8, Core 6.0 e 7.0. PowerShell PowerShell Per ulteriori informazioni sull'inclusione di script nei runbook di automazione, consultare Utilizzo di script nei runbook e Utilizzo di Document Builder (Generatore documenti) per la creazione di runbook.

Quando si crea un runbook di automazione con allegati, è inoltre necessario specificare i file allegati utilizzando l'--attachmentsopzione (for) o (per API e SDK). AWS CLIAttachments È possibile specificare la posizione del file sia per i file locali che per i file archiviati nei bucket Amazon Simple Storage Service (Amazon S3). Per ulteriori informazioni, consulta Attachments in the API Reference. 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

Campo obbligatorio: no

Esempi type di parametri di documenti SSM

I tipi di parametri nei documenti SSM sono statici. Ciò significa che il tipo di parametro non può essere modificato dopo che è stato definito. Quando si utilizzano parametri con plugin del documento SSM, il tipo di parametro non può essere modificato dinamicamente all'interno dell'input di un plugin. Ad esempio, non è possibile fare riferimento a un parametro Integer all'interno dell'input runCommand del plugin aws:runShellScript perché questo input accetta una stringa o un elenco di stringhe. Per utilizzare un parametro per un input di plugin, il tipo di parametro deve corrispondere al tipo accettato. Ad esempio, è necessario specificare un tipo di parametro Boolean per l'input allowDowngrade del plugin aws:updateSsmAgent. Se il tipo di parametro non corrisponde al tipo di input per un plugin, il documento SSM non viene convalidato e il sistema non crea il documento. Questo vale anche quando si utilizzano parametri a valle all'interno degli input per altri plugin o azioni di automazione. AWS Systems Manager Ad esempio, non è possibile fare riferimento a un parametro di StringList nell'input documentParameters del plugin aws:runDocument. L'input di documentParameters accetta una mappa di stringhe anche se il tipo di parametro del documento SSM a valle è un parametro StringList e corrisponde al parametro a cui si fa riferimento.

Quando si utilizzano parametri con operazioni di automazione di , nella maggior parte dei casi i tipi di parametro non vengono convalidati quando si crea il documento SSM. Solo quando si utilizza l'operazione aws:runCommand, i tipi di parametro vengono convalidati quando si crea il documento SSM. In tutti gli altri casi, la convalida dei parametri avviene durante l'esecuzione dell'automazione quando l'input di un'operazione viene verificato prima dell'esecuzione. Ad esempio, se il parametro di input è String e si fa riferimento ad esso come valore per l'input MaxInstanceCount dell'operazione aws:runInstances, viene creato il documento SSM. Tuttavia, quando si esegue il documento, l'automazione non riesce durante la convalida dell'operazione aws:runInstances perché l'input MaxInstanceCount richiede un valore Integer.

Di seguito sono riportati alcuni esempi di ciascun parametro type.

Stringa

Una sequenza di zero o più caratteri Unicode inclusa tra virgolette. Ad esempio, "i-1234567890abcdef0". Utilizza barre rovesciate come caratteri di escape.

YAML

---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."

JSON

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

StringList

Un elenco di elementi String separati da virgole. Ad esempio, ["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

Accetta solo true o false. Non accetta "true" o 0.

YAML

---
canRun:
  type: Boolean
  description: ''
  default: true

JSON

"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}

Numero intero

Numeri interi. Non accetta numeri decimali, ad esempio 3,14159, o numeri inclusi tra virgolette, ad esempio "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

Mappatura di chiavi a valori. Le chiavi e i valori devono essere stringhe. Ad esempio, {"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

Un elenco di oggetti. 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
}

Visualizzazione del contenuto del documento Command SSM

Per visualizzare in anteprima i parametri obbligatori e facoltativi per un documento di comando AWS Systems Manager (SSM), oltre alle azioni eseguite dal documento, è possibile visualizzare il contenuto del documento nella console Systems Manager.

Per visualizzare il contenuto del documento Command SSM

1. Aprire la AWS Systems Manager console all'indirizzo https://console.aws.amazon.com/systems-manager/.

2. Nel riquadro di navigazione, scegli Documenti.

3. Nella casella di ricerca selezionare Document type (Tipo di documento) e quindi selezionare Command (Comando).

4. Scegliere il nome di un documento, quindi la scheda Content (Contenuto).

5. Nel campo del contenuto esaminare i parametri e i passaggi delle operazioni disponibili per il documento.

   Ad esempio, l'immagine seguente mostra che (1) version e (2) allowDowngradesono parametri opzionali per il documento AWS-UpdateSSMAgent e che la prima operazione eseguita dal documento è (3) aws:updateSsmAgent.