• AWS Systems Manager CloudWatch Dasbor tidak akan lagi tersedia setelah 30 April 2026. Pelanggan dapat terus menggunakan CloudWatch konsol Amazon untuk melihat, membuat, dan mengelola CloudWatch dasbor Amazon mereka, seperti yang mereka lakukan hari ini. Untuk informasi selengkapnya, lihat [dokumentasi CloudWatch Dasbor Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
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, lihat[Skema dokumen sesi](session-manager-schema.md).
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. |
| Interpolasi parameter | Interpolasi berarti menyisipkan atau mengganti nilai variabel ke dalam string. Anggap saja sebagai mengisi ruang kosong dengan nilai aktual sebelum string digunakan. Dalam konteks dokumen SSM, interpolasi parameter memungkinkan parameter string diinterpolasi ke dalam variabel lingkungan sebelum eksekusi perintah, memberikan keamanan yang lebih baik terhadap injeksi perintah. Ketika diatur ke`ENV_VAR`, agen menciptakan variabel lingkungan bernama `SSM_{{parameter-name}}` yang berisi nilai parameter. |
**catatan**
Anda harus AWS Systems Manager SSM Agent terus memperbarui instans dengan versi terbaru untuk menggunakan fitur Systems Manager dan fitur dokumen SSM yang baru. Untuk informasi selengkapnya, lihat [Memperbarui SSM Agent penggunaan Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
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.
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 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"
]
}
}
]
}
```
------
**Contoh interpolasi skema versi 2.2 dengan SSM Agent versi sebelum 3.3.2746.0**
Pada SSM Agent versi sebelum 3.3.2746.0, agen mengabaikan `interpolationType` parameter dan sebagai gantinya melakukan substitusi string mentah. Jika Anda mereferensikan `SSM_{{parameter-name}}` secara eksplisit, Anda harus mengatur ini secara eksplisit. Dalam contoh berikut untuk Linux, variabel `SSM_Message` lingkungan direferensikan secara eksplisit.
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**catatan**
`allowedPattern`tidak diperlukan secara teknis jika dokumen SSM tidak menggunakan kawat gigi ganda: `{{ }}`
**Contoh skema versi 2.2 State Manager**
Anda dapat menggunakan dokumen SSM berikut denganState Manager, alat di 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.
------
#### [ 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 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/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
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.11
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.11
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
```
## Contoh penanganan parameter aman
Contoh berikut menunjukkan penanganan parameter aman menggunakan variabel lingkungan`interpolationType`.
### Eksekusi perintah aman dasar
Contoh ini menunjukkan cara menangani parameter perintah dengan aman:
**catatan**
`allowedPattern`tidak diperlukan secara teknis dalam dokumen SSM yang tidak menggunakan kawat gigi ganda: `{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### Menggunakan parameter dalam bahasa yang ditafsirkan
Contoh ini menunjukkan penanganan parameter aman di Python:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Contoh kompatibilitas mundur
Contoh ini menunjukkan cara menangani parameter dengan aman sambil mempertahankan kompatibilitas mundur:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**catatan**
`allowedPattern`tidak diperlukan secara teknis dalam dokumen SSM yang tidak menggunakan kawat gigi ganda: `{{ }}`
## Praktik terbaik keamanan parameter
Ikuti praktik terbaik ini saat menangani parameter dalam dokumen SSM:
+ **Gunakan interpolasi variabel lingkungan** - Selalu gunakan `interpolationType: "ENV_VAR"` untuk parameter string yang akan digunakan dalam eksekusi perintah.
+ **Implementasikan validasi masukan** - Gunakan `allowedPattern` untuk membatasi nilai parameter ke pola aman.
+ **Menangani sistem lama** - Sertakan logika fallback untuk SSM Agent versi lama yang tidak mendukung interpolasi variabel lingkungan.
+ **Melarikan diri dari karakter khusus** - Saat menggunakan nilai parameter dalam perintah, lepaskan karakter khusus dengan benar untuk mencegah interpretasi oleh shell.
+ **Batasi cakupan parameter** - Gunakan pola parameter yang paling ketat untuk kasus penggunaan Anda.