View a markdown version of this page

데이터 요소 및 파마미터 - AWS Systems Manager

데이터 요소 및 파마미터

이 주제에서는 SSM 문서에 사용되는 데이터 요소를 설명합니다. 문서를 생성하는 데 사용되는 스키마 버전은 문서에서 허용하는 구문과 데이터 요소를 정의합니다. Command 문서에는 스키마 버전 2.2 이상을 사용하는 것이 좋습니다. Automation 런북은 스키마 버전 0.3을 사용합니다. 또한 Automation 런북에서는 Markdown을 사용할 수 있습니다. 마크업 언어인 Markdown을 사용하면 문서와 문서 내의 개별 단계에 wiki 스타일의 설명을 추가할 수 있습니다. 마크다운 사용에 대한 자세한 내용은 AWS Management Console 시작 안내서콘솔에서 마크다운 사용을 참조하세요.

다음 섹션에서는 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이 필요하지 않습니다.

자주 사용하는 파라미터의 경우 해당 파라미터를 Parameter Store에 저장하는 것이 좋습니다. 그런 다음 Parameter Store 파라미터를 기본값으로 참조하는 파라미터를 문서에서 정의할 수 있습니다. Parameter Store 파라미터를 참조하려면 다음 구문을 사용합니다.

{{ssm:parameter-name}}

다른 문서 파라미터와 동일한 방식으로 Parameter Store 파라미터를 참조하는 파라미터를 사용할 수 있습니다. 다음 예제에서 commands 파라미터의 기본값은 Parameter Store 파라미터 myShellCommands입니다. commands 파라미터를 runCommand 문자열로 지정하면 문서에서 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 }}"], interpolationType : 'ENV_VAR' allowedPattern: '^[^"]*$' 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 }}"], "interpolationType" : "ENV_VAR" } }, "mainSteps": [ { "action": "aws:runShellScript", "name": "runShellScriptDefaultParams", "inputs": { "runCommand": [ "{{ commands }}" ] } } ] }
참고

문서의 parameters 섹션에서 StringStringList Parameter Store 파라미터를 참조할 수 있습니다. SecureString Parameter Store 파라미터를 참조할 수 없습니다.

Parameter Store에 대한 자세한 내용은 AWS Systems Manager Parameter Store 섹션을 참조하세요.

형식: 구조

parameters 구조는 다음의 필드 및 값을 수락합니다.

  • type: (필수) 허용되는 값은 다음과 같습니다. String, StringList, Integer Boolean, MapList, StringMap. 각 유형의 예를 보려면 다음 단원의 SSM 문서 파라미터 type 예제를 참조하십시오.

    참고

    Command 유형 문서에서는 StringStringList 파라미터 유형만 지원합니다.

  • 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 라이브러리를 사용하여 수행됩니다. 두 번째 유효성 검사는 문서를 처리하기 전에 GO 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 - 런북 변수 값을 업데이트 섹션을 참조하세요.

형식: Boolean | Integer | MapList | String | StringList | StringMap

필수 여부: 아니요

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

(스키마 버전 1.2만 해당) 하나 이상의 Systems Manager 플러그인에 의해 적용되는 인스턴스 구성입니다. 플러그인은 순서대로 실행되지 않습니다.

형식: Dictionary<string,PluginConfiguration>

필수 여부: 아니요

mainSteps

(스키마 버전 0.3, 2.0 및 2.2만 해당) 여러 단계(플러그인)를 포함할 수 있는 객체입니다. 플러그인은 단계 내에서 정의됩니다. 단계는 이 문서에 나열된 순서대로 실행됩니다.

형식: Dictionary<string,PluginConfiguration>

필수 여부: 예

출력

(스키마 버전 0.3에만 해당) 이 문서를 실행하여 생성되었고 다른 프로세스에서 사용할 수 있는 데이터입니다. 예를 들어 문서에서 새 AMI를 생성하는 경우 출력 값으로 "CreateImage.ImageId"를 지정한 다음, 이 출력을 사용하여 후속 자동화 실행에서 새 인스턴스를 생성할 수 있습니다. 출력에 대한 자세한 내용은 작업 출력을 입력으로 사용 섹션을 참조하세요.

형식: Dictionary<string,OutputConfiguration>

필수 여부: 아니요

files

(스키마 버전 0.3에만 해당) 문서에 첨부되어 자동화 실행 중에 실행되는 스크립트 파일(및 해당 체크섬)입니다. aws:executeScript 작업을 포함하고 하나 이상의 단계에서 첨부 파일이 지정된 문서에만 적용됩니다.

Automation 런북에서 지원하는 런타임에 대한 자세한 내용은 aws:executeScript - 스크립트 실행 섹션을 참조하세요. Automation 런북에 스크립트 포함에 대한 자세한 내용은 런북에서 스크립트 사용Automation 런북의 시각적 디자인 경험 섹션을 참조하세요.

첨부 파일이 포함된 Automation 실행서를 생성할 때 옵션 --attachments(AWS CLI용) 또는 Attachments(API 및 SDK용)를 사용하여 첨부 파일을 지정해야 합니다. SSM 문서와 Amazon Simple Storage Service(Amazon S3) 버킷에 저장된 파일에 대해 파일 위치를 지정할 수 있습니다. 자세한 내용은 AWS Systems Manager API 참조의 첨부 파일을 참조하세요.

YAML
--- files: launch.py: checksums: sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": { "launch.py": { "checksums": { "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE" } } }

형식: Dictionary<string,FilesConfiguration>

필수 여부: 아니요

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이 포함될 수 있습니다.

YAML
--- InstanceId: type: String description: "(Optional) The target EC2 instance ID." interpolationType: ENV_VAR
JSON
"InstanceId":{ "type":"String", "description":"(Optional) The target EC2 instance ID.", "interpolationType": "ENV_VAR" }
StringList

쉼표로 구분된 문자열 항목의 목록입니다. 예를 들면 ["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" }
부울

true 또는 false만 허용됩니다. "true" 또는 0은 허용되지 않습니다.

YAML
--- canRun: type: Boolean description: '' default: true
JSON
"canRun": { "type": "Boolean", "description": "", "default": true }
Integer

정수입니다. 십진수(예: 3.14159) 또는 인용 부호로 묶인 숫자(예: "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

키-값 매핑입니다. 키와 값은 문자열이어야 합니다. 예를 들면 {"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

SfortMar 객체의 목록입니다.

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 }

SSM Command 문서 내용 보기

AWS Systems Manager(SSM) 문서에 대한 필수 및 옵션 파라미터를 미리 보기 위해 문서에서 실행하는 작업 외에도 Systems Manager 콘솔에서 문서의 내용을 볼 수 있습니다.

SSM Command 문서 내용을 보려면
  1. AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/)을 엽니다.

  2. 탐색 창에서 Documents를 선택합니다.

  3. 검색 상자에서 [문서 유형(Document type)]을 선택한 다음 [Command]를 선택합니다.

  4. 문서의 이름을 선택한 후 [콘텐츠(Content)] 탭을 선택합니다.

  5. 콘텐츠 필드에서 문서에 사용 가능한 파라미터와 작업 단계를 검토합니다.

    예를 들어 다음 이미지는 (1) version 및 (2) allowDowngradeAWS-UpdateSSMAgent 문서에 대한 옵션 파라미터이고 문서에서 실행되는 첫 번째 작업이 (3) aws:updateSsmAgent임을 보여줍니다.

    Systems Manager 콘솔에서 SSM 문서 내용 보기