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 로그 보기 섹션을 참조하세요.

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) 아웃바운드 트래픽을 허용해야 합니다.

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

설명한 대로 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 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 엔드포인트에 연결합니다.

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

관리형 노드 가용성 문제 해결에 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를 사용하여 관리형 노드 가용성 문제 해결 단원을 참조하십시오.