• AWS Systems Manager CloudWatch 대시보드는 2026년 4월 30일 이후에는 더 이상 사용할 수 없습니다. 고객은 Amazon CloudWatch 콘솔을 계속 사용하여 현재와 마찬가지로 Amazon CloudWatch 대시보드를 보고, 생성하고, 관리할 수 있습니다. 자세한 내용은 [Amazon CloudWatch 대시보드 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)를 참조하세요. # AWS Systems Manager Documents AWS Systems Manager 문서(SSM 문서)는 Systems Manager가 관리형 인스턴스에서 실행하는 작업을 정의합니다. Systems Manager에는 런타임에 파라미터를 지정하여 사용할 수 있는 사전 구성 문서가 100개 이상 포함되어 있습니다. **Amazon 소유(Owned by Amazon)** 탭을 선택하거나 `ListDocuments` API 작업 호출 시 `Owner` 필터에 대해 Amazon을 지정하여 Systems Manager 문서(Systems Manager Documents) 콘솔에서 사전 구성된 문서를 찾을 수 있습니다. 문서는 JavaScript Object Notation(JSON) 또는 YAML을 사용하며 사용자가 지정하는 단계와 파라미터를 포함합니다. 보안 강화를 위해 2025년 7월 14일부터 SSM 문서는 파라미터를 처리할 때 환경 변수 보간을 지원합니다. 스키마 버전 2.2 및 SSM Agent 버전 3.3.2746.0 이상에서 사용할 수 있는 이 기능은 명령 삽입 공격을 방지하는 데 도움이 됩니다. SSM 문서를 시작하려면 [Systems Manager 콘솔](https://console.aws.amazon.com/systems-manager/documents)을 엽니다. 탐색 창에서 **Documents**를 선택합니다. **중요** Systems Manager에서 *Amazon 소유* SSM 문서는 Amazon Web Services 자체에서 생성하고 관리하는 문서입니다. *Amazon 소유* 문서에는 문서 이름에 접두사(예: `AWS-*`)가 포함됩니다. 문서의 소유자는 AWS 내 특정 사용자 계정이 아닌 Amazon으로 간주됩니다. 이 문서는 누구나 사용할 수 있도록 공개되어 있습니다. ## Documents 도구가 조직에 주는 이점은 무엇인가요? AWS Systems Manager의 도구인 Documents는 다음 이점을 제공합니다. + **문서 범주** 필요한 문서를 찾는 데 도움이 되도록 검색 중인 문서 유형에 따라 범주를 선택합니다. 검색 범위를 넓히기 위해 동일한 문서 유형의 여러 범주를 선택할 수 있습니다. 서로 다른 문서 유형의 범주 선택은 지원되지 않습니다. 범주는 Amazon이 소유한 문서에만 지원됩니다. + **문서 버전** 다양한 버전의 문서를 작성하여 저장할 수 있습니다. 그런 다음 각 문서의 기본 버전을 지정할 수 있습니다. 문서의 기본 버전은 새로운 버전으로 업데이트하거나 이전 버전으로 되돌릴 수 있습니다. 문서의 콘텐츠를 변경하면 Systems Manager가 자동으로 문서의 버전을 높입니다. 콘솔, AWS Command Line Interface(AWS CLI) 명령 또는 API 호출에서 문서 버전을 지정하여 문서의 모든 버전을 검색하거나 사용할 수 있습니다. + **필요에 맞게 문서 사용자 지정** 문서에서 각 단계 및 작업을 사용자 정의하고 싶다면 자신만의 고유한 문서를 생성할 수 있습니다. 시스템은 문서를 생성한 AWS 리전의 AWS 계정으로 문서를 저장합니다. SSM 문서 생성 방법에 대한 자세한 내용은 [SSM 문서 콘텐츠 생성](documents-creating-content.md) 섹션을 참조하세요. + **문서에 태그 지정** 문서에 태그를 지정하면 문서에 지정한 태그를 토대로 하나 이상의 문서를 빠르게 식별하는 데 도움이 될 수 있습니다. 예를 들어 특정 환경, 부서, 사용자, 그룹 또는 기간의 문서에 태그를 지정할 수 있습니다. 또한 사용자나 그룹이 액세스할 수 있는 태그를 지정하는 AWS Identity and Access Management(IAM) 정책을 생성하여 문서에 대한 액세스를 제한할 수도 있습니다. + **문서 공유** 문서를 퍼블릭으로 설정하거나 동일한 AWS 리전에서 특정 AWS 계정와 공유할 수 있습니다. 고객 또는 직원에게 공급하는 모든 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스의 구성이 동일하기를 바라는 경우 계정 간 문서 공유가 유용할 수 있습니다. 인스턴스의 애플리케이션 및 패치를 최신 상태를 유지하는 것 외에도 고객 인스턴스의 특정 활동을 제한하고자 할 수도 있습니다. 또는 조직 전체의 직원 계정에서 사용하는 인스턴스가 특정 내부 리소스에 대해 액세스가 허용되도록 하고자 할 수도 있습니다. 자세한 내용은 [SSM 문서 공유](documents-ssm-sharing.md) 섹션을 참조하세요. ## 누가 Documents를 사용해야 하나요? + Systems Manager 도구를 사용하여 규모에 맞게 운영 효율성을 개선하고, 수동 개입과 관련된 오류를 줄이고, 일반적인 문제 해결 시간을 단축하고자 하는 AWS 고객. + 배포 및 구성 태스크를 자동화하려는 인프라 전문가 + 일반적인 문제를 안정적으로 해결하고, 문제 해결 효율성을 높이고, 반복 작업을 줄이려는 관리자 + 일반적으로 수동으로 수행하는 태스크를 자동화하려는 사용자 ## SSM 문서의 유형은 무엇인가요? 다음 표에서는 여러 유형의 SSM 문서와 그 용도에 대해 설명합니다. **** | Type | 용도 | 세부 정보 | | --- | --- | --- | | ApplicationConfiguration ApplicationConfigurationSchema | [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html) | AWS Systems Manager의 도구인 AWS AppConfig를 사용하여 애플리케이션 구성을 생성, 관리 및 신속하게 배포합니다. `ApplicationConfiguration` 문서 유형을 사용하는 문서를 만들어 SSM 문서에 구성 데이터를 저장할 수 있습니다. 자세한 내용은 *AWS AppConfig 사용 설명서*의 [자유형 구성](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#free-form-configurations) 단원을 참조하십시오. SSM 문서에서 구성을 생성하는 경우 해당 JSON 스키마를 지정해야 합니다. 스키마는 `ApplicationConfigurationSchema` 문서 유형을 사용하여, 규칙 세트와 같이 각 애플리케이션 구성 설정에 대해 허용 가능한 속성을 정의합니다. 자세한 내용은 *AWS AppConfig 사용 설명서*의 [검사기 정보](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile-validators.html) 단원을 참조하십시오. | | Automation 실행서 | [자동화](systems-manager-automation.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | Automation 실행서는 Amazon Machine Image(AMI) 생성 또는 업데이트와 같은 일반적인 유지 관리 및 배포 태스크를 실행할 때 사용됩니다. State Manager는 Automation 실행서를 사용하여 구성을 적용합니다. 이 작업은 인스턴스 수명 주기 중 언제든지 하나 이상의 대상에서 실행할 수 있습니다. Maintenance Windows에서는 Automation 실행서를 사용하여 지정된 일정을 기반으로 일반 유지 관리 및 배포 태스크를 수행합니다. Linux 기반 운영 체제에서 지원되는 모든 Automation 실행서는 macOS용 EC2 인스턴스에서도 지원됩니다. | | Change Calendar 문서 | [Change Calendar](systems-manager-change-calendar.md) | AWS Systems Manager의 도구인 Change Calendar는 `ChangeCalendar` 문서 유형을 사용합니다. Change Calendar 문서는 자동화 작업에서 환경 변경을 허용하거나 금지할 수 있는 일정 항목 및 연관된 이벤트를 저장합니다. Change Calendar에서 문서는 [iCalendar 2.0](https://icalendar.org/) 데이터를 일반 텍스트 형식으로 저장합니다. Change Calendar는 macOS용 EC2 인스턴스에서 지원되지 않습니다. | | AWS CloudFormation 템플릿 | [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | AWS CloudFormation 템플릿은 CloudFormation 스택에서 프로비저닝할 리소스에 대해 설명합니다. CloudFormation 템플릿을 Systems Manager 문서로 저장하여 Systems Manager 문서 기능을 활용할 수 있습니다. 여기에는 여러 버전의 템플릿 생성 및 비교와 같은 AWS 리전에 있는 다른 계정과 템플릿 공유가 포함됩니다. Systems Manager의 도구인 Application Manager를 사용하여 CloudFormation 템플릿 및 스택을 생성하고 편집할 수 있습니다. 자세한 내용은 [Application Manager에서 CloudFormation 템플릿 및 스택 작업](application-manager-working-stacks.md) 섹션을 참조하세요. | | 명령 문서 | [Run Command](run-command.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | AWS Systems Manager의 도구인 Run Command는 명령 문서를 사용하여 명령을 실행합니다. AWS Systems Manager의 도구인 State Manager는 명령 문서를 사용하여 구성을 적용합니다. 이 작업은 인스턴스 수명 주기 중 언제든지 하나 이상의 대상에서 실행할 수 있습니다. AWS Systems Manager의 도구인 Maintenance Windows에서는 Command 문서를 사용하여 지정된 일정을 기반으로 구성을 적용합니다. 대부분의 Command 문서는 모든 Linux 및 Systems Manager에서 지원하는 Windows Server 운영 체제에서 지원됩니다. 다음 Command 문서는 macOS용 EC2 인스턴스에서 지원됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/documents.html) | | AWS Config 규정 준수 팩 템플릿 | [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) | AWS Config 규정 준수 팩 템플릿은 AWS Config 관리형 또는 사용자 지정 규칙 및 수정 작업 목록을 포함하는 규정 준수 팩을 생성하는 데 사용되는 YAML 형식의 문서입니다. 자세한 내용을 알아보려면 [규정 준수 팩](https://docs.aws.amazon.com/config/latest/developerguide/conformance-packs.html)을 참조하세요. | | 패키지 문서 | [Distributor](distributor.md) | AWS Systems Manager의 도구인 Distributor에서 패키지는 SSM 문서로 표현됩니다. 패키지 문서에는 관리형 인스턴스에 설치할 소프트웨어 또는 자산이 포함된 연결된 ZIP 아카이브 파일이 포함됩니다. Distributor에서 패키지를 생성하면 패키지 문서가 생성됩니다. Distributor는 Oracle Linux와 macOS 관리형 인스턴스에서 지원되지 않습니다. | | 정책 문서 | [State Manager](systems-manager-state.md) | AWS Systems Manager의 도구인 Inventory는 State Manager 연결이 있는 `AWS-GatherSoftwareInventory` Policy 문서를 사용하여 관리형 인스턴스에서 인벤토리 데이터를 수집합니다. 자체 SSM 문서 생성 시 Automation 실행서와 Command 문서는 관리형 인스턴스에서 정책을 적용하는 데 선호되는 방법입니다. Systems Manager Inventory 및 `AWS-GatherSoftwareInventory` Policy 문서는 Systems Manager에서 지원하는 모든 운영 체제에서 지원됩니다. | | 인시던트 후 분석 템플릿 | [Incident Manager 인시던트 후 분석](https://docs.aws.amazon.com/incident-manager/latest/userguide/analysis.html) | Incident Manager는 인시던트 후 분석 템플릿을 사용하여 AWS 운영 관리 모범 사례를 기반으로 분석을 생성합니다. 템플릿을 사용하여 팀에서 인시던트 대응에 대한 개선 사항을 식별하는 데 사용할 수 있는 분석을 생성합니다. | | 세션 문서 | [Session Manager](session-manager.md) | AWS Systems Manager의 도구인 Session Manager에서는 Session 문서를 사용하여 시작할 세션의 유형(예: 포트 전달 세션, 대화형 명령을 실행할 세션, SSH 터널을 생성할 세션)을 결정합니다. Session 문서는 모든 Linux 및 Systems Manager에서 지원하는 Windows Server 운영 체제에서 지원됩니다. 다음 Command 문서는 macOS용 EC2 인스턴스에서 지원됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/documents.html) | **SSM 문서 할당량** SSM 문서 할당량에 대한 내용은 **Amazon Web Services 일반 참조의 [Systems Manager 서비스 할당량](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)을 참조하세요. **Topics** + [Documents 도구가 조직에 주는 이점은 무엇인가요?](#ssm-docs-benefits) + [누가 Documents를 사용해야 하나요?](#documents-who) + [SSM 문서의 유형은 무엇인가요?](#what-are-document-types) + [문서 구성 요소](documents-components.md) + [SSM 문서 콘텐츠 생성](documents-creating-content.md) + [문서 작업](documents-using.md) + [파라미터 처리 문제 해결](parameter-troubleshooting.md) # 문서 구성 요소 이 섹션에는 SSM 문서를 구성하는 구성 요소에 대한 정보가 포함되어 있습니다. **Topics** + [스키마, 특성 및 예제](documents-schemas-features.md) + [데이터 요소 및 파마미터](documents-syntax-data-elements-parameters.md) + [Command 문서 플러그인 참조](documents-command-ssm-plugin-reference.md) # 스키마, 특성 및 예제 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 문서 스키마](session-manager-schema.md) 문서를 참조하세요. `Command` 및 `Policy` 문서에 최신 스키마 버전을 사용하여 다음 기능을 활용할 수 있습니다. **스키마 버전 2.2 문서 기능** | 기능 | 세부 정보 | | --- | --- | | 문서 편집 | 이제 문서를 업데이트할 수 있습니다. 버전 1.2에서는 문서를 업데이트하려면 다른 이름으로 저장해야 했습니다. | | 자동 버전 관리 | 문서로 업데이트하면 새로운 버전이 만들어집니다. 이것은 스키마가 아닌 문서 버전입니다. | | 기본 버전 | 문서 버전이 다수인 경우에는 기본 문서로 사용할 버전을 지정할 수 있습니다. | | 시퀀싱 | 문서의 플러그인 또는 *단계*는 지정된 순서로 실행됩니다. | | 교차 플랫폼 지원 | 크로스 플랫폼 지원으로 동일한 SSM 문서 내에서 플러그인마다 다른 운영 체제를 지정할 수 있습니다. 교차 플랫폼 지원 기능은 단계 내에서 `precondition` 파라미터를 사용합니다. | | 파라미터 보간 | 보간은 변수 값을 문자열에 삽입하거나 대체하는 것을 의미합니다. 문자열을 사용하기 전에 실제 값으로 공백을 채우는 것으로 생각하세요. SSM 문서에서 파라미터 보건을 사용하면 명령 실행 전에 문자열 파라미터를 환경 변수에 보간하여 명령 주입에 대한 보안을 강화할 수 있습니다. `ENV_VAR`로 설정하면 에이전트는 파라미터 값이 포함된 `SSM_parameter-name`이라는 이름으로 환경 변수를 생성합니다. | **참고** 새로운 Systems Manager 기능과 SSM 문서 기능을 사용하려면 인스턴스의 AWS Systems Manager SSM Agent를 최신 버전으로 업데이트하여 최신 상태를 유지해야 합니다. 자세한 내용은 [Run Command를 사용하여 SSM Agent 업데이트](run-command-tutorial-update-software.md#rc-console-agentexample) 섹션을 참조하세요. 다음 표에는 주요 스키마 버전의 차이점이 나열되어 있습니다. **** | 버전 1.2 | 버전 2.2(최신 버전) | 세부 정보 | | --- | --- | --- | | runtimeConfig | mainSteps | 버전 2.2에서는 `mainSteps` 섹션이 `runtimeConfig` 섹션으로 대체되었습니다. `mainSteps` 섹션을 사용하면 Systems Manager가 단계를 순서대로 실행할 수 있습니다. | | properties | 입력 | 버전 2.2에서는 `properties` 섹션이 `inputs` 섹션으로 대체되었습니다. `inputs` 섹션은 각 단계의 파라미터를 허용합니다. | |   명령 | runCommand | 버전 2.2에서는 `inputs` 섹션이 `commands` 파라미터 대신 `runCommand` 파라미터를 사용합니다. | | id | 작업 | 버전 2.2에서는 `ID`가 `Action`으로 대체되었습니다. 여기에서는 이름만 변경되었을 뿐입니다. | | 해당 사항 없음 | 이름 | 버전 2.2 에서 `name`은 단계를 나타내는 사용자 정의 이름입니다. | **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 문서의 최상위 요소를 나타낸 예제입니다. ------ #### [ YAML ] ``` --- schemaVersion: "2.2" description: A description of the document. parameters: parameter 1: property 1: "value" property 2: "value" parameter 2: property 1: "value" property 2: "value" mainSteps: - action: Plugin name name: A name for the step. inputs: input 1: "value" input 2: "value" input 3: "{{ parameter 1 }}" ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "A description of the document.", "parameters": { "parameter 1": { "property 1": "value", "property 2": "value" }, "parameter 2":{ "property 1": "value", "property 2": "value" } }, "mainSteps": [ { "action": "Plugin name", "name": "A name for the step.", "inputs": { "input 1": "value", "input 2": "value", "input 3": "{{ parameter 1 }}" } } ] } ``` ------ **스키마 버전 2.2 예제** 다음 예제에서는 `aws:runPowerShellScript` 플러그인을 사용하여 대상 인스턴스에서 PowerShell 명령을 실행합니다. ------ #### [ YAML ] ``` --- schemaVersion: "2.2" description: "Example document" parameters: Message: type: "String" description: "Example parameter" default: "Hello World" allowedValues: - "Hello World" mainSteps: - action: "aws:runPowerShellScript" name: "example" inputs: timeoutSeconds: '60' runCommand: - "Write-Output {{Message}}" ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "Example document", "parameters": { "Message": { "type": "String", "description": "Example parameter", "default": "Hello World", "allowedValues": ["Hello World"] } }, "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "example", "inputs": { "timeoutSeconds": "60", "runCommand": [ "Write-Output {{Message}}" ] } } ] } ``` ------ **스키마 버전 2.2 precondition 파라미터 예제** 스키마 버전 2.2는 교차 플랫폼 지원 기능을 제공합니다. 이 말은 단일 SSM 문서 내에서 플러그인마다 다른 운영 체제를 지정할 수 있다는 것을 의미합니다. 교차 플랫폼 지원 기능은 다음 예제와 같이 단계 내에서 `precondition` 파라미터를 사용합니다. `precondition` 파라미터를 사용하여 SSM 문서에 정의한 입력 파라미터를 검증할 수도 있습니다. 다음 예 중 두 번째 예에서 이를 확인할 수 있습니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: cross-platform sample mainSteps: - action: aws:runPowerShellScript name: PatchWindows precondition: StringEquals: - platformType - Windows inputs: runCommand: - cmds - action: aws:runShellScript name: PatchLinux precondition: StringEquals: - platformType - Linux inputs: runCommand: - cmds ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "cross-platform sample", "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "PatchWindows", "precondition": { "StringEquals": [ "platformType", "Windows" ] }, "inputs": { "runCommand": [ "cmds" ] } }, { "action": "aws:runShellScript", "name": "PatchLinux", "precondition": { "StringEquals": [ "platformType", "Linux" ] }, "inputs": { "runCommand": [ "cmds" ] } } ] } ``` ------ ------ #### [ YAML ] ``` --- schemaVersion: '2.2' parameters: action: type: String allowedValues: - Install - Uninstall confirmed: type: String allowedValues: - True - False mainSteps: - action: aws:runShellScript name: InstallAwsCLI precondition: StringEquals: - "{{ action }}" - "Install" inputs: runCommand: - sudo apt install aws-cli - action: aws:runShellScript name: UninstallAwsCLI precondition: StringEquals: - "{{ action }} {{ confirmed }}" - "Uninstall True" inputs: runCommand: - sudo apt remove aws-cli ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "parameters": { "action": { "type": "String", "allowedValues": [ "Install", "Uninstall" ] }, "confirmed": { "type": "String", "allowedValues": [ true, false ] } }, "mainSteps": [ { "action": "aws:runShellScript", "name": "InstallAwsCLI", "precondition": { "StringEquals": [ "{{ action }}", "Install" ] }, "inputs": { "runCommand": [ "sudo apt install aws-cli" ] } }, { "action": "aws:runShellScript", "name": "UninstallAwsCLI", "precondition": { "StringEquals": [ "{{ action }} {{ confirmed }}", "Uninstall True" ] }, "inputs": { "runCommand": [ "sudo apt remove aws-cli" ] } } ] } ``` ------ **3.3.2746.0 이전 SSM Agent 버전을 사용한 스키마 버전 2.2 보간 예제** 3.3.2746.0 이전 SSM Agent 버전에서는 에이전트가 `interpolationType` 파라미터를 무시하고 대신 원시 문자열 대체를 수행합니다. `SSM_parameter-name`을(를) 명시적으로 참조하는 경우 이를 명시적으로 설정해야 합니다. 다음 Linux 예제에서는 `SSM_Message` 환경 변수가 명시적으로 참조됩니다. ``` { "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", "inputs": { "runCommand": [ "if [ -z "${SSM_Message+x}" ]; then", " export SSM_Message=\"{{Message}}\"", "fi", "", "echo $SSM_Message" ] } } } ``` **참고** SSM 문서에서 이중 중괄호(`{{ }}`)를 사용하지 않는 경우 기술적으로 `allowedPattern`이 필요하지 않습니다. **스키마 버전 2.2 State Manager 예제** Systems Manager의 도구인 State Manager에서 다음 SSM 문서를 사용하여 ClamAV 안티바이러스 소프트웨어를 설치할 수 있습니다. State Manager에서는 특정 구성만 사용 가능합니다. 즉, State Manager 연결이 실행될 때마다 시스템이 ClamAV 소프트웨어가 설치되어 있는지 확인합니다. 설치되어 있지 않은 경우 State Manager은 이 문서를 다시 실행합니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: State Manager Bootstrap Example parameters: {} mainSteps: - action: aws:runShellScript name: configureServer inputs: runCommand: - sudo yum install -y httpd24 - sudo yum --enablerepo=epel install -y clamav ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "State Manager Bootstrap Example", "parameters": {}, "mainSteps": [ { "action": "aws:runShellScript", "name": "configureServer", "inputs": { "runCommand": [ "sudo yum install -y httpd24", "sudo yum --enablerepo=epel install -y clamav" ] } } ] } ``` ------ **스키마 버전 2.2 인벤토리 예제** State Manager에서 다음과 같은 SSM 문서를 사용하여 해당 인스턴스에 대한 인벤토리 메타데이터를 수집할 수 있습니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: Software Inventory Policy Document. parameters: applications: type: String default: Enabled description: "(Optional) Collect data for installed applications." allowedValues: - Enabled - Disabled awsComponents: type: String default: Enabled description: "(Optional) Collect data for AWS Components like amazon-ssm-agent." allowedValues: - Enabled - Disabled networkConfig: type: String default: Enabled description: "(Optional) Collect data for Network configurations." allowedValues: - Enabled - Disabled windowsUpdates: type: String default: Enabled description: "(Optional) Collect data for all Windows Updates." allowedValues: - Enabled - Disabled instanceDetailedInformation: type: String default: Enabled description: "(Optional) Collect additional information about the instance, including the CPU model, speed, and the number of cores, to name a few." allowedValues: - Enabled - Disabled customInventory: type: String default: Enabled description: "(Optional) Collect data for custom inventory." allowedValues: - Enabled - Disabled mainSteps: - action: aws:softwareInventory name: collectSoftwareInventoryItems inputs: applications: "{{ applications }}" awsComponents: "{{ awsComponents }}" networkConfig: "{{ networkConfig }}" windowsUpdates: "{{ windowsUpdates }}" instanceDetailedInformation: "{{ instanceDetailedInformation }}" customInventory: "{{ customInventory }}" ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "Software Inventory Policy Document.", "parameters": { "applications": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for installed applications.", "allowedValues": [ "Enabled", "Disabled" ] }, "awsComponents": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.", "allowedValues": [ "Enabled", "Disabled" ] }, "networkConfig": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for Network configurations.", "allowedValues": [ "Enabled", "Disabled" ] }, "windowsUpdates": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for all Windows Updates.", "allowedValues": [ "Enabled", "Disabled" ] }, "instanceDetailedInformation": { "type": "String", "default": "Enabled", "description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.", "allowedValues": [ "Enabled", "Disabled" ] }, "customInventory": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for custom inventory.", "allowedValues": [ "Enabled", "Disabled" ] } }, "mainSteps": [ { "action": "aws:softwareInventory", "name": "collectSoftwareInventoryItems", "inputs": { "applications": "{{ applications }}", "awsComponents": "{{ awsComponents }}", "networkConfig": "{{ networkConfig }}", "windowsUpdates": "{{ windowsUpdates }}", "instanceDetailedInformation": "{{ instanceDetailedInformation }}", "customInventory": "{{ customInventory }}" } } ] } ``` ------ **스키마 버전 2.2 `AWS-ConfigureAWSPackage` 예제** 다음은 `AWS-ConfigureAWSPackage` 문서를 나타낸 예제입니다. `mainSteps` 섹션에는 `action` 단계의 `aws:configurePackage` 플러그인이 포함되어 있습니다. **참고** Linux 운영 체제에서는 `AmazonCloudWatchAgent` 및 `AWSSupport-EC2Rescue` 패키지만 지원됩니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: 'Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.' parameters: action: description: "(Required) Specify whether or not to install or uninstall the package." type: String allowedValues: - Install - Uninstall name: description: "(Required) The package to install/uninstall." type: String allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$" version: type: String description: "(Optional) A specific version of the package to install or uninstall." mainSteps: - action: aws:configurePackage name: configurePackage inputs: name: "{{ name }}" action: "{{ action }}" version: "{{ version }}" ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.", "parameters": { "action": { "description":"(Required) Specify whether or not to install or uninstall the package.", "type":"String", "allowedValues":[ "Install", "Uninstall" ] }, "name": { "description": "(Required) The package to install/uninstall.", "type": "String", "allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$" }, "version": { "type": "String", "description": "(Optional) A specific version of the package to install or uninstall." } }, "mainSteps":[ { "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "version": "{{ version }}" } } ] } ``` ------ ## 스키마 버전 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/al2023-ami-kernel-6.1-x86_64 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}' 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.11 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.11 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 ``` ## 보안 파라미터 처리 예제 다음 예제에서는 환경 변수 `interpolationType`을 사용한 보안 파라미터 처리를 보여줍니다. ### 기본 보안 명령 실행 이 예제는 명령 파라미터를 안전하게 처리하는 방법을 보여줍니다. **참고** 이중 중괄호(`{{ }}`)를 사용하지 않는 SSM 문서에서는 기술적으로 `allowedPattern`이 필요하지 않습니다. ------ #### [ YAML ] ``` --- 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}} ``` ------ #### [ JSON ] ``` { "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}}" ] } }] } ``` ------ ### 해석된 언어에서 파라미터 사용 이 예제는 Python의 보안 파라미터 처리를 보여줍니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: 'Secure Python script execution' parameters: inputData: type: String description: 'Input data for processing' interpolationType: 'ENV_VAR' mainSteps: - action: aws:runPowerShellScript name: runPython inputs: runCommand: - | python3 -c ' import os import json # Safely access parameter through environment variable input_data = os.environ.get("SSM_inputData", "") # Process the data try: processed_data = json.loads(input_data) print(f"Successfully processed: {processed_data}") except json.JSONDecodeError: print("Invalid JSON input") ' ``` ------ ### 하위 버전 호환성 예제 이 예제는 하위 버전 호환성을 유지하면서 파라미터를 안전하게 처리하는 방법을 보여줍니다. ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: 'Backwards compatible secure parameter handling' parameters: userInput: type: String description: 'User input to process' interpolationType: 'ENV_VAR' allowedPattern: '^[^"]*$' mainSteps: - action: aws:runShellScript name: processInput inputs: runCommand: - | # Handle both modern and legacy agent versions if [ -z "${SSM_userInput+x}" ]; then # Legacy agent - fall back to direct parameter reference export SSM_userInput="{{userInput}}" fi # Process the input securely echo "Processing input: $SSM_userInput" ``` ------ **참고** 이중 중괄호(`{{ }}`)를 사용하지 않는 SSM 문서에서는 기술적으로 `allowedPattern`이 필요하지 않습니다. ## 파라미터 보안 모범 사례 SSM 문서에서 파라미터를 처리할 때 다음 모범 사례를 따르세요. + **환경 변수 보간 사용** - 명령 실행에 사용할 문자열 파라미터에 항상 `interpolationType: "ENV_VAR"`을 사용합니다. + **입력 검증 구현** - `allowedPattern`을 사용하여 파라미터 값을 안전한 패턴으로 제한합니다. + **레거시 시스템 처리** - 환경 변수 보간을 지원하지 않는 이전 SSM Agent 버전에 대한 대체 로직을 포함합니다. + **특수 문자 이스케이프** - 명령에서 파라미터 값을 사용하는 경우 특수 문자를 적절히 이스케이프하여 쉘의 해석을 방지합니다. + **파라미터 범위 제한** - 사용 사례에서 가능한 가장 제한적인 파라미터 패턴을 사용합니다. # 데이터 요소 및 파마미터 이 주제에서는 SSM 문서에 사용되는 데이터 요소를 설명합니다. 문서를 생성하는 데 사용되는 스키마 버전은 문서에서 허용하는 구문과 데이터 요소를 정의합니다. Command 문서에는 스키마 버전 2.2 이상을 사용하는 것이 좋습니다. Automation 런북은 스키마 버전 0.3을 사용합니다. 또한 Automation 런북에서는 Markdown을 사용할 수 있습니다. 마크업 언어인 Markdown을 사용하면 문서와 문서 내의 개별 단계에 wiki 스타일의 설명을 추가할 수 있습니다. 마크다운 사용에 대한 자세한 내용은 AWS Management Console 시작 안내서의 [콘솔에서 마크다운 사용](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)을 참조하세요. 다음 섹션에서는 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`이 필요하지 않습니다. 자주 사용하는 파라미터의 경우 AWS Systems Manager의 도구인 Parameter Store에 해당 파라미터를 저장하는 것이 좋습니다. 그런 다음 Parameter Store 파라미터를 기본값으로 참조하는 파라미터를 문서에서 정의할 수 있습니다. Parameter Store 파라미터를 참조하려면 다음 구문을 사용합니다. ``` {{ssm:parameter-name}} ``` 다른 문서 파라미터와 동일한 방식으로 Parameter Store 파라미터를 참조하는 파라미터를 사용할 수 있습니다. 다음 예제에서 `commands` 파라미터의 기본값은 Parameter Store 파라미터 `myShellCommands`입니다. `commands` 파라미터를 `runCommand` 문자열로 지정하면 문서에서 `myShellCommands` 파라미터에 저장된 명령을 실행합니다. ``` --- 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 }}" ``` ``` { "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` 섹션에서 `String` 및 `StringList` Parameter Store 파라미터를 참조할 수 있습니다. `SecureString` Parameter Store 파라미터를 참조할 수 없습니다. Parameter Store에 대한 자세한 내용은 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md) 섹션을 참조하세요. 형식: 구조 `parameters` 구조는 다음의 필드 및 값을 수락합니다. + `type`: (필수) 허용되는 값은 다음과 같습니다. `String`, `StringList`, `Integer` `Boolean`, `MapList`, `StringMap`. 각 유형의 예를 보려면 다음 단원의 [SSM 문서 파라미터 `type` 예제](#top-level-properties-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 라이브러리](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)를 사용하여 수행됩니다. 두 번째 유효성 검사는 문서를 처리하기 전에 [GO regexp 라이브러리](https://pkg.go.dev/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` - 런북 변수 값을 업데이트](automation-action-update-variable.md) 섹션을 참조하세요. 형식: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap 필수 여부: 아니요 ``` variables: payload: type: StringMap default: "{}" ``` ``` { "variables": [ "payload": { "type": "StringMap", "default": "{}" } ] } ``` **runtimeConfig** (스키마 버전 1.2만 해당) 하나 이상의 Systems Manager 플러그인에 의해 적용되는 인스턴스 구성입니다. 플러그인은 순서대로 실행되지 않습니다. 형식: Dictionary 필수 여부: 아니요 **mainSteps** (스키마 버전 0.3, 2.0 및 2.2만 해당) 여러 단계(플러그인)를 포함할 수 있는 객체입니다. 플러그인은 단계 내에서 정의됩니다. 단계는 이 문서에 나열된 순서대로 실행됩니다. 형식: Dictionary 필수 여부: 예 **출력** (스키마 버전 0.3에만 해당) 이 문서를 실행하여 생성되었고 다른 프로세스에서 사용할 수 있는 데이터입니다. 예를 들어 문서에서 새 AMI를 생성하는 경우 출력 값으로 "CreateImage.ImageId"를 지정한 다음, 이 출력을 사용하여 후속 자동화 실행에서 새 인스턴스를 생성할 수 있습니다. 출력에 대한 자세한 내용은 [작업 출력을 입력으로 사용](automation-action-outputs-inputs.md) 섹션을 참조하세요. 형식: Dictionary 필수 여부: 아니요 **files** (스키마 버전 0.3에만 해당) 문서에 첨부되어 자동화 실행 중에 실행되는 스크립트 파일(및 해당 체크섬)입니다. `aws:executeScript` 작업을 포함하고 하나 이상의 단계에서 첨부 파일이 지정된 문서에만 적용됩니다. Automation 런북에서 지원하는 런타임에 대한 자세한 내용은 [`aws:executeScript` - 스크립트 실행](automation-action-executeScript.md) 섹션을 참조하세요. Automation 런북에 스크립트 포함에 대한 자세한 내용은 [런북에서 스크립트 사용](automation-document-script-considerations.md) 및 [Automation 런북의 시각적 디자인 경험](automation-visual-designer.md) 섹션을 참조하세요. 첨부 파일이 포함된 Automation 실행서를 생성할 때 옵션 `--attachments`(AWS CLI용) 또는 `Attachments`(API 및 SDK용)를 사용하여 첨부 파일을 지정해야 합니다. SSM 문서와 Amazon Simple Storage Service(Amazon S3) 버킷에 저장된 파일에 대해 파일 위치를 지정할 수 있습니다. 자세한 내용은 AWS Systems Manager API 참조의 [첨부 파일](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)을 참조하세요. ``` --- files: launch.py: checksums: sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE ``` ``` "files": { "launch.py": { "checksums": { "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE" } } } ``` 형식: Dictionary 필수 여부: 아니요 ## 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`이 포함될 수 있습니다. ``` --- InstanceId: type: String description: "(Optional) The target EC2 instance ID." interpolationType: ENV_VAR ``` ``` "InstanceId":{ "type":"String", "description":"(Optional) The target EC2 instance ID.", "interpolationType": "ENV_VAR" } ``` StringList 쉼표로 구분된 문자열 항목의 목록입니다. 예를 들면 ["cd \$1”, “pwd”]입니다. ``` --- commands: type: StringList description: "(Required) Specify a shell script or a command to run." default: "" minItems: 1 displayType: textarea ``` ``` "commands":{ "type":"StringList", "description":"(Required) Specify a shell script or a command to run.", "minItems":1, "displayType":"textarea" } ``` 부울 `true` 또는 `false`만 허용됩니다. "true" 또는 0은 허용되지 않습니다. ``` --- canRun: type: Boolean description: '' default: true ``` ``` "canRun": { "type": "Boolean", "description": "", "default": true } ``` Integer 정수입니다. 십진수(예: 3.14159) 또는 인용 부호로 묶인 숫자(예: "3")는 허용되지 않습니다. ``` --- timeout: type: Integer description: The type of action to perform. default: 100 ``` ``` "timeout": { "type": "Integer", "description": "The type of action to perform.", "default": 100 } ``` StringMap 키-값 매핑입니다. 키와 값은 문자열이어야 합니다. 예를 들면 \$1"Env”: “Prod”\$1입니다. ``` --- notificationConfig: type: StringMap description: The configuration for events to be notified about default: NotificationType: 'Command' NotificationEvents: - 'Failed' NotificationArn: "$dependency.topicArn" maxChars: 150 ``` ``` "notificationConfig" : { "type" : "StringMap", "description" : "The configuration for events to be notified about", "default" : { "NotificationType" : "Command", "NotificationEvents" : ["Failed"], "NotificationArn" : "$dependency.topicArn" }, "maxChars" : 150 } ``` MapList SfortMar 객체의 목록입니다. ``` 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 ``` ``` "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/](https://console.aws.amazon.com/systems-manager/))을 엽니다. 1. 탐색 창에서 **Documents**를 선택합니다. 1. 검색 상자에서 [**문서 유형(Document type)**]을 선택한 다음 [**Command**]를 선택합니다. 1. 문서의 이름을 선택한 후 [**콘텐츠(Content)**] 탭을 선택합니다. 1. 콘텐츠 필드에서 문서에 사용 가능한 파라미터와 작업 단계를 검토합니다. 예를 들어 다음 이미지는 (1) `version` 및 (2) `allowDowngrade`가 `AWS-UpdateSSMAgent` 문서에 대한 옵션 파라미터이고 문서에서 실행되는 첫 번째 작업이 (3) `aws:updateSsmAgent`임을 보여줍니다. ![\[Systems Manager 콘솔에서 SSM 문서 내용 보기\]](http://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/images/view-document-content.png) # Command 문서 플러그인 참조 이 참조는 AWS Systems Manager(SSM) Command 유형 문서에서 지정할 수 있는 플러그인을 설명합니다. 이러한 플러그인은 Automation 작업을 사용하는 SSM Automation 실행서에서는 사용할 수 없습니다. AWS Systems Manager 자동화 작업에 대한 자세한 내용은 [Systems Manager Automation 작업 참조](automation-actions.md) 섹션을 참조하세요. Systems Manager는 SSM 문서의 콘텐츠를 읽어 관리형 인스턴스에서 수행할 작업을 결정합니다. 각 문서에는 코드 실행 섹션이 포함됩니다. 문서의 스키마 버전에 따라 이 코드 실행 섹션이 하나 이상의 플러그인 또는 단계를 포함할 수 있습니다. 이 도움말 주제의 목적을 위해, 플러그인 및 단계를 *플러그인*으로 부릅니다. 이 섹션에는 각 Systems Manager 플러그인에 대한 정보가 포함되어 있습니다. 문서 생성 및 스키마 버전 간 차이를 비롯해 문서에 대한 자세한 내용은 [AWS Systems Manager Documents](documents.md) 섹션을 참조하세요. `aws:runShellScript` 및 `aws:runPowerShellScript`와 같은 문자열 파라미터를 허용하는 플러그인의 경우 `interpolationType` 파라미터를 사용하여 파라미터 입력을 잠재적으로 실행 가능한 명령이 아닌 문자열 리터럴로 처리하여 보안을 강화할 수 있습니다. 예제: ``` { "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" } }, //truncated } ``` **참고** 여기서 설명하는 일부 플러그인은 Windows Server 인스턴스 또는 Linux 인스턴스 중 하나에서만 실행할 수 있습니다. 플러그인마다 플랫폼 종속성이 표시되어 있습니다. 다음 문서 플러그인은 macOS용 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스에서 지원됩니다. `aws:refreshAssociation` `aws:runShellScript` `aws:runPowerShellScript` `aws:softwareInventory` `aws:updateSsmAgent` **Topics** + [공유 입력](#shared-inputs) + [`aws:applications`](#aws-applications) + [`aws:cloudWatch`](#aws-cloudWatch) + [`aws:configureDocker`](#aws-configuredocker) + [`aws:configurePackage`](#aws-configurepackage) + [`aws:domainJoin`](#aws-domainJoin) + [`aws:downloadContent`](#aws-downloadContent) + [`aws:psModule`](#aws-psModule) + [`aws:refreshAssociation`](#aws-refreshassociation) + [`aws:runDockerAction`](#aws-rundockeraction) + [`aws:runDocument`](#aws-rundocument) + [`aws:runPowerShellScript`](#aws-runPowerShellScript) + [`aws:runShellScript`](#aws-runShellScript) + [`aws:softwareInventory`](#aws-softwareinventory) + [`aws:updateAgent`](#aws-updateagent) + [`aws:updateSsmAgent`](#aws-updatessmagent) ## 공유 입력 (SSM Agent 버전 3.0.502 이상 한정) 모든 플러그 인은 다음 입력을 사용할 수 있습니다. **finallyStep** 문서를 실행할 마지막 단계입니다. 이 입력이 단계에 대해 정의된 경우 `onFailure` 또는 `onSuccess` 입력에 지정된 `exit` 값보다 우선합니다. 이 입력이 있는 단계가 예상대로 실행되려면 해당 단계가 문서의 `mainSteps`에 정의된 마지막 단계여야 합니다. 유형: Boolean 유효한 값: `true` \$1 `false` 필수 여부: 아니요 **onFailure** `exit` 값이 있는 플러그인에 대해 이 입력을 지정하고 단계가 실패하면 단계 상태는 실패를 반영하고 문서는 `finallyStep`이 정의되지 않는 한 나머지 단계를 실행하지 않습니다. `successAndExit` 값이 있는 플러그인에 대해 이 입력을 지정하고 단계가 실패하면 단계 상태는 성공으로 표시되고 문서는 `finallyStep`이 정의되지 않는 한 나머지 단계를 실행하지 않습니다. 유형: 문자열 유효한 값: `exit` \$1 `successAndExit` 필수 여부: 아니요 **onSuccess** 플러그인에 대해 이 입력을 지정하고 단계가 성공적으로 실행되면 `finallyStep`이 정의되지 않는 한 문서는 나머지 단계를 실행하지 않습니다. 타입: 문자열 유효한 값: `exit` 필수 여부: 아니요 ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: Shared inputs example parameters: customDocumentParameter: type: String description: Example parameter for a custom Command-type document. mainSteps: - action: aws:runDocument name: runCustomConfiguration inputs: documentType: SSMDocument documentPath: "yourCustomDocument" documentParameters: '"documentParameter":{{customDocumentParameter}}' onSuccess: exit - action: aws:runDocument name: ifConfigurationFailure inputs: documentType: SSMDocument documentPath: "yourCustomRepairDocument" onFailure: exit - action: aws:runDocument name: finalConfiguration inputs: documentType: SSMDocument documentPath: "yourCustomFinalDocument" finallyStep: true ``` ------ #### [ JSON ] ``` { "schemaVersion": "2.2", "description": "Shared inputs example", "parameters": { "customDocumentParameter": { "type": "String", "description": "Example parameter for a custom Command-type document." } }, "mainSteps":[ { "action": "aws:runDocument", "name": "runCustomConfiguration", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomDocument", "documentParameters": "\"documentParameter\":{{customDocumentParameter}}", "onSuccess": "exit" } }, { "action": "aws:runDocument", "name": "ifConfigurationFailure", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomRepairDocument", "onFailure": "exit" } }, { "action": "aws:runDocument", "name":"finalConfiguration", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomFinalDocument", "finallyStep": true } } ] } ``` ------ ## `aws:applications` EC2 인스턴스에서 애플리케이션을 설치, 복구 또는 제거합니다. 이 플러그인은 Windows Server 운영 체제에서만 실행됩니다. ### 구문 #### 스키마 2.2 ------ #### [ YAML ] ``` --- schemaVersion: '2.2' description: aws:applications plugin parameters: source: description: "(Required) Source of msi." type: String mainSteps: - action: aws:applications name: example inputs: action: Install source: "{{ source }}" ``` ------ #### [ JSON ] ``` { "schemaVersion":"2.2", "description":"aws:applications", "parameters":{ "source":{ "description":"(Required) Source of msi.", "type":"String" } }, "mainSteps":[ { "action":"aws:applications", "name":"example", "inputs":{ "action":"Install", "source":"{{ source }}" } } ] } ``` ------ #### 스키마 1.2 ------ #### [ YAML ] ``` --- runtimeConfig: aws:applications: properties: - id: 0.aws:applications action: "{{ action }}" parameters: "{{ parameters }}" source: "{{ source }}" sourceHash: "{{ sourceHash }}" ``` ------ #### [ JSON ] ``` { "runtimeConfig":{ "aws:applications":{ "properties":[ { "id":"0.aws:applications", "action":"{{ action }}", "parameters":"{{ parameters }}", "source":"{{ source }}", "sourceHash":"{{ sourceHash }}" } ] } } } ``` ------ ### 속성 **작업** 수행할 작업입니다. 형식: 열거형 유효한 값: `Install` \$1 `Repair` \$1 `Uninstall` 필수 여부: 예 **parameters** 설치 프로그램에 대한 파라미터입니다. 유형: 문자열 필수 여부: 아니요 **source** 애플리케이션용 `.msi` 파일의 URL입니다. 유형: 문자열 필수 항목 여부: 예 **sourceHash** `.msi` 파일의 SHA256 해시입니다. 유형: 문자열 필수 여부: 아니요 ## `aws:cloudWatch` Windows Server에서 Amazon CloudWatch 또는 Amazon CloudWatch Logs로 데이터를 내보내고 CloudWatch 지표를 사용하여 데이터를 모니터링합니다. 이 플러그인은 Windows Server 운영 체제에서만 실행됩니다. Amazon Elastic Compute Cloud(Amazon EC2)와의 CloudWatch 통합 구성에 대한 자세한 내용은 *Amazon CloudWatch 사용 설명서*의 [CloudWatch 에이전트를 사용하여 지표, 로그 및 추적 수집](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)을 참조하세요. **중요** 통합 CloudWatch 에이전트가 Amazon CloudWatch Logs에 로그 데이터를 전송하기 위한 도구로 SSM Agent를 대체했습니다. SSM Agent aws:cloudWatch 플러그인은 지원되지 않습니다. 로그 수집 프로세스에 통합된 CloudWatch 에이전트만 사용하는 것이 좋습니다. 자세한 내용은 다음 항목을 참조하세요. [통합 CloudWatch Logs로 노드 로그 전송(CloudWatch 에이전트)](monitoring-cloudwatch-agent.md) [Windows 서버 노드 로그 수집을 CloudWatch 에이전트로 마이그레이션](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate) *Amazon CloudWatch 사용 설명서의 [CloudWatch 에이전트를 사용하여 지표, 로그 및 추적 수집](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html).* 다음의 데이터 형식을 내보내고 모니터링할 수 있습니다. **ApplicationEventLog** CloudWatch Logs로 애플리케이션 이벤트 로그 데이터를 보냅니다. **CustomLogs** Amazon CloudWatch Logs로 텍스트 기반 로그 파일을 보냅니다. CloudWatch 플러그인은 로그 파일의 지문을 생성합니다. 그러면 시스템이 각 지문에 데이터 오프셋을 연결합니다. 플러그인은 변경 사항이 있을 경우 파일을 업로드하고, 오프셋을 기록하고, 지문에 오프셋을 연결합니다. 이 방법은 사용자가 플러그인을 설정하고, 대량 파일을 포함하는 디렉터리에 서비스를 연결하고, 시스템이 모든 파일을 업로드하는 상황을 방지하기 위해 사용됩니다. 애플리케이션이 폴링 도중 로그를 자르거나 정리하려 할 경우 `LogDirectoryPath`에 지정된 모든 로그에서 항목이 손실될 수 있음을 유의하세요. 예를 들어 로그 파일 크기를 제한하려는 경우, 해당 제한에 도달하면 새 로그 파일을 생성한 후 새 파일에 데이터를 계속 기록합니다. **ETW** CloudWatch Logs로 Windows용 이벤트 추적(ETW) 데이터를 보냅니다. **IIS** CloudWatch Logs로 IIS 로그 데이터를 전송합니다. **PerformanceCounter** CloudWatch로 Windows 성능 카운터를 보냅니다. CloudWatch에 지표로 업로드할 여러 범주를 선택할 수 있습니다. 업로드하려는 각 성능 카운터에 대해 고유한 ID(예: "PerformanceCounter2", "PerformanceCounter3" 등)를 지정하여 **PerformanceCounter** 섹션을 생성하고 해당 속성을 구성합니다. AWS Systems Manager SSM Agent 또는 CloudWatch 플러그 인이 중지되고 성능 카운터 데이터가 에 로그되지 않습니다. 이 동작은 사용자 지정 로그나 Windows 이벤트 로그와 다릅니다. 사용자 정의 로그와 Windows 이벤트 로그는 성능 측정 데이터를 보관했다가 SSM Agent 또는 CloudWatch 플러그인이 사용 가능해지면 CloudWatch에 업로드합니다. **SecurityEventLog** CloudWatch Logs로 보안 이벤트 로그 데이터를 보냅니다. **SystemEventLog** CloudWatch Logs로 시스템 이벤트 로그 데이터를 전송합니다. 데이터에 다음 대상을 정의할 수 있습니다. **CloudWatch** 성능 카운터 지표 데이터가 보내지는 대상입니다. 고유한 ID(예: "CloudWatch2", CloudWatch3" 등)를 갖는 섹션을 추가하고 새 ID마다 다른 리전을 지정하여 동일한 데이터를 여러 위치로 보낼 수 있습니다. **CloudWatchLogs** 로그 데이터가 보내지는 대상입니다. 고유한 ID(예: "CloudWatchLogs2", CloudWatchLogs3" 등)를 갖는 섹션을 추가하고 새 ID마다 다른 리전을 지정하여 동일한 데이터를 여러 위치로 보낼 수 있습니다. ### 구문 ``` "runtimeConfig":{ "aws:cloudWatch":{ "settings":{ "startType":"{{ status }}" }, "properties":"{{ properties }}" } } ``` ### 설정 및 속성 **AccessKey** 사용자의 액세스 키 ID입니다. 이 속성은 IAM 역할을 사용해 인스턴스를 시작하지 않은 한 필수입니다. 이 속성은 SSM과 함께 사용할 수 없습니다. 유형: 문자열 필수 여부: 아니요 **CategoryName** Performance Monitor의 성능 카운터 범주입니다. 유형: 문자열 필수 항목 여부: 예 **CounterName** Performance Monitor의 성능 카운터 이름입니다. 유형: 문자열 필수 항목 여부: 예 **CultureName** 타임스탬프가 기록되는 로캘입니다. **CultureName**이 공백이면 기본적으로 Windows Server 인스턴스에서 사용 중인 것과 동일한 로캘로 설정됩니다. 유형: 문자열 유효한 값: 지원되는 값 목록은 Microsoft 웹 사이트에서 [National Language Support(NLS)](https://msdn.microsoft.com/en-us/library/cc233982.aspx)를 참조하세요. **div**, **div-MV**, **hu**, **hu-HU** 값은 지원되지 않습니다. 필수 여부: 아니요 **DimensionName** Amazon CloudWatch 지표의 차원입니다. `DimensionName`를 지정할 경우 `DimensionValue`을 지정해야 합니다. 이런 파라미터는 메트릭 나열 시 또 다른 보기를 제공합니다. 특정 차원에 속하는 모든 지표를 볼 수 있도록 여러 지표에서 같은 차원을 사용할 수 있습니다. 유형: 문자열 필수 여부: 아니요 **DimensionValue** Amazon CloudWatch 지표의 차원 값입니다. 유형: 문자열 필수 여부: 아니요 **인코딩** 사용할 파일 인코딩입니다(예: UTF-8). 표시 이름이 아니라 인코딩 이름을 사용합니다. 유형: 문자열 유효한 값: 지원되는 값 목록은 Microsoft Learn Library의 [Encoding Class](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0)를 참조하세요. 필수 여부: 예 **필터** 로그 이름의 접두사입니다. 모든 파일을 모니터링하려면 이 파라미터를 공백으로 둡니다. 유형: 문자열 유효한 값: 지원되는 값 목록은 MSDN 라이브러리에서 [FileSystemWatcherFilter Property](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx) 항목을 참조하세요. 필수 여부: 아니요 **흐름** 데이터의 대상(CloudWatch 또는 CloudWatch Logs)과 함께 업로드할 각 데이터 형식입니다. 예를 들어 `"Id": "PerformanceCounter"`에서 정의된 성능 카운터를 `"Id": "CloudWatch"`에서 정의된 CloudWatch 대상으로 보내려면 **"PerformanceCounter,CloudWatch"**를 입력합니다. 마찬가지로, 사용자 정의 로그, ETW 로그 및 시스템 로그를 `"Id": "ETW"`에서 정의된 CloudWatch Logs 대상으로 보내려면 **"(ETW),CloudWatchLogs"**를 입력합니다. 또한, 같은 성능 카운터 또는 로그 파일을 두 개 이상의 대상으로 보낼 수 있습니다. 예를 들어, 애플리케이션 로그를 `"Id": "CloudWatchLogs"` 및 `"Id": "CloudWatchLogs2"`에서 정의된 두 개의 대상으로 보내려면 **"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**를 입력합니다. 유형: 문자열 유효한 값(원본): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog` 유효한 값(대상): `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n* 필수 여부: 예 **FullName** 구성 요소의 전체 이름입니다. 유형: 문자열 필수 항목 여부: 예 **Id** 데이터 원본 또는 대상을 식별합니다. 이 식별자는 구성 파일 내에서 고유해야 합니다. 유형: 문자열 필수 항목 여부: 예 **InstanceName** 성능 카운터 인스턴스의 이름입니다. 각 성능 카운터 구성 요소가 메트릭을 하나씩만 지원하므로, 모든 인스턴스를 나타내기 위해 별표(\$1)를 사용하지 않도록 합니다. 하지만 **\$1Total**을 사용할 수는 있습니다. 유형: 문자열 필수 항목 여부: 예 **수준** Amazon CloudWatch로 전송할 메시지의 유형입니다. 유형: 문자열 유효한 값: + **1** - 오류 메시지만 업로드됩니다. + **2** - 경고 메시지만 업로드됩니다. + **4** - 정보 메시지만 업로드됩니다. 이들 값을 적절히 더하여 두 가지 이상의 메시지 유형을 포함할 수 있습니다. 예를 들어 **3**은 오류 메시지(**1**)와 경고 메시지(**2**)가 포함된다는 의미입니다. 값 **7**은 오류 메시지(**1**), 경고 메시지(**2**) 및 정보 메시지(**4**)가 포함된다는 의미입니다. 필수 여부: 예 Windows 보안 로그는 수준을 7로 설정해야 합니다. **LineCount** 로그 파일을 식별하는 헤더의 행 수입니다. 예를 들어, IIS 로그 파일에 있는 헤더들은 사실상 동일합니다. **3**을 입력하면 로그 파일 헤더에서 처음 나오는 세 줄을 읽어 식별하는 식입니다. IIS 로그 파일에서 세 번째 줄은 날짜와 타임스탬프(로그 파일 간에 차이가 있음)입니다. 유형: 정수 필수 여부: 아니요 **LogDirectoryPath** CustomLogs의 경우, 로그가 EC2 인스턴스에서 저장되는 경로입니다. IIS 로그의 경우, 개별 사이트에 대해 IIS 로그가 저장되는 폴더입니다(예: **C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***). IIS 로그에는 W3C 로그 형식만 지원됩니다. IIS, NCSA 및 사용자 정의 형식은 지원되지 않습니다. 유형: 문자열 필수 항목 여부: 예 **LogGroup** 로그 그룹의 이름. 이 이름은 CloudWatch 콘솔에서 [**로그 그룹(Log Groups)**] 화면에 표시됩니다. 유형: 문자열 필수 항목 여부: 예 **LogName** 로그 파일의 이름입니다. 1. 로그 이름을 찾으려면 이벤트 뷰어의 탐색 창에서 [**애플리케이션 및 서비스 로그(Applications and Services Logs)**]를 선택합니다. 1. 로그 목록에서 업로드하려는 로그(예: `Microsoft` > `Windows` > `Backup` > `Operational`)를 마우스 오른쪽 버튼으로 클릭한 후 **Create Custom View(사용자 정의 뷰 생성)**를 선택합니다. 1. [**사용자 정의 뷰 생성(Create Custom View)**] 대화 상자에서 **XML** 탭을 선택합니다. **LogName**은