Skema, fitur, dan contoh - AWS Systems Manager

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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 atau YAML.

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 mengizinkan Anda untuk menentukan sistem operasi yang berbeda untuk plugin yang berbeda dalam dokumen SSM yang sama. Dukungan lintas platform menggunakan parameter precondition dalam langkahnya.

catatan

Anda harus menjaga AWS Systems Manager SSM Agent pada instans Anda yang diperbarui dengan versi terbaru untuk menggunakan fitur Systems Manager baru dan fitur dokumen SSM. 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 parameter precondition untuk menentukan target sistem operasi untuk setiap plugin atau untuk memvalidasi parameter input yang telah Anda tetapkan dalam dokumen SSM Anda. Parameter precondition mendukung referensi parameter input dokumen SSM Anda, dan platformType menggunakan nilai dari Linux, MacOS, dan Windows. 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.

Misalnya, dalam dokumen skema versi 2.2, jika precondition tidak ditentukan dan aws:runShellScript plugin terdaftar, maka langkahnya berjalan pada instance Linux, tetapi sistem melewatkannya Windows Server contoh karena aws:runShellScript tidak kompatibel dengan Windows Server contoh. Namun, untuk dokumen skema versi 2.0, jika Anda menentukan aws:runShellScript plugin, dan kemudian menjalankan dokumen pada Windows Server contoh, eksekusi gagal. Anda dapat melihat contoh parameter prasyarat dalam dokumen SSM nanti di bagian ini.

Skema versi 2.2

Elemen tingkat atas

Contoh berikut menunjukkan elemen-elemen tingkat atas dari dokumen SSM menggunakan skema versi 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 }}" } } ] }
Contoh skema versi 2.2

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

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}}" ] } } ] }
Skema versi 2.2 contoh parameter prasyarat

Skema versi 2.2 menyediakan dukungan lintas-platform. Ini berarti bahwa dalam satu dokumen SSM 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 parameter precondition untuk memvalidasi parameter input yang telah ditetapkan dalam dokumen SSM Anda. Anda dapat melihat ini di kedua contoh berikut.

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" ] } } ] }
Skema versi 2.2 State Manager contoh

Anda dapat menggunakan dokumen SSM berikut dengan State Manager, alat di Systems Manager, untuk mengunduh dan menginstal perangkat lunak antivirus ClamAV. State Manager memberlakukan konfigurasi tertentu, yang berarti bahwa setiap kali State Manager asosiasi dijalankan, sistem memeriksa untuk melihat apakah perangkat lunak ClamAV diinstal. Jika tidak, State Manager menjalankan ulang dokumen ini.

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" ] } } ] }
Contoh inventaris skema versi 2.2

Anda dapat menggunakan dokumen SSM berikut dengan 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 Dokumen SSM AWS-RunShellScript. Bagian runtimeConfig mencakup 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 }}" } ] } } }

Skema versi 0.3

Elemen tingkat atas

Contoh berikut menunjukkan elemen-elemen tingkat atas dari skema versi 0.3 runbook otomatisasi 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 } } }
Contoh runbook otomatisasi YAML

Contoh berikut menunjukkan isi dari sebuah runbook otomatisasi, dalam format YAML. 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