• AWS Systems Manager CloudWatch 대시보드는 2026년 4월 30일 이후에는 더 이상 사용할 수 없습니다. 고객은 Amazon CloudWatch 콘솔을 계속 사용하여 현재와 마찬가지로 Amazon CloudWatch 대시보드를 보고, 생성하고, 관리할 수 있습니다. 자세한 내용은 [Amazon CloudWatch 대시보드 설명서](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)를 참조하세요.
# Ansible 플레이북을 실행하는 연결 생성
`AWS-ApplyAnsiblePlaybooks` SSM 문서를 사용하여 Ansible 플레이북을 실행하는 State Manager 연결을 생성할 수 있습니다. State Manager는 AWS Systems Manager의 도구입니다. 이 문서는 플레이북 실행을 위해 다음과 같은 이점을 제공합니다.
+ 복잡한 플레이북 실행 지원
+ GitHub 및 Amazon Simple Storage Service(S3)에서 플레이북 다운로드 지원
+ 압축된 플레이북 구조 지원
+ 향상된 로깅
+ 플레이북이 번들로 제공될 때 실행할 플레이북 지정 가능
**참고**
Systems Manager에는 Ansible 플레이북을 실행하는 State Manager 연결을 생성하는 데 사용할 수 있는 SSM 문서가 2개(`AWS-RunAnsiblePlaybook`, `AWS-ApplyAnsiblePlaybooks`)가 포함되어 있습니다. `AWS-RunAnsiblePlaybook` 문서는 더 이상 사용되지 않습니다. Systems Manager에서 레거시용으로 제공됩니다. `AWS-ApplyAnsiblePlaybooks` 문서에 여기서 설명한 기능 향상 부분이 있으므로 이 문서를 사용하는 것이 좋습니다.
Ansible 플레이북을 실행하는 연결은 macOS에서 지원되지 않습니다.
**복잡한 플레이북 실행 지원**
`AWS-ApplyAnsiblePlaybooks` 문서는 지정된 주요 플레이북을 실행하기 전에 먼저 로컬 디렉터리에 전체 파일 구조를 복사하므로 번들로 제공되는 복잡한 플레이북을 지원합니다. 소스 플레이북은 zip 파일 또는 디렉터리 구조로 제공할 수 있습니다. Zip 파일이나 디렉터리는 GitHub 또는 Amazon S3에 저장할 수 있습니다.
**GitHub에서 플레이북 다운로드 지원**
`AWS-ApplyAnsiblePlaybooks` 문서는 `aws:downloadContent` 플러그인을 사용하여 플레이북 파일을 다운로드합니다. 파일은 GitHub에 한 개의 파일로 또는 결합된 플레이북 세트로 저장할 수 있습니다. GitHub에서 콘텐츠를 다운로드하려면 GitHub 리포지토리에 대한 정보를 JSON 형식으로 지정합니다. 다음 예를 참고하세요
```
{
"owner":"TestUser",
"repository":"GitHubTest",
"path":"scripts/python/test-script",
"getOptions":"branch:master",
"tokenInfo":"{{ssm-secure:secure-string-token}}"
}
```
**Amazon S3에서 플레이북 다운로드 지원**
Amazon S3에서 Ansible 플레이북을 단일 .zip 파일 또는 디렉터리 구조로 저장하고 다운로드할 수도 있습니다. Amazon S3에서 콘텐츠를 다운로드하려면 파일에 대한 경로를 지정합니다. 다음은 두 가지 예입니다.
**예 1: 특정 플레이북 파일 다운로드**
```
{
"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml"
}
```
**예 2: 디렉터리 콘텐츠 다운로드**
```
{
"path":"https://s3.amazonaws.com/amzn-s3-demo-bucket/ansible/webservers/"
}
```
**중요**
Amazon S3를 지정한 경우 관리형 노드의 AWS Identity and Access Management(IAM) 인스턴스 프로파일에 S3 버킷에 대한 권한이 포함되어야 합니다. 자세한 내용은 [Systems Manager에 필요한 인스턴스 권한 구성](setup-instance-permissions.md)을 참조하세요.
**압축된 플레이북 구조 지원**
`AWS-ApplyAnsiblePlaybooks` 문서를 사용하면 다운로드한 번들에서 압축된 .zip 파일을 실행할 수 있습니다. 문서는 압축된 파일이 다운로드한 파일에 .zip 형식으로 포함되어 있는지 점검합니다. .zip 파일이 있으면 문서는 자동으로 파일 압축을 푼 다음 지정된 Ansible 자동화를 실행합니다.
**향상된 로깅**
`AWS-ApplyAnsiblePlaybooks` 문서에는 다양한 로깅 수준을 지정하는 데 필요한 파라미터 옵션이 포함되어 있습니다. 세부 수준이 낮으면 -v를, 중간이면 -vvv를, 디버그 레벨 로깅 수준이면 -vvvv를 지정합니다. 이러한 옵션은 Ansible 세부 수준 옵션에 직접 매핑됩니다.
**플레이북이 번들로 제공될 때 실행할 플레이북 지정 가능**
`AWS-ApplyAnsiblePlaybooks` 문서에는 여러 개의 플레이북이 번들로 제공될 때 실행할 플레이북을 지정하는 데 필요한 파라미터가 포함되어 있습니다. 이 옵션을 사용하면 다양한 사용 사례를 지원하도록 플레이북을 유연하게 실행할 수 있습니다.
## 설치된 종속성 이해
**InstallDependencies** 파라미터에 **True**를 지정하면 Systems Manager는 노드에 다음 종속성이 설치되어 있는지 확인합니다.
+ **Ubuntu Server/Debian Server**: Apt-get(패키지 관리), Python 3, Ansible, Unzip
+ **Amazon Linux** 지원 버전: Ansible
+ **RHEL**: Python 3, Ansible, Unzip
이 종속성 중 하나 이상이 없다면 Systems Manager는 해당 종속성을 자동으로 설치합니다.
## Ansible 플레이북을 실행하는 연결 생성(콘솔)
다음 절차에서는 Systems Manager 콘솔을 사용하여 `AWS-ApplyAnsiblePlaybooks` 문서로 Ansible 플레이북을 실행하는 State Manager 연결을 생성하는 방법을 설명합니다.
**Ansible 플레이북을 실행하는 연결을 생성하려면(콘솔)**
1. [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)에서 AWS Systems Manager 콘솔을 엽니다.
1. 탐색 창에서 **State Manager**를 선택합니다.
1. **State Manager**를 선택하고 **Create association(연결 생성)**을 선택합니다.
1. **이름**에 연결의 목적을 기억하는 데 도움이 되는 이름을 지정합니다.
1. [**문서(Document)**] 목록에서 **`AWS-ApplyAnsiblePlaybooks`**를 선택합니다.
1. **파라미터** 섹션의 **소스 유형**에서 **GitHub** 또는 **S3**를 선택합니다.
**GitHub**
**GitHub**를 선택하는 경우 다음 형식으로 리포지토리 정보를 입력합니다.
```
{
"owner":"user_name",
"repository":"name",
"path":"path_to_directory_or_playbook_to_download",
"getOptions":"branch:branch_name",
"tokenInfo":"{{(Optional)_token_information}}"
}
```
**S3**
[**S3**]를 선택하는 경우 다음 형식으로 경로 정보를 입력합니다.
```
{
"path":"https://s3.amazonaws.com/path_to_directory_or_playbook_to_download"
}
```
1. **종속성 설치**에서 옵션을 선택합니다.
1. (선택 사항) **Playbook File(플레이북 파일)**에 파일 이름을 입력합니다. Zip 파일에 플레이북이 포함된 경우 Zip 파일에 대한 상대 경로를 지정합니다.
1. (선택 사항) **추가 변수**에서 실행 시간 동안 State Manager에서 Ansible에 전송할 변수를 입력합니다.
1. (선택 사항) **확인**에서 옵션을 선택합니다.
1. (선택 사항) **상세 표시**에서 옵션을 선택합니다.
1. **대상**에서 옵션을 선택합니다. 태그 사용에 대한 자세한 내용은 [State Manager 연결에서의 대상 및 속도 제어 이해](systems-manager-state-manager-targets-and-rate-controls.md) 섹션을 참조하세요.
1. **일정 지정** 섹션에서 **On Schedule(일정이 있을 때)** 또는 **No schedule(일정이 없을 때)**을 선택합니다. **On Schedule(일정이 있을 때)**을 선택한 경우 제공된 버튼을 사용하여 연결에 대한 cron 또는 rate 일정을 생성합니다.
1. **고급 옵션** 섹션의 **규정 준수 심각도**에서 연결에 대한 심각도 수준을 선택합니다. 규정 준수 보고는 여기서 지정한 심각도 수준과 함께 연결 상태가 준수인지 아니면 미준수인지를 나타냅니다. 자세한 내용은 [State Manager 연결 규정 준수 정보](compliance-about.md#compliance-about-association) 섹션을 참조하세요.
1. **Rate control(속도 제어)** 섹션에서 관리형 노드 플릿 간에 State Manager 연결을 실행하기 위한 옵션을 구성합니다. 속도 제어 사용에 대한 자세한 내용은 [State Manager 연결에서의 대상 및 속도 제어 이해](systems-manager-state-manager-targets-and-rate-controls.md) 섹션을 참조하세요.
**동시성** 섹션에서 옵션을 선택합니다.
+ **대상**을 선택하여 연결을 동시에 실행할 수 있는 대상 수(절대 개수)를 입력합니다.
+ **백분율**을 선택하여 연결을 동시에 실행할 수 있는 대상의 백분율을 입력합니다.
**오류 임계값** 섹션에서 옵션을 선택합니다.
+ **오류**를 선택하여 State Manager에서 추가 대상에 대한 연결 실행을 중지하기 전에 허용되는 절대 오류 수를 입력합니다.
+ **백분율**을 선택하여 State Manager에서 추가 대상에 대한 연결 실행을 중지하기 전에 허용되는 오류 비율을 입력합니다.
1. (선택 사항) **출력 옵션**에서 명령 출력을 파일에 저장하려면 **S3 버킷에 쓰기 활성화** 옆의 상자를 선택합니다. 상자에 버킷 및 접두사(폴더) 이름을 입력합니다.
**참고**
데이터를 S3 버킷에 쓰는 기능을 부여하는 S3 권한은 이 작업을 수행하는 IAM 사용자의 권한이 아닌 관리형 노드에 할당된 인스턴스 프로파일의 권한입니다. 자세한 내용은 [Systems Manager에 필요한 인스턴스 권한 구성](setup-instance-permissions.md)이나 [하이브리드 환경을 위한 IAM 서비스 역할 생성](hybrid-multicloud-service-role.md)을 참조하세요. 또한 지정된 S3 버킷이 다른 AWS 계정에 있는 경우 관리형 노드와 연결된 인스턴스 프로파일 또는 IAM 서비스 역할은 해당 버킷에 쓸 수 있는 권한이 있어야 합니다.
1. **연결 생성**을 선택합니다.
**참고**
태그를 사용하여 하나 이상의 대상 노드에 대해 연결을 생성한 다음 노드에서 태그를 제거하면 해당 노드가 더 이상 연결을 실행하지 않습니다. 이러한 노드는 State Manager 문서에서 연결 해제됩니다.
## Ansible 플레이북을 실행하는 연결 생성(CLI)
다음 절차에서는 AWS Command Line Interface(AWS CLI)을 사용하여 `AWS-ApplyAnsiblePlaybooks` 문서로 Ansible 플레이북을 실행하는 State Manager 연결을 생성하는 방법을 설명합니다.
**Ansible 플레이북을 실행하는 연결을 생성하려면(CLI)**
1. 아직 하지 않은 경우 AWS Command Line Interface(AWS CLI)을 설치하고 구성합니다.
자세한 내용은 [최신 버전의 AWS CLI 설치 또는 업데이트](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)를 참조하세요.
1. 다음 명령 중 하나를 실행하면 태그로 노드를 대상 지정하여 Ansible 플레이북을 실행하는 연결을 생성할 수 있습니다. 각 *example resource placeholder*를 사용자의 정보로 바꿉니다. Command (A)는 소스 유형으로 GitHub를 지정합니다. Command (B)는 소스 유형으로 Amazon S3를 지정합니다.
**(A) GitHub 소스**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"],"TimeoutSeconds":["3600"]}' \
--association-name "name" \
--schedule-expression "cron_or_rate_expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"owner_name\", \"repository\": \"name\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"], "TimeoutSeconds":["3600"]}' ^
--association-name "name" ^
--schedule-expression "cron_or_rate_expression"
```
------
다음 예를 참고하세요
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets "Key=tag:OS,Values=Linux" \
--parameters '{"SourceType":["GitHub"],"SourceInfo":["{\"owner\":\"ansibleDocumentTest\", \"repository\": \"Ansible\", \"getOptions\": \"branch:master\"}"],"InstallDependencies":["True"],"PlaybookFile":["hello-world-playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
**(B) S3 소스**
------
#### [ Linux & macOS ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets Key=tag:TagKey,Values=TagValue \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' \
--association-name "name" \
--schedule-expression "cron_or_rate_expression"
```
------
#### [ Windows ]
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" ^
--targets Key=tag:TagKey,Values=TagValue ^
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/path_to_Zip_file,_directory,_or_playbook_to_download\"}"],"InstallDependencies":["True_or_False"],"PlaybookFile":["file_name.yml"],"ExtraVariables":["key/value_pairs_separated_by_a_space"],"Check":["True_or_False"],"Verbose":["-v,-vv,-vvv, or -vvvv"]}' ^
--association-name "name" ^
--schedule-expression "cron_or_rate_expression"
```
------
다음 예를 참고하세요
```
aws ssm create-association --name "AWS-ApplyAnsiblePlaybooks" \
--targets "Key=tag:OS,Values=Linux" \
--parameters '{"SourceType":["S3"],"SourceInfo":["{\"path\":\"https://s3.amazonaws.com/amzn-s3-demo-bucket/playbook.yml\"}"],"InstallDependencies":["True"],"PlaybookFile":["playbook.yml"],"ExtraVariables":["SSM=True"],"Check":["False"],"Verbose":["-v"]}' \
--association-name "AnsibleAssociation" \
--schedule-expression "cron(0 2 ? * SUN *)"
```
**참고**
State Manager 연결은 cron 및 rate 표현식 중 일부를 지원하지 않습니다. 연결에 대한 cron 및 rate 표현식을 생성하는 방법에 대한 자세한 내용은 [참조: Systems Manager용 Cron 및 Rate 표현식](reference-cron-and-rate-expressions.md) 섹션을 참조하세요.
시스템은 해당 노드에 연결을 생성하고 그 상태를 즉시 적용하려고 합니다.
1. 다음 명령을 실행하여 방금 생성한 연결의 업데이트된 상태를 확인합니다.
```
aws ssm describe-association --association-id "ID"
```