Skema versi 2.2 Skema versi 1.2 Skema versi 0.3

Skema, fitur, dan contoh

AWS Systems Manager (SSM) dokumen menggunakan versi skema berikut.

Jenis dokumen Command dapat menggunakan skema versi 1.2, 2.0, dan 2.2. Jika Anda menggunakan skema dokumen 1.2, kami sarankan Anda membuat dokumen yang menggunakan skema versi 2.2.
Jenis dokumen Policy harus menggunakan skema versi 2.0 atau yang lebih baru.
Jenis dokumen Automation harus menggunakan skema versi 0.3.
Dokumen jenis Session harus menggunakan skema versi 1.0.
Anda dapat membuat dokumen di JSON atauYAML.

Untuk informasi selengkapnya tentang skema Session dokumen, lihatSkema dokumen sesi.

Dengan menggunakan versi skema terbaru untuk dokumen Command dan Policy, Anda dapat memanfaatkan fitur berikut.

Fitur dokumen skema versi 2.2
Fitur	Detail
Mengedit dokumen	Dokumen sekarang dapat diperbarui. Dengan versi 1.2, setiap update dokumen yang diperlukan yang Anda simpan dengan nama yang berbeda.
Versioning otomatis	Setiap pembaruan ke dokumen menciptakan versi baru. Ini bukan versi skema, tetapi versi dokumen.
Versi default	Jika Anda memiliki beberapa versi dokumen, Anda dapat menentukan yang mana versi dokumen default.
Pengurutan	Plugin atau Langkah dalam dokumen yang dijalankan sesuai urutan yang Anda tentukan.
Dukungan lintas platform	Dukungan lintas platform memungkinkan Anda menentukan sistem operasi yang berbeda untuk plugin yang berbeda dalam dokumen yang samaSSM. Dukungan lintas platform menggunakan parameter `precondition` dalam langkahnya.

catatan

Anda harus AWS Systems Manager SSM Agent terus memperbarui instans dengan versi terbaru untuk menggunakan fitur Systems Manager dan fitur SSM dokumen baru. Untuk informasi selengkapnya, lihat Memperbarui SSM Agent penggunaan Run Command.

Tabel berikut mencantumkan perbedaan antara versi utama skema.

Versi 1.2	Versi 2.2 (versi terbaru)	Detail
runtimeConfig	mainSteps	Di versi 2.2, `mainSteps` menggantikan bagian `runtimeConfig`. Bagian `mainSteps` memungkinkan Systems Manager untuk menjalankan langkah-langkah secara berurutan.
properti	masukan	Di versi 2.2, bagian `inputs` menggantikan bagian `properties`. Bagian `inputs` menerima langkah-langkah parameter.
perintah	runCommand	Di versi 2.2,bagian `inputs` mengambil parameter `runCommand` bukan parameter `commands`.
id	tindakan	Versi 2.2, `Action` menggantikan `ID`. Ini hanya perubahan nama.
tidak berlaku	nama	Versi 2.2, `name` adalah nama yang ditetapkan oleh pengguna untuk langkah.

Menggunakan parameter prasyarat

Dengan skema versi 2.2 atau yang lebih baru, Anda dapat menggunakan precondition parameter untuk menentukan sistem operasi target untuk setiap plugin atau untuk memvalidasi parameter input yang telah Anda tentukan dalam dokumen AndaSSM. preconditionParameter mendukung referensi parameter input SSM dokumen Anda, dan platformType menggunakan nilaiLinux,MacOS, danWindows. Hanya StringEquals operator yang didukung.

Untuk dokumen yang menggunakan skema versi 2.2 atau yang terbaru, jika precondition tidak ditentukan, setiap plugin yang dijalankan atau dilewati berdasarkan kompatibilitas plugin dengan sistem operasi. Kompatibilitas plugin dengan sistem operasi dievaluasi sebelum precondition. Untuk dokumen yang menggunakan skema 2.0 atau sebelumnya, plugin yang tidak kompatibel akan membuang kesalahan.

Sebagai contoh, dalam dokumen skema versi 2.2, jika precondition tidak dispesifikasikan dan plugin aws:runShellScript yang terdaftar, maka langkah yang berjalan pada instans Linux, tetapi melewati sistem instans Windows Server karena aws:runShellScript tidak kompatibel dengan instans Windows Server. Namun, untuk dokumen skema versi 2.0, jika Anda menentukan plugin aws:runShellScript, dan kemudian menjalankan dokumen pada instans Windows Server, eksekusi akan gagal. Anda dapat melihat contoh parameter prasyarat dalam SSM dokumen nanti di bagian ini.

Skema versi 2.2

Elemen tingkat atas

Contoh berikut menunjukkan elemen tingkat atas SSM dokumen menggunakan skema versi 2.2.

Contoh skema versi 2.2

Contoh berikut menggunakan aws:runPowerShellScript plugin untuk menjalankan PowerShell perintah pada instance target.

Skema versi 2.2 contoh parameter prasyarat

Skema versi 2.2 menyediakan dukungan lintas-platform. Ini berarti bahwa dalam satu SSM dokumen Anda dapat menentukan sistem operasi yang berbeda untuk plugin yang berbeda. Dukungan lintas platform dalam setiap langkah menggunakan parameter precondition, seperti yang ditunjukkan dalam contoh berikut. Anda juga dapat menggunakan precondition parameter untuk memvalidasi parameter input yang telah Anda tentukan dalam SSM dokumen Anda. Anda dapat melihat ini di kedua contoh berikut.

Contoh skema versi 2.2 State Manager

Anda dapat menggunakan SSM dokumen berikut denganState Manager, kemampuan Systems Manager, untuk mengunduh dan menginstal perangkat lunak antivirus ClamAV. State Managermemberlakukan konfigurasi tertentu, yang berarti bahwa setiap kali State Manager asosiasi dijalankan, sistem memeriksa untuk melihat apakah perangkat lunak ClamAV diinstal. Jika tidak, State Manager jalankan kembali dokumen ini.

Contoh inventaris skema versi 2.2

Anda dapat menggunakan SSM dokumen berikut State Manager untuk mengumpulkan metadata inventaris tentang instans Anda.

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 }}"
         }
      }
   ]
}

Contoh skema versi 2.2 `AWS-ConfigureAWSPackage`

Contoh berikut menunjukkan dokumen AWS-ConfigureAWSPackage. Bagian mainSteps mencakup plugin aws:configurePackage di langkah action.

catatan

Pada sistem operasi Linux, hanya paket AmazonCloudWatchAgent dan AWSSupport-EC2Rescue yang didukung.

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 }}"
         }
      }
   ]
}

Skema versi 1.2

Contoh berikut menunjukkan unsur-unsur tingkat atas dokumen skema versi 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"
            }
         ]
      }
   }
}

Contoh skema versi 1.2 `aws:runShellScript`

Contoh berikut menunjukkan AWS-RunShellScript SSM dokumen. runtimeConfigBagian ini mencakup aws:runShellScript plugin.


{
    "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 }}"
                }
            ]
        }
    }
}

Skema versi 0.3

Elemen tingkat atas

Contoh berikut menunjukkan elemen tingkat atas dari skema versi 0.3 Automation runbook dalam format. 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
        }
    }
}

YAMLContoh runbook otomatisasi

Contoh berikut menunjukkan isi runbook Otomasi, dalam YAML format. Contoh kerja ini dari skema dokumen versi 0.3 juga menunjukkan penggunaan Potongan harga untuk memformat deskripsi dokumen.


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

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Komponen dokumen

Elemen dan parameter data

Skema, fitur, dan contoh

catatan

Menggunakan parameter prasyarat

Skema versi 2.2

Elemen tingkat atas

Contoh skema versi 2.2

Skema versi 2.2 contoh parameter prasyarat

Contoh skema versi 2.2 State Manager

Contoh inventaris skema versi 2.2

Contoh skema versi 2.2 AWS-ConfigureAWSPackage

catatan

Skema versi 1.2

Contoh skema versi 1.2 aws:runShellScript

Skema versi 0.3

Elemen tingkat atas

YAMLContoh runbook otomatisasi

Contoh skema versi 2.2 `AWS-ConfigureAWSPackage`

Contoh skema versi 1.2 `aws:runShellScript`