SSM Agent 문제 해결

관리형 노드에서 작업을 실행하는 데 문제가 발생하면 AWS Systems Manager Agent(SSM Agent)에 문제가 있는 것일 수 있습니다. 다음 정보를 사용하면 SSM Agent 로그 파일을 보고 에이전트 문제를 해결하는 데 도움이 됩니다.

SSM Agent가 만료됨

SSM Agent의 업데이트된 버전은 Systems Manager에 새 기능이 추가되거나 기존 기능이 업데이트될 때마다 릴리스됩니다. 최신 버전의 에이전트를 사용하지 못하면 관리형 노드에서 다양한 Systems Manager 기능을 사용하지 못할 수 있습니다. 이러한 이유로 시스템의 SSM Agent 상태를 최신 상태로 유지하는 프로세스를 자동화하는 것이 좋습니다. 자세한 내용은 SSM Agent 업데이트 자동화을 참조하세요. SSM Agent 업데이트에 대해 알림을 수신하려면 GitHub에서 SSM Agent 릴리스 정보 페이지를 구독합니다.

SSM Agent 로그 파일을 사용하여 문제 해결

SSM Agent는 다음 파일에 정보를 기록합니다. 이 파일에 있는 정보는 문제를 해결하는 데도 도움이 됩니다. 디버그 로깅을 켜는 방법을 포함하여 SSM Agent 로그 파일에 대한 자세한 내용은 SSM Agent 로그 보기 섹션을 참조하세요.

참고

Windows 파일 탐색기를 사용하여 이러한 로그를 보려면 폴더 옵션에서 숨긴 파일 및 시스템 파일을 볼 수 있도록 허용해야 합니다.

Windows

• %PROGRAMDATA%\Amazon\SSM\Logs\amazon-ssm-agent.log

• %PROGRAMDATA%\Amazon\SSM\Logs\errors.log

Linux 및 macOS에서

• /var/log/amazon/ssm/amazon-ssm-agent.log

• /var/log/amazon/ssm/errors.log

Linux 관리형 노드의 경우 /var/log 디렉터리에 기록된 messages 파일에서 자세한 정보를 찾을 수 있습니다.

에이전트 로그를 사용하는 문제 해결에 대한 자세한 내용은 AWSre:Post 지식 센터의 SSM Agent 로그를 사용하여 내 관리형 인스턴스의 SSM Agent 관련 문제를 해결하려면 어떻게 해야 하나요?를 참조하세요.

에이전트 로그 파일이 교체되지 않음(Windows)

Windows Server 관리형 노드의 seelog.xml 파일에서 날짜 기반 로그 파일 교체를 지정해도 로그가 교체되지 않는 경우 fullname=true 파라미터를 지정합니다. 다음은 fullname=true 파라미터가 지정된 seelog.xml 구성 파일의 예입니다.

<seelog type="adaptive" mininterval="2000000" maxinterval="100000000" critmsgcount="500" minlevel="debug">
   <exceptions>
      <exception filepattern="test*" minlevel="error" />
   </exceptions>
   <outputs formatid="fmtinfo">
      <console formatid="fmtinfo" />
      <rollingfile type="date" datepattern="200601021504" maxrolls="4" filename="C:\ProgramData\Amazon\SSM\Logs\amazon-ssm-agent.log" fullname=true />
      <filter levels="error,critical" formatid="fmterror">
         <rollingfile type="date" datepattern="200601021504" maxrolls="4" filename="C:\ProgramData\Amazon\SSM\Logs\errors.log" fullname=true />
      </filter>
   </outputs>
   <formats>
      <format id="fmterror" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n" />
      <format id="fmtdebug" format="%Date %Time %LEVEL [%FuncShort @ %File.%Line] %Msg%n" />
      <format id="fmtinfo" format="%Date %Time %LEVEL %Msg%n" />
   </formats>
</seelog>

SSM 엔드포인트에 연결할 수 없음

SSM Agent에서는 다음과 같은 엔드포인트에 대한 HTTPS(포트 443) 아웃바운드 트래픽을 허용해야 합니다.

• ssm.region.amazonaws.com

• ssmmessages.region.amazonaws.com

리전은 미국 동부(오하이오) 리전의 us-east-2 같이 AWS Systems Manager가 지원하는 AWS 리전의 식별자를 나타냅니다. 지원되는 리전 값 목록은 Amazon Web Services 일반 참조의 Systems Manager 서비스 엔드포인트에 있는 리전 열을 참조하세요.

참고

2024년 이전에도 ec2messages.region.amazonaws.com도 필요했습니다. 2024년 이전에 출시된 AWS 리전의 경우 ssmmessages.region.amazonaws.com으로의 트래픽을 허용해야 하지만, ec2messages.region.amazonaws.com으로의 트래픽 허용은 선택 사항입니다.

2024년 이후에 출시된 리전의 경우 ssmmessages.region.amazonaws.com으로의 트래픽을 허용해야 하지만, 이러한 리전에서는 ec2messages.region.amazonaws.com 엔드포인트가 지원되지 않습니다.

설명한 대로 Amazon Linux 2 또는 Amazon Linux 2023과 같은 AWS에서 제공되는 Amazon Machine Images(AMIs)를 사용해도 앞의 엔드포인트와 통신할 수 없으면 SSM Agent가 작동하지 않습니다. 네트워크 구성에 개방형 인터넷 액세스가 있거나 사용자 정의 Virtual Private Cloud(VPC) 엔드포인트가 구성되어 있어야 합니다. 사용자 정의 VPC 엔드포인트를 생성할 계획이 없다면 인터넷 게이트웨이 또는 NAT 게이트웨이를 확인합니다. VPC 엔드포인트 관리 방법에 대한 자세한 내용은 Systems Manager용 VPC 엔드포인트를 사용하여 EC2 인스턴스의 보안 개선 섹션을 참조하세요.

VPC 구성 확인

Systems Manager로 EC2 인스턴스를 관리하려면 VPC 엔드포인트를 ssm.region.amazonaws.com, ssmmessages.region.amazonaws.com 및 경우에 따라 이 항목 앞부분에 설명된 SSM 엔드포인트에 연결할 수 없음, ec2messages.region.amazonaws.com에 대해 올바르게 구성해야 합니다. 네트워크 구성에 개방형 인터넷 액세스가 있거나 해당 가상 프라이빗 클라우드(VPC) 엔드포인트가 구성되어 있어야 합니다.

VPC 엔드포인트의 문제를 해결하려면 다음을 수행합니다.

• VPC 엔드포인트가 VPC 수준에 포함되어 있는지 확인합니다. 특정 서비스 이름의 VPC 엔드포인트를 VPC에서 찾을 수 없는 경우 먼저 VPC 수준에서 DNS 지원을 사용하도록 설정되어 있는지 확인합니다. 그런 다음 새 VPC 엔드포인트를 생성하고 각 가용 영역의 서브넷 하나에 연결합니다.

• VPC 엔드포인트 수준에서 프라이빗 DNS 이름을 사용하도록 설정되어 있는지 확인합니다. 프라이빗 DNS 이름은 기본적으로 사용하도록 설정되어 있지만 어느 시점에서 수동으로 사용하지 않도록 설정되었을 수 있습니다.

• 기존 VPC 엔드포인트가 적절한 서브넷에 연결되어 있는지 확인합니다. 또한 VPCE가 해당 가용 영역의 서브넷에 이미 연결되어 있는지 확인합니다.

자세한 정보는 다음의 주제를 참조하세요.

• AWS PrivateLink 가이드의 인터페이스 VPC 엔드포인트를 사용하여 AWS 서비스에 액세스

• AWS PrivateLink 가이드의 프라이빗 DNS 이름 연결

• Systems Manager용 VPC 엔드포인트를 사용하여 EC2 인스턴스의 보안 개선

VPC DNS 관련 속성 확인

VPC 구성 확인의 일환으로 속성 enableDnsSupport 및 enableDnsHostnames가 사용하도록 설정되어 있는지 확인합니다.

이러한 속성은 Amazon EC2 ModifyVPCAttribute API 작업 또는 AWS CLI 명령인 modify-vpc-attribute를 통해 사용하도록 설정할 수 있습니다.

Amazon VPC 콘솔에서 이러한 속성을 사용하도록 설정하는 방법에 대한 자세한 내용은 Amazon VPC 사용 설명서에서 View and update DNS attributes for your VPC를 참조하세요.

엔드포인트 보안 그룹의 수신 규칙 확인

구성한 모든 VPC 엔드포인트(ssm, ssmmessages, ec2messages)에 포트 443에서 트래픽의 수신을 허용하도록 해당 보안 그룹에 수신 규칙이 포함되어 있는지 확인합니다. 필요하다면 VPC에 하나의 수신 규칙이 포함된 새 보안 그룹을 생성하여 VPC의 CIDR(Classless Inter-Domain Routing) 블록에 대해 포트 443의 트래픽을 허용할 수 있습니다. 보안 그룹을 생성한 후 이를 각 VPC 엔드포인트에 연결합니다.

자세한 정보는 다음의 주제를 참조하세요.

• AWS re:Post의 Systems Manager를 사용하여 인터넷 액세스 없이 프라이빗 EC2 인스턴스를 관리할 수 있도록 VPC 엔드포인트를 생성하려면 어떻게 해야 하나요?

• Amazon VPC 사용 설명서의 VPC CIDR 블록

관리형 노드 가용성 문제 해결에 ssm-cli 사용

SSM Agent 버전 3.1.501.0부터 ssm-cli를 사용하여 Systems Manager에서 관리하는 기본 요구 사항을 관리형 노드에서 충족하는지를 판단하고 Fleet Manager의 관리형 노드 목록에 표시할 수 있습니다. ssm-cli는 SSM Agent 설치에 포함된 독립 실행형 명령줄 도구입니다. 실행 중인 것으로 확인된 Amazon EC2 인스턴스 또는 비 EC2 시스템이 Systems Manager의 관리형 노드 목록에 포함되지 않은 이유를 진단하는 데 도움이 되는 필수 정보를 수집하는 사전 구성된 명령이 포함되어 있습니다. 이러한 명령은 get-diagnostics 옵션을 지정할 때 실행됩니다.

자세한 내용은 ssm-cli를 사용하여 관리형 노드 가용성 문제 해결 단원을 참조하십시오.