데이터 요소 및 파마미터
이 주제에서는 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
파라미터에 저장된 명령을 실행합니다.참고
문서의
parameters
섹션에서String
및StringList
Parameter Store 파라미터를 참조할 수 있습니다.SecureString
Parameter Store 파라미터를 참조할 수 없습니다.Parameter Store에 대한 자세한 내용은 AWS Systems Manager Parameter Store 섹션을 참조하세요.
형식: 구조
parameters
구조는 다음의 필드 및 값을 수락합니다.-
type
: (필수) 허용되는 값은 다음과 같습니다.String
,StringList
,Integer
Boolean
,MapList
,StringMap
. 각 유형의 예를 보려면 다음 단원의 SSM 문서 파라미터 type 예제를 참조하십시오.참고
Command 유형 문서에서는
String
및StringList
파라미터 유형만 지원합니다. -
description
: (선택 사항) 파라미터에 대한 설명입니다. -
default
: (선택 사항) 파라미터의 기본값 또는 Parameter Store 내 파라미터에 대한 참조입니다. -
allowedValues
: (선택 사항) 파라미터에 허용되는 값의 배열입니다. 파라미터에 허용된 값을 정의하면 사용자 입력이 검증됩니다. 사용자가 허용되지 않는 값을 입력하면 실행이 시작되지 않습니다. -
allowedPattern
: (선택 사항) 사용자 입력이 파라미터에 대해 정의된 패턴과 일치하는지 여부를 확인하는 정규 표현식입니다. 사용자 입력이 허용된 패턴과 일치하지 않으면 실행이 시작되지 않습니다.참고
Systems Manager는
allowedPattern
에 대한 두 가지 검증을 수행합니다. 첫 번째 유효성 검사는 문서를 사용할 때 API 레벨에서 Java regex 라이브러리를 사용하여 수행됩니다. 두 번째 유효성 검사는 문서를 처리하기 전에 GO regexp 라이브러리 를 사용하여 SSM Agent에서 수행됩니다. -
displayType
: (선택 사항) AWS Management Console에서textfield
또는textarea
를 표시하는 데 사용됩니다.textfield
는 한 줄 텍스트 상자이고,textarea
는 여러 줄 텍스트 상자입니다. -
minItems
: (선택 사항) 허용되는 최소 항목 수입니다. -
maxItems
: (선택 사항) 허용되는 최대 항목 수입니다. -
minChars
: (선택 사항) 허용되는 파라미터 문자 최소 개수입니다. -
maxChars
: (선택 사항) 허용되는 파라미터 문자 최대 개수입니다.
필수 항목 여부: 아니요
-
- variables
-
(스키마 버전 0.3만 해당) Automation 런북의 전체 단계에서 참조하거나 업데이트할 수 있는 값입니다. 변수는 파라미터와 비슷하지만 매우 중요한 점에서 다릅니다. 런북의 컨텍스트에서는 파라미터 값이 고정되어 있지만 런북의 컨텍스트에서 변수 값을 변경할 수 있습니다. 변수 값을 업데이트할 때 데이터 유형은 정의된 데이터 유형과 일치해야 합니다. 자동화에서 변수 값을 업데이트하는 방법에 대한 자세한 내용은 aws:updateVariable - 런북 변수 값을 업데이트 섹션을 참조하세요.
형식: Boolean | Integer | MapList | String | StringList | StringMap
필수 항목 여부: 아니요
- 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 참조의 첨부 파일을 참조하세요.형식: 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"입니다. 이스케이프하려면 백슬래시를 사용합니다.
- StringList
-
쉼표로 구분된 문자열 항목의 목록입니다. 예를 들면 ["cd ~”, “pwd”]입니다.
- 불
-
true
또는false
만 허용됩니다. "true" 또는 0은 허용되지 않습니다. - Integer
-
정수입니다. 십진수(예: 3.14159) 또는 인용 부호로 묶인 숫자(예: "3")는 허용되지 않습니다.
- StringMap
-
키-값 매핑입니다. 키와 값은 문자열이어야 합니다. 예를 들면 {"Env”: “Prod”}입니다.
- MapList
-
SfortMar 객체의 목록입니다.
SSM Command 문서 내용 보기
AWS Systems Manager(SSM) 문서에 대한 필수 및 옵션 파라미터를 미리 보기 위해 문서에서 실행하는 작업 외에도 Systems Manager 콘솔에서 문서의 내용을 볼 수 있습니다.
SSM Command 문서 내용을 보려면
AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/
)을 엽니다. 탐색 창에서 Documents를 선택합니다.
-
검색 상자에서 [문서 유형(Document type)]을 선택한 다음 [Command]를 선택합니다.
-
문서의 이름을 선택한 후 [콘텐츠(Content)] 탭을 선택합니다.
-
콘텐츠 필드에서 문서에 사용 가능한 파라미터와 작업 단계를 검토합니다.
예를 들어 다음 이미지는 (1)
version
및 (2)allowDowngrade
가AWS-UpdateSSMAgent
문서에 대한 옵션 파라미터이고 문서에서 실행되는 첫 번째 작업이 (3)aws:updateSsmAgent
임을 보여줍니다.