• AWS Systems Manager CloudWatch 대시보드는 2026년 4월 30일 이후에는 더 이상 사용할 수 없습니다. 고객은 Amazon CloudWatch 콘솔을 계속 사용하여 현재와 마찬가지로 Amazon CloudWatch 대시보드를 보고, 생성하고, 관리할 수 있습니다. 자세한 내용은 [Amazon CloudWatch 대시보드 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)를 참조하세요.
# 데이터 요소 및 파마미터
이 주제에서는 SSM 문서에 사용되는 데이터 요소를 설명합니다. 문서를 생성하는 데 사용되는 스키마 버전은 문서에서 허용하는 구문과 데이터 요소를 정의합니다. Command 문서에는 스키마 버전 2.2 이상을 사용하는 것이 좋습니다. Automation 런북은 스키마 버전 0.3을 사용합니다. 또한 Automation 런북에서는 Markdown을 사용할 수 있습니다. 마크업 언어인 Markdown을 사용하면 문서와 문서 내의 개별 단계에 wiki 스타일의 설명을 추가할 수 있습니다. 마크다운 사용에 대한 자세한 내용은 AWS Management Console 시작 안내서의 [콘솔에서 마크다운 사용](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)을 참조하세요.
다음 섹션에서는 SSM 문서에 포함할 수 있는 데이터 요소에 대해 설명합니다.
## 최상위 데이터 요소
**schemaVersion**
사용할 스키마 버전입니다.
형식: 버전
필수 여부: 예
**description**
문서 목적을 설명하는 정보입니다. 또한 이 필드를 사용하여 파라미터에 문서 실행 값이 필요한지 또는 파라미터 값을 제공하는 것이 선택 사항인지 여부를 지정할 수 있습니다. 필수 파라미터와 선택적 파라미터는 이 주제의 예에서 볼 수 있습니다.
유형: 문자열
필수 여부: 아니요
**parameters**
문서가 허용하는 파라미터를 정의하는 구조입니다.
문자열 파라미터를 처리할 때 보안을 강화하기 위해 `interpolationType` 속성을 지정하여 환경 변수 보간을 사용할 수 있습니다. `ENV_VAR`로 설정하면 파라미터 값이 포함된 `SSM_parameter-name`이라는 이름으로 환경 변수가 생성됩니다.
다음은 환경 변수 `interpolationType`을 사용하는 파라미터의 예입니다.
```
{
"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}}"
]
}
}
}
```
이중 중괄호(`{{ }}`)를 사용하지 않는 SSM 문서에서는 기술적으로 `allowedPattern`이 필요하지 않습니다.
자주 사용하는 파라미터의 경우 AWS Systems Manager의 도구인 Parameter Store에 해당 파라미터를 저장하는 것이 좋습니다. 그런 다음 Parameter Store 파라미터를 기본값으로 참조하는 파라미터를 문서에서 정의할 수 있습니다. Parameter Store 파라미터를 참조하려면 다음 구문을 사용합니다.
```
{{ssm:parameter-name}}
```
다른 문서 파라미터와 동일한 방식으로 Parameter Store 파라미터를 참조하는 파라미터를 사용할 수 있습니다. 다음 예제에서 `commands` 파라미터의 기본값은 Parameter Store 파라미터 `myShellCommands`입니다. `commands` 파라미터를 `runCommand` 문자열로 지정하면 문서에서 `myShellCommands` 파라미터에 저장된 명령을 실행합니다.
```
---
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 }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"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 }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
문서의 `parameters` 섹션에서 `String` 및 `StringList` Parameter Store 파라미터를 참조할 수 있습니다. `SecureString` Parameter Store 파라미터를 참조할 수 없습니다.
Parameter Store에 대한 자세한 내용은 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md) 섹션을 참조하세요.
형식: 구조
`parameters` 구조는 다음의 필드 및 값을 수락합니다.
+ `type`: (필수) 허용되는 값은 다음과 같습니다. `String`, `StringList`, `Integer` `Boolean`, `MapList`, `StringMap`. 각 유형의 예를 보려면 다음 단원의 [SSM 문서 파라미터 `type` 예제](#top-level-properties-type)를 참조하십시오.
**참고**
Command 유형 문서에서는 `String` 및 `StringList` 파라미터 유형만 지원합니다.
+ `description`: (선택 사항) 파라미터에 대한 설명입니다.
+ `default`: (선택 사항) 파라미터의 기본값 또는 Parameter Store 내 파라미터에 대한 참조입니다.
+ `allowedValues`: (선택 사항) 파라미터에 허용되는 값의 배열입니다. 파라미터에 허용된 값을 정의하면 사용자 입력이 검증됩니다. 사용자가 허용되지 않는 값을 입력하면 실행이 시작되지 않습니다.
------
#### [ 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`: (선택 사항) 사용자 입력이 파라미터에 대해 정의된 패턴과 일치하는지 여부를 확인하는 정규 표현식입니다. 사용자 입력이 허용된 패턴과 일치하지 않으면 실행이 시작되지 않습니다.
**참고**
Systems Manager는 `allowedPattern`에 대한 두 가지 검증을 수행합니다. 첫 번째 유효성 검사는 문서를 사용할 때 API 레벨에서 [Java regex 라이브러리](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)를 사용하여 수행됩니다. 두 번째 유효성 검사는 문서를 처리하기 전에 [GO regexp 라이브러리](https://pkg.go.dev/regexp)를 사용하여 SSM Agent에서 수행됩니다.
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (선택 사항) AWS Management Console에서 `textfield` 또는 `textarea`를 표시하는 데 사용됩니다. `textfield`는 한 줄 텍스트 상자이고, `textarea`는 여러 줄 텍스트 상자입니다.
+ `minItems`: (선택 사항) 허용되는 최소 항목 수입니다.
+ `maxItems`: (선택 사항) 허용되는 최대 항목 수입니다.
+ `minChars`: (선택 사항) 허용되는 파라미터 문자 최소 개수입니다.
+ `maxChars`: (선택 사항) 허용되는 파라미터 문자 최대 개수입니다.
+ `interpolationType`: (선택 사항) 명령 실행 전에 파라미터 값을 처리하는 방법을 정의합니다. `ENV_VAR`로 설정하면 파라미터 값을 `SSM_parameter-name`이라는 환경 변수로 사용할 수 있습니다. 이 기능은 파라미터 값을 리터럴 문자열로 처리하여 명령 주입을 방지하는 데 도움이 됩니다.
타입: 문자열
유효한 값: `ENV_VAR`
필수 여부: 아니요
**variables**
(스키마 버전 0.3만 해당) Automation 런북의 전체 단계에서 참조하거나 업데이트할 수 있는 값입니다. 변수는 파라미터와 비슷하지만 매우 중요한 점에서 다릅니다. 런북의 컨텍스트에서는 파라미터 값이 고정되어 있지만 런북의 컨텍스트에서 변수 값을 변경할 수 있습니다. 변수 값을 업데이트할 때 데이터 유형은 정의된 데이터 유형과 일치해야 합니다. 자동화에서 변수 값을 업데이트하는 방법에 대한 자세한 내용은 [`aws:updateVariable` - 런북 변수 값을 업데이트](automation-action-update-variable.md) 섹션을 참조하세요.
형식: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
필수 여부: 아니요
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(스키마 버전 1.2만 해당) 하나 이상의 Systems Manager 플러그인에 의해 적용되는 인스턴스 구성입니다. 플러그인은 순서대로 실행되지 않습니다.
형식: Dictionary
필수 여부: 아니요
**mainSteps**
(스키마 버전 0.3, 2.0 및 2.2만 해당) 여러 단계(플러그인)를 포함할 수 있는 객체입니다. 플러그인은 단계 내에서 정의됩니다. 단계는 이 문서에 나열된 순서대로 실행됩니다.
형식: Dictionary
필수 여부: 예
**출력**
(스키마 버전 0.3에만 해당) 이 문서를 실행하여 생성되었고 다른 프로세스에서 사용할 수 있는 데이터입니다. 예를 들어 문서에서 새 AMI를 생성하는 경우 출력 값으로 "CreateImage.ImageId"를 지정한 다음, 이 출력을 사용하여 후속 자동화 실행에서 새 인스턴스를 생성할 수 있습니다. 출력에 대한 자세한 내용은 [작업 출력을 입력으로 사용](automation-action-outputs-inputs.md) 섹션을 참조하세요.
형식: Dictionary
필수 여부: 아니요
**files**
(스키마 버전 0.3에만 해당) 문서에 첨부되어 자동화 실행 중에 실행되는 스크립트 파일(및 해당 체크섬)입니다. `aws:executeScript` 작업을 포함하고 하나 이상의 단계에서 첨부 파일이 지정된 문서에만 적용됩니다.
Automation 런북에서 지원하는 런타임에 대한 자세한 내용은 [`aws:executeScript` - 스크립트 실행](automation-action-executeScript.md) 섹션을 참조하세요. Automation 런북에 스크립트 포함에 대한 자세한 내용은 [런북에서 스크립트 사용](automation-document-script-considerations.md) 및 [Automation 런북의 시각적 디자인 경험](automation-visual-designer.md) 섹션을 참조하세요.
첨부 파일이 포함된 Automation 실행서를 생성할 때 옵션 `--attachments`(AWS CLI용) 또는 `Attachments`(API 및 SDK용)를 사용하여 첨부 파일을 지정해야 합니다. SSM 문서와 Amazon Simple Storage Service(Amazon S3) 버킷에 저장된 파일에 대해 파일 위치를 지정할 수 있습니다. 자세한 내용은 AWS Systems Manager API 참조의 [첨부 파일](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)을 참조하세요.
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
형식: Dictionary
필수 여부: 아니요
## SSM 문서 파라미터 `type` 예제
SSM 문서의 파라미터 유형은 정적입니다. 즉, 파라미터 유형을 정의한 후에는 변경할 수 없습니다. SSM 문서 플러그인과 함께 파라미터를 사용하는 경우 파라미터 유형을 플러그인의 입력 내에서 동적으로 변경할 수 없습니다. 예를 들어 이러한 입력은 문자열이나 문자열 목록을 허용하기 때문에 `aws:runShellScript` 플러그인의 `runCommand` 입력 내에서 `Integer` 파라미터를 참조할 수 없습니다. 플러그인 입력에 파라미터를 사용하려면 파라미터 유형이 허용되는 유형과 일치해야 합니다. 예를 들어 `aws:updateSsmAgent` 플러그인의 `allowDowngrade` 입력에 대해 `Boolean` 유형 파라미터를 지정해야 합니다. 파라미터 유형이 플러그인의 입력 유형과 일치하지 않으면 SSM 문서 검증에 실패하고 시스템에서는 문서를 생성하지 않습니다. 이는 다른 플러그 인 또는 AWS Systems Manager Automation 작업에 대한 입력 내에서 파라미터 다운스트림을 사용할 때도 마찬가지입니다. 예를 들어 `aws:runDocument` 플러그 인의 `documentParameters` 입력 내에서 `StringList` 파라미터를 참조할 수 없습니다. `documentParameters` 입력은 다운스트림 SSM 문서 파라미터 유형이 `StringList` 파라미터이고 참조하는 파라미터와 일치하더라도 문자열 맵을 허용합니다.
Automation 작업에서 파라미터를 사용할 때, 대부분의 경우 SSM 문서 생성 시 파라미터 유형을 검증하지 않습니다. `aws:runCommand` 작업을 사용하는 경우에만 SSM 문서 생성 시 파라미터 유형이 검증됩니다. 다른 모든 경우에는 작업을 실행하기 전에 작업의 입력이 확인되면 자동화 실행 중에 파라미터 검증이 수행됩니다. 예를 들어 입력 파라미터가 `String`이고 이를 `aws:runInstances` 작업의 `MaxInstanceCount` 입력 값으로 참조하면 SSM 문서가 생성됩니다. 그러나 문서 실행 시 `MaxInstanceCount` 입력에 `Integer`가 필요하기 때문에 `aws:runInstances` 작업을 검증하는 중에 자동화가 실패합니다.
다음은 각 파라미터 `type`의 예입니다.
문자열
인용 부호로 묶인 0개 이상의 유니코드 문자 시퀀스입니다. 예를 들면 "i-1234567890abcdef0"입니다. 패치 기준에서 특정 분류 및 심각도 수준의 모든 패치가 설치 승인을 받도록 지정할 수 있습니다.
문자열 파라미터에는 보안 강화를 위해 환경 변수 보간을 활성화하는 선택적 `interpolationType` 필드 및 값 `ENV_VAR`이 포함될 수 있습니다.
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
쉼표로 구분된 문자열 항목의 목록입니다. 예를 들면 ["cd \$1”, “pwd”]입니다.
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
부울
`true` 또는 `false`만 허용됩니다. "true" 또는 0은 허용되지 않습니다.
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
Integer
정수입니다. 십진수(예: 3.14159) 또는 인용 부호로 묶인 숫자(예: "3")는 허용되지 않습니다.
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
키-값 매핑입니다. 키와 값은 문자열이어야 합니다. 예를 들면 \$1"Env”: “Prod”\$1입니다.
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
SfortMar 객체의 목록입니다.
```
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
```
```
"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
}
```
## SSM Command 문서 내용 보기
AWS Systems Manager(SSM) 문서에 대한 필수 및 옵션 파라미터를 미리 보기 위해 문서에서 실행하는 작업 외에도 Systems Manager 콘솔에서 문서의 내용을 볼 수 있습니다.
**SSM Command 문서 내용을 보려면**
1. AWS Systems Manager 콘솔([https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/))을 엽니다.
1. 탐색 창에서 **Documents**를 선택합니다.
1. 검색 상자에서 [**문서 유형(Document type)**]을 선택한 다음 [**Command**]를 선택합니다.
1. 문서의 이름을 선택한 후 [**콘텐츠(Content)**] 탭을 선택합니다.
1. 콘텐츠 필드에서 문서에 사용 가능한 파라미터와 작업 단계를 검토합니다.
예를 들어 다음 이미지는 (1) `version` 및 (2) `allowDowngrade`가 `AWS-UpdateSSMAgent` 문서에 대한 옵션 파라미터이고 문서에서 실행되는 첫 번째 작업이 (3) `aws:updateSsmAgent`임을 보여줍니다.
![\[Systems Manager 콘솔에서 SSM 문서 내용 보기\]](http://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/images/view-document-content.png)