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

데이터 요소 및 파마미터

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

다음 섹션에서는 SSM 문서에 포함할 수 있는 데이터 요소에 대해 설명합니다.

최상위 데이터 요소

schemaVersion

사용할 스키마 버전입니다.

형식: 버전

필수 여부: 예

설명

문서 목적을 설명하는 정보입니다. 또한 이 필드를 사용하여 파라미터에 문서 실행 값이 필요한지 또는 파라미터 값을 제공하는 것이 선택 사항인지 여부를 지정할 수 있습니다. 필수 파라미터와 선택적 파라미터는 이 주제의 예에서 볼 수 있습니다.

유형: 문자열

필수 항목 여부: 아니요

파라미터

문서가 허용하는 파라미터를 정의하는 구조입니다.

자주 사용하는 파라미터의 경우 AWS Systems Manager의 기능인 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 }}"] 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 }}"] } }, "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-z0-9]{8,17}$" default: ''
    JSON
    "InstanceId": { "type": "String", "description": "(Required) The instance ID to target.", "allowedPattern": "^i-[a-z0-9]{8,17}$", "default": "" }
  • displayType: (선택 사항) AWS Management Console에서 textfield 또는 textarea를 표시하는 데 사용됩니다. textfield는 한 줄 텍스트 상자이고, textarea는 여러 줄 텍스트 상자입니다.

  • minItems: (선택 사항) 허용되는 최소 항목 수입니다.

  • maxItems: (선택 사항) 허용되는 최대 항목 수입니다.

  • minChars: (선택 사항) 허용되는 파라미터 문자 최소 개수입니다.

  • maxChars: (선택 사항) 허용되는 파라미터 문자 최대 개수입니다.

필수 항목 여부: 아니요

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용)를 사용하여 첨부 파일을 지정해야 합니다. 로컬 파일과 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의 예입니다.

String

인용 부호로 묶인 0개 이상의 유니코드 문자 시퀀스입니다. 예를 들면 "i-1234567890abcdef0"입니다. 이스케이프하려면 백슬래시를 사용합니다.

YAML
--- InstanceId: type: String description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{ "type":"String", "description":"(Optional) The target EC2 instance ID." }
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 문서 내용 보기