[AWS] System Manager 간단 정리(SSM Agent Install)

1. AWS Systems Manager의 기능

• Fleet Manager
• Inventory
• Patch Manager
• Session Manager

2. SSM Agent

2.1 SSM Agent Install

https://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/manually-install-ssm-agent-linux.html

공식 문서에 들어가면 각 OS별로 설치 가이드를 제공한다.

(2024-10-10 기준)

AlmaLinux
Amazon Linux 2 및 Amazon Linux 2023
Amazon Linux 1 1
CentOS
CentOS Stream
Debian Server
Oracle Linux
Red Hat Enterprise Linux
Rocky Linux
SUSE Linux Enterprise Server
Ubuntu Server
macOS
Windows Server

 

SSM Agent는 일부 AMI에 사전 설치되어 있다.

(2024-10-10 기준)

AlmaLinux
2017년 9월 이후의 Amazon Linux 1 Base AMI
Amazon Linux 2
Amazon Linux 2 ECS 최적화 기본 AMIs
Amazon Linux 2023(AL2023)
Amazon EKS 최적화 Amazon Linux AMIs
macOS 10.14.x(Mojave), 10.15.x(Catalina), 11.x(Big Sur), 12.x(Monterey), 13.x(Ventura), 14.x(Sonoma)
SUSE Linux Enterprise Server(SLES) 12 및 15
Ubuntu Server 16.04, 18.04, 20.04 및 22.04
Windows Server 2008-2012 R2 AMIs는 2016년 11월 이후에 게시되었습니다.
Windows Server 2016, 2019 및 2022(Nano 버전 제외)

 

2.2 (예제) CentOS에 SSM Agent 설치하기

Processor Architecture를 확인하기 위해 다음 명령어를 실행해 본다.

uname -a
cat /etc/*release*

 

서버의 Architecture에 맞는 Install 명령어를 실행한다.

# x86_64 인스턴스
sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm

# ARM64 인스턴스
sudo yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm

 

설치가 완료되었다.

Agent가 실행 중인지 확인해 보자.

sudo systemctl status amazon-ssm-agent

# Agent가 실행 중일 경우 Active: active (running)라고 출력된다.
amazon-ssm-agent.service - amazon-ssm-agent
  Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: disabled)
  Active: active (running) since Tue 2022-04-19 15:57:27 UTC; 6s ago
           --truncated--

# Agent가 실행중이지 않을 경우 Active: inactive (dead)라고 출력된다.
amazon-ssm-agent.service - amazon-ssm-agent
  Loaded: loaded (/etc/systemd/system/amazon-ssm-agent.service; enabled; vendor preset: disabled)
  Active: inactive (dead) since Tue 2022-04-19 15:58:44 UTC; 2s ago
           --truncated--

 

2.3 SSM Agent 명령어

SSM Agent를 기동 및 중지, 상태 확인하는 명령어는 아래와 같다.

# Agent Start
sudo systemctl start amazon-ssm-agent

# Agent Stop
sudo systemctl stop amazon-ssm-agent

# Agent Restart
sudo systemctl restart amazon-ssm-agent

# Agent Status
sudo systemctl status amazon-ssm-agent

# 서버 재기동 시 자동으로 Agent가 실행되도록 Enable하는 명령어
sudo systemctl enable amazon-ssm-agent

각 OS에서 사용하는 명령어가 다를 수 있으니 공식 문서를 살펴본다.
예를 들어 Amazon Linux 1, RHEL 6.x에서는 sudo start amazon-ssm-agent와 같은 명령어를 사용한다.
https://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/ssm-agent-status-and-restart.html

 

2.4 SSM Agent 에러 로그

Agent를 실행했음에도 정상 동작하지 않을 경우 로그를 살펴본다.

# Linux
tail -n 20 /var/log/amazon/ssm/amazon-ssm-agent.log
tail -n 20 /var/log/amazon/ssm/errors.log

# Windows
%PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log
%PROGRAMDATA%\Amazon\SSM\Logs\errors.log

https://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/ssm-agent-logs.html

 

3. 네트워크

3.1 Network

https://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/setup-create-vpc.html

SSM Agent를 사용하기 위해서 다음 엔드포인트에 대한 HTTPS(443) 오픈 필요.
ssm.region.amazonaws.com
ssmmessages.region.amazonaws.com
ec2messages.region.amazonaws.com (--> SSM Agent 버전에 따라서 필요 없는 것 같음)

SSM 작업에서 S3를 사용할 경우 다음 엔드포인트에 대해서 HTTPS(443) 오픈 필요.
s3.amazonaws.com

SSM Agent 버전 3.3.40.0부터 Systems Manager는 가능한 경우 ec2messages:* 엔드포인트 대신 ssmmessages:* 엔드포인트를 사용하기 시작했다.
IAM 권한 정책에서 ssmmessages:*에 대한 액세스를 제공하는 경우, IAM 인스턴스 프로파일이 두 엔드포인트를 모두 허용하도록 구성되어 있더라도 SSM Agent가 ssmmessages:* 엔드포인트에 연결된다.

 

[참고]
ec2messages : Amazon Message Delivery Service
ssmmessages: Amazon Message Gateway Service

 

3.2 Private Network

Private Network 환경에서 구축하기 위해서 아래와 같은 VPC Endpoint를 생성하여 사용할 수 있다.

(Interface Type) ssm.region.amazonaws.com
(Interface Type) ssmmessages.region.amazonaws.com
(Interface Type) ec2messages.region.amazonaws.com (--> SSM Agent 버전에 따라서 필요 없는 것 같음)
(Gateway Type) s3.amazonaws.com

 

4. 권한

https://docs.aws.amazon.com/ko_kr/systems-manager/latest/userguide/setup-instance-permissions.html

AmazonSSMManagedInstanceCore

(선택 사항) S3 Policy

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": "s3:GetObject",
           "Resource": [
               "arn:aws:s3:::aws-ssm-region/*",
               "arn:aws:s3:::aws-windows-downloads-region/*",
               "arn:aws:s3:::amazon-ssm-region/*",
               "arn:aws:s3:::amazon-ssm-packages-region/*",
               "arn:aws:s3:::region-birdwatcher-prod/*",
               "arn:aws:s3:::aws-ssm-distributor-file-region/*",
               "arn:aws:s3:::aws-ssm-document-attachments-region/*",
               "arn:aws:s3:::patch-baseline-snapshot-region/*"
           ]
       },
       {
           "Effect": "Allow",
           "Action": [
               "s3:GetObject",
               "s3:PutObject",
               "s3:PutObjectAcl",
               "s3:GetEncryptionConfiguration"
           ],
           "Resource": [
               "arn:aws:s3:::amzn-s3-demo-bucket/*",
               "arn:aws:s3:::amzn-s3-demo-bucket"
           ]
       }
   ]
}


# 첫 번째 Statement 요소
# VPC 엔드포인트를 사용 중인 경우에만 필요.
# 각 region 자리 표시자를 이 정책이 사용되는 AWS 리전의 식별자로 대체.

# 두 번째 Statement 요소
# Systems Manager 작업에서 사용하기 위해 생성한 S3 버킷을 사용 중인 경우에만 필요.
# PutObjectAcl 액세스 제어 목록 권한은 다른 계정에서 S3 버킷에 대한 교차 계정 액세스를 지원하려는 경우에만 필요.
# GetEncryptionConfiguration 요소는 암호화를 사용하기 위해 S3 버킷을 구성할 경우 필요.

 

5. 에러

ERROR [RemoteRetrieve @ ec2_role_provider.go.144] EC2RoleProvider Failed to connect to Systems Manager with SSM role credentials. error calling RequestManagedInstanceRoleToken: AccessDeniedException: Systems Manager's instance management role is not configured for account: 123456789123

ERROR [minLog @ credentialrefresher.go.280] [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity. Default Host Management Err: error calling RequestManagedInstanceRoleToken: AccessDeniedException: Systems Manager's instance management role is not configured for account: 123456789123

==> Role을 Attach하지 않고 SSM Agent를 실행시킬 경우 위와 같이 발생
==> Role을 Attach하고 아무 권한을 부여하지 않으니 동일한 에러 발생

ERROR [HandleAwsError @ awserr.go.50] [ssm-agent-worker] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::123456789123:assumed-role/testec2/i-0662ceb237dxxxxxx is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-northeast-2:123456789123:instance/i-0662ceb237d1c2d2a with an explicit deny in an identity-based policy

ERROR [HandleAwsError @ awserr.go.50] [ssm-agent-worker] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::123456789123:assumed-role/testec2/i-0662ceb237dxxxxxx is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-northeast-2:123456789123:instance/i-0662ceb237d1c2d2a with an explicit deny in an identity-based policy


==> AmazonSSMManagedInstanceCore에서 몇몇 Action 권한을 뺐더니 위와 같이 에러 발생
이 경우 권한이 없다고하는 ssm:UpdateInstanceInformation 권한을 추가해줘야함.

 

7. Inventory

AWS Systems Manager > 노드 관리 > 인벤토리
SSM Command document 또는 Automation runbook를 기반으로 Inventory Association을 생성.

 

[예시]

AWS에서 제공하는 AWS-GatherSoftwareInventory라는 Document로 전체 인스턴스를 대상으로 Association을 생성한다.
아래와 같이 Association을 생성하면 3일에 한 번씩 Document를 실행하고 SSM 인벤토리 대시보드에서 확인할 수 있다.

aws ssm create-association \
   --name "AWS-GatherSoftwareInventory" \
   --targets "Key=InstanceIds,Values=*" \
   --association-name "Assonication-Name" \
   --schedule-expression "rate(3 days)" \
   --region ap-northeast-2

 

8. Run Command

aws ssm send-command \
   --document-name "SSM Document Name 작성" \
   --document-version "1" \
   --targets "[{\"Key\":\"InstanceIds\",\"Values\":[\"$instance_id\"]}]" \
   --parameters '{}' \
   --timeout-seconds 600 \
   --max-concurrency "50" \
   --max-errors "0" \
   --output-s3-bucket-name "Bucket Name 작성" \
   --region ap-northeast-2

aws s3api get-object \
   --bucket BUCKET_NAME \
   --key "$command_id/$instance_id/awsrunShellScript/runShellScript/stdout" \
   send-cmd-output.txt