스키마, 특성 및 예제
AWS Systems Manager 문서는 다음 스키마 버전을 사용합니다.
-
Command유형의 문서는 스키마 버전 1.2, 2.0 및 2.2을 사용해야 합니다. 1.2 문서를 사용하는 경우 스키마 버전 2.2를 사용하는 문서 생성을 권장합니다. -
Policy유형의 문서는 스키마 버전 2.0 이상을 사용해야 합니다. -
Automation유형의 문서는 스키마 버전 0.3을 사용해야 합니다. -
Session유형의 문서는 스키마 버전 1.0을 사용해야 합니다. -
JSON 또는 YAML에서 문서를 만들 수 있습니다.
Session 문서 스키마에 대한 자세한 정보는 Session 문서 스키마 문서를 참조하세요.
Command 및 Policy 문서에 최신 스키마 버전을 사용하여 다음 기능을 활용할 수 있습니다.
스키마 버전 2.2 문서 기능 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 기능 | Details | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
문서 편집 |
이제 문서를 업데이트할 수 있습니다. 버전 1.2에서는 문서를 업데이트하려면 다른 이름으로 저장해야 했습니다. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
자동 버전 관리 |
문서로 업데이트하면 새로운 버전이 만들어집니다. 이것은 스키마가 아닌 문서 버전입니다. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
기본 버전 |
문서 버전이 다수인 경우에는 기본 문서로 사용할 버전을 지정할 수 있습니다. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
시퀀싱 |
문서의 플러그인 또는 단계는 지정된 순서로 실행됩니다. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
교차 플랫폼 지원 |
크로스 플랫폼 지원으로 동일한 SSM 문서 내에서 플러그인마다 다른 운영 체제를 지정할 수 있습니다. 교차 플랫폼 지원 기능은 단계 내에서 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
참고
새로운 Systems Manager 기능과 SSM 문서 기능을 사용하려면 인스턴스의 AWS Systems Manager SSM Agent를 최신 버전으로 업데이트하여 최신 상태를 유지해야 합니다. 자세한 내용은 Run Command를 사용하여 SSM Agent 업데이트 단원을 참조하십시오.
다음 표에는 주요 스키마 버전의 차이점이 나열되어 있습니다.
| 버전 1.2 | 버전 2.2(최신 버전) | Details |
|---|---|---|
|
runtimeConfig |
mainSteps |
버전 2.2에서는 |
|
properties |
inputs |
버전 2.2에서는 |
|
명령 |
runCommand |
버전 2.2에서는 |
|
id |
작업 |
버전 2.2에서는 |
|
해당 사항 없음 |
name |
버전 2.2 에서 |
Precondition 파라미터 사용
스키마 버전 2.2 이상에서는 precondition 파라미터를 사용하여 플러그인마다 대상 운영 체제를 지정하거나 SSM 문서에 정의한 입력 파라미터를 검증할 수 있습니다. precondition 파라미터는 SSM 문서의 입력 파라미터 참조 및 platformType의 Linux, MacOS, Windows 값 사용을 지원합니다. StringEquals 연산자만 지원됩니다.
스키마 버전 2.2 이상을 사용하는 문서에서 precondition 파라미터를 지정하지 않으면 플러그인과 운영 체제의 호환성에 따라 각 플러그인이 실행되거나 생략됩니다. 운영 체제와의 플러그인 호환성은 precondition보다 먼저 평가됩니다. 반대로 스키마 버전 2.0 이하를 사용하는 문서에서는 비호환 플러그인을 실행하려고 하면 오류가 발생합니다.
예를 들어 스키마 버전 2.2 문서에서 precondition이 지정되지 않고 aws:runShellScript 플러그인이 나열되면 Linux 인스턴스에서는 단계가 실행되지만, aws:runShellScript가 Windows Server 인스턴스와 호환되지 않기 때문에 Windows Server 인스턴스에서는 이 단계를 건너뜁니다. 하지만 스키마 버전 2.0 문서에서는 aws:runShellScript 플러그인을 지정하더라도 Windows Server 인스턴스에서 문서를 실행하면 실행이 실패합니다. 이 섹션 후반부의 SSM 문서에 있는 precondition 파라미터의 예를 참조하세요.
스키마 버전 2.2
최상위 수준 요소
다음은 스키마 버전 2.2를 사용하여 SSM 문서의 최상위 요소를 나타낸 예제입니다.
스키마 버전 2.2 예제
다음 예제에서는 aws:runPowerShellScript 플러그인을 사용하여 대상 인스턴스에서 PowerShell 명령을 실행합니다.
스키마 버전 2.2 precondition 파라미터 예제
스키마 버전 2.2는 교차 플랫폼 지원 기능을 제공합니다. 이 말은 단일 SSM 문서 내에서 플러그인마다 다른 운영 체제를 지정할 수 있다는 것을 의미합니다. 교차 플랫폼 지원 기능은 다음 예제와 같이 단계 내에서 precondition 파라미터를 사용합니다. precondition 파라미터를 사용하여 SSM 문서에 정의한 입력 파라미터를 검증할 수도 있습니다. 다음 예 중 두 번째 예에서 이를 확인할 수 있습니다.
스키마 버전 2.2 State Manager 예제
State Manager에서 Systems Manager의 기능인 다음과 같은 SSM 문서를 사용하여 ClamAV 안티바이러스 소프트웨어를 설치할 수 있습니다. State Manager에서는 특정 구성만 사용 가능합니다. 즉, State Manager 연결이 실행될 때마다 시스템이 ClamAV 소프트웨어가 설치되어 있는지 확인합니다. 설치되어 있지 않은 경우 State Manager은 이 문서를 다시 실행합니다.
스키마 버전 2.2 인벤토리 예제
State Manager에서 다음과 같은 SSM 문서를 사용하여 해당 인스턴스에 대한 인벤토리 메타데이터를 수집할 수 있습니다.
스키마 버전 2.2 AWS-ConfigureAWSPackage 예제
다음은 AWS-ConfigureAWSPackage 문서를 나타낸 예제입니다. mainSteps 섹션에는 action 단계의 aws:configurePackage 플러그인이 포함되어 있습니다.
참고
Linux 운영 체제에서는 AmazonCloudWatchAgent 및 AWSSupport-EC2Rescue 패키지만 지원됩니다.
스키마 버전 1.2
다음은 스키마 버전 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" } ] } } }
스키마 버전 1.2 aws:runShellScript 예제
다음 예에서는 AWS-RunShellScript SSM 문서를 보여줍니다. runtimeConfig 섹션에는 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 }}" } ] } } }
스키마 버전 0.3
최상위 수준 요소
다음 예에서는 스키마 버전이 0.3인 JSON 형식 Automation 실행서의 최상위 요소를 보여줍니다.
{ "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} } }
YAML Automation 실행서 예
다음 샘플은 Automation 실행서의 내용을 YAML 형식으로 보여줍니다. 문서 스키마 버전 0.3에 대한 이 작업 예제는 Markdown을 사용하여 문서 설명의 서식을 지정하는 방법을 보여줍니다.
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/amzn-ami-hvm-x86_64-gp2 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}' 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.8 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.8 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
