데이터 요소 및 파마미터 - AWS Systems Manager
최상위 데이터 요소SSM 문서 파라미터 type 예제SSM Command 문서 내용 보기

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

데이터 요소 및 파마미터

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

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

최상위 데이터 요소

schemaVersion

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

형식: 버전

필수 여부: 예

설명

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

타입: 문자열

필수 항목 여부: 아니요

파라미터

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

자주 사용하는 매개변수의 경우 해당 매개변수를 의 용량 () 에 Parameter Store 저장하는 것이 좋습니다 AWS Systems Manager. 그런 다음 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 섹션에서 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: (선택 사항) 파라미터에 허용되는 값의 배열입니다. 파라미터에 허용된 값을 정의하면 사용자 입력이 검증됩니다. 사용자가 허용되지 않는 값을 입력하면 실행이 시작되지 않습니다.

    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: (선택 사항) textfield a나 a를 textarea 에 표시하는 데 사용됩니다 AWS Management Console. textfield한 줄로 된 텍스트 상자입니다. textarea여러 줄로 된 텍스트 영역입니다.

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

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

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

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

필수 여부: 아니요

variables

(스키마 버전 0.3만 해당) Automation 런북의 전체 단계에서 참조하거나 업데이트할 수 있는 값입니다. 변수는 파라미터와 비슷하지만 매우 중요한 점에서 다릅니다. 런북의 컨텍스트에서는 파라미터 값이 고정되어 있지만 런북의 컨텍스트에서 변수 값을 변경할 수 있습니다. 변수 값을 업데이트할 때 데이터 유형은 정의된 데이터 유형과 일치해야 합니다. 자동화에서 변수 값을 업데이트하는 방법에 대한 자세한 내용은 aws:updateVariable - 런북 변수 값을 업데이트 섹션을 참조하세요.

유형: 불리언 | 정수 | | 문자열 | MapList | StringList StringMap

필수 여부: 아니요

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

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

유형: 딕셔너리<문자열, > PluginConfiguration

필수 여부: 아니요

mainSteps

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

유형: 사전<문자열, > PluginConfiguration

필수 여부: 예

출력

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

유형: 딕셔너리<문자열, > OutputConfiguration

필수 여부: 아니요

files

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

스크립트 런타임 지원을 위해 자동화 런북은 Python 3.7, Python 3.8, PowerShell Core 6.0 및 7.0용 스크립트를 지원합니다. PowerShell Automation 런북에 스크립트 포함에 대한 자세한 내용은 런북에서 스크립트 사용 및 문서 빌더를 사용하여 런북 생성 섹션을 참조하세요.

첨부 파일이 있는 자동화 런북을 만들 때는 (for AWS CLI) 또는 Attachments (API 및 SDK용) --attachments 옵션을 사용하여 첨부 파일도 지정해야 합니다. 로컬 파일과 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"
        }
    }
}

유형: 딕셔너리<문자열, > FilesConfiguration

필수 여부: 아니요

SSM 문서 파라미터 type 예제

SSM 문서의 파라미터 유형은 정적입니다. 즉, 파라미터 유형을 정의한 후에는 변경할 수 없습니다. SSM 문서 플러그인과 함께 파라미터를 사용하는 경우 파라미터 유형을 플러그인의 입력 내에서 동적으로 변경할 수 없습니다. 예를 들어 이러한 입력은 문자열이나 문자열 목록을 허용하기 때문에 aws:runShellScript 플러그인의 runCommand 입력 내에서 Integer 파라미터를 참조할 수 없습니다. 플러그인 입력에 파라미터를 사용하려면 파라미터 유형이 허용되는 유형과 일치해야 합니다. 예를 들어 aws:updateSsmAgent 플러그인의 allowDowngrade 입력에 대해 Boolean 유형 파라미터를 지정해야 합니다. 파라미터 유형이 플러그인의 입력 유형과 일치하지 않으면 SSM 문서 검증에 실패하고 시스템에서는 문서를 생성하지 않습니다. 이는 다른 플러그인이나 자동화 작업을 위한 입력 내에서 다운스트림 매개변수를 사용할 때도 마찬가지입니다. AWS Systems Manager 예를 들어 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

StringMap 객체 목록.

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. https://console.aws.amazon.com/systems-manager/ 에서 AWS Systems Manager 콘솔을 엽니다.

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

    -또는-

    AWS Systems Manager 홈 페이지가 먼저 열리면 메뉴 아이콘 ( The menu icon ) 을 선택하여 탐색 창을 연 다음 탐색 창에서 [Documents] 를 선택합니다.

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

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

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

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

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