SSM Agent 로그를 사용하여 관리형 인스턴스의 SSM Agent 문제를 해결하려면 어떻게 해야 합니까?

최종 업데이트 날짜: 2022년 10월 17일

AWS Systems Manager Agent(SSM Agent)가 성공적으로 실행되지 않지만 SSM Agent 로그를 사용하여 문제를 해결하는 방법을 모르겠습니다. SSM 에이전트 로그 메시지에 액세스하여 메시지를 해석하려면 어떻게 해야 합니까?

간략한 설명

SSM 에이전트는 관리형 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스에서 실행되며 AWS Systems Manager 서비스의 요청을 처리합니다. SSM 에이전트를 사용하려면 다음 조건이 충족되어야 합니다.

  • SSM 에이전트는 필요한 서비스 엔드포인트에 연결해야 합니다.
  • SSM 에이전트는 Systems Manager API 호출을 호출하기 위해 AWS Identity and Access Management(IAM) 권한이 필요합니다.

이러한 조건 중 하나가 충족되지 않으면 SSM 에이전트가 성공적으로 실행되지 않습니다.

SSM 에이전트 실패의 근본 원인을 확인하려면 다음 위치에서 SSM 에이전트 로그를 검토하세요.

Linux

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

Windows

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

참고: SSM 에이전트가 새 기능으로 자주 업데이트되므로 SSM 에이전트에 대한 자동 업데이트를 구성하는 것이 좋습니다.

해결 방법

로그를 검토하고 SSM 에이전트 문제가 엔드포인트 연결 누락 또는 권한 누락으로 인한 것인지 확인한 후 다음 문제 해결 단계를 수행합니다.

SSM 에이전트가 필요한 엔드포인트와 통신할 수 없음

SSM 에이전트가 메타데이터 서비스에 연결할 수 없음

SSM 에이전트가 메타데이터 서비스에 연결할 수 없으므로 SSM 에이전트가 인스턴스 메타데이터 서비스에서 리전 정보, IAM 역할 및 인스턴스 ID를 찾을 수 없습니다. SSM 에이전트가 메타데이터 서비스 엔드포인트에 도달할 수 없는 경우 SSM 에이전트 로그에 다음과 유사한 오류 메시지가 나타납니다.

INFO- Failed to fetch instance ID. Data from vault is empty. RequestError: send request failed caused by: Get http://169.254.169.254/latest/meta-data/instance-id

이 오류의 가장 일반적인 원인은 프록시를 사용하도록 SSM Agent를 구성하지 않고 프록시를 사용하여 인스턴스에서 아웃바운드 인터넷 연결을 설정하기 때문입니다. 프록시를 사용하도록 SSM Agent를 구성하세요.

Windows 인스턴스에서는 사용자 지정 AMI를 사용하여 인스턴스를 시작할 때 잘못 구성된 영구 네트워크 경로로 인해 오류가 발생할 수도 있습니다. 메타데이터 서비스 IP의 경로가 올바른 기본 게이트웨이를 가리키는지 확인해야 합니다.

SSM Agent가 Systems Manager 서비스 엔드포인트에 연결할 수 없음

SSM Agent는 포트 443에서 다음 Systems Manager 서비스 API 호출과의 아웃바운드 연결을 설정해야 합니다. 연결을 설정하지 않으면 SSM Agent가 실패합니다.

  • SSM 엔드포인트: ssm.REGION.amazonaws.com
  • EC2 메시징 엔드포인트: ec2messages.REGION.amazonaws.com
  • SSM 메시징 엔드포인트: ssmmessages.REGION.amazonaws.com

참고: SSM Agent는 인스턴스 메타데이터 서비스에서 검색한 리전 정보를 사용하여 이러한 엔드포인트의 REGION 값을 바꿉니다.

SSM Agent가 Systems Manager 엔드포인트와 연결할 수 없는 경우 SSM 에이전트 로그에 다음과 유사한 오류 메시지가 나타납니다.

ERROR [HealthCheck] error when calling AWS APIs. error details - RequestError: send request failed caused by: Post https://ssm.ap-southeast-2.amazonaws.com/: dial tcp 172.31.24.65:443: i/o timeout
DEBUG [MessagingDeliveryService] RequestError: send request failed
caused by: Post https://ec2messages.ap-southeast-2.amazonaws.com/: net/http: request cancelled while waiting for connection (Client.Timeout exceeded while awaiting headers)

SSM 에이전트가 포트 443의 Systems Manager API 엔드포인트와 연결할 수 없는 몇 가지 일반적인 이유는 다음과 같습니다.

  • 인스턴스 송신 보안 그룹 규칙은 포트 443에서 발신 연결을 허용하지 않습니다.
  • Virtual Private Cloud(VPC) 엔드포인트 수신 및 송신 보안 그룹 규칙은 포트 443에서 VPC 인터페이스 엔드포인트에 대한 수신 및 발신 연결을 허용하지 않습니다.
  • 인스턴스가 퍼블릭 서브넷에 있을 때 인터넷 게이트웨이를 사용하여 트래픽을 전달하도록 라우팅 테이블 규칙이 구성되지 않았습니다.
  • 인스턴스가 프라이빗 서브넷에 있을 때 NAT 게이트웨이 또는 VPC 엔드포인트를 사용하여 트래픽을 전달하도록 라우팅 테이블 규칙이 구성되지 않습니다.
  • 라우팅 테이블 규칙이 모든 발신 연결에 프록시를 사용하도록 구성되었는데 SSM 에이전트가 프록시를 사용하도록 구성되지 않았습니다.

필요한 Systems Manager API 호출을 호출할 수 있는 권한이 SSM 에이전트에 없음

SSM 에이전트가 서비스에 대한 UpdateInstanceInformation API 호출을 수행할 권한이 없기 때문에 SSM 에이전트가 Systems Manager에서 온라인으로 자신을 등록하지 못했습니다.

SSM 에이전트가 예상대로 작동하고 있음을 서비스에서 알 수 있도록 SSM 에이전트와의 연결을 유지하려면 UpdateInstanceInformation API 호출이 필요합니다. SSM 에이전트는 상태 확인 정보를 제공하기 위해 5분마다 클라우드에서 Systems Manager 서비스를 호출합니다. SSM 에이전트에 올바른 IAM 권한이 없는 경우 SSM 에이전트 로그에 다음과 유사한 오류 메시지가 표시됩니다.

SSM 에이전트가 잘못된 IAM 권한을 사용하는 경우:

ERROR [instanceID=i-XXXXX] [HealthCheck] error when calling AWS APIs. error details - AccessDeniedException: User: arn:aws:sts::XXX:assumed-role/XXX /i-XXXXXX is not authorized to perform: ssm:UpdateInstanceInformation on resource: arn:aws:ec2:ap-southeast-2:XXXXXXX:instance/i-XXXXXX
status code: 400, request id: XXXXXXXX-XXXX-XXXXXXX
INFO [instanceID=i-XXXX] [HealthCheck] increasing error count by 1

SSM 에이전트에 IAM 권한이 없는 경우:

ERROR [instanceID=i-XXXXXXX] [HealthCheck] error when calling AWS APIs. error details - NoCredentialProviders: no valid providers in chain. Deprecated. For verbose messaging see aws.Config.CredentialsChainVerboseErrors
2018-05-08 10:58:39 INFO [instanceID=i-XXXXXXX] [HealthCheck] increasing error count by 1

인스턴스에 연결된 IAM 역할에 인스턴스가 Systems Manager 서비스 핵심 기능을 사용하도록 허용하는 데 필요한 권한이 포함되어 있는지 확인합니다. 또는 인스턴스 프로필 역할이 아직 연결되어 있지 않은 경우 인스턴스 프로필 역할을 연결하고 AmazonsMmanagedInstanceCore 권한을 포함시킵니다.

Systems Manager에 필요한 IAM 권한에 대한 자세한 내용은 Systems Manager 인스턴스 프로필에 대한 정책 정보를 참조하세요.

Systems Manager API 호출 조절

SSM 에이전트를 실행하는 대량의 관리형 인스턴스가 여러 UpdateInstanceInformation API 호출을 동시에 수행하는 경우 API 호출이 제한될 수 있습니다.

인스턴스에 대한 UpdateInstanceInformation API 호출이 제한되면 SSM 에이전트 로그에 다음과 유사한 오류 메시지가 표시됩니다.

INFO [HealthCheck] HealthCheck reporting agent health.
ERROR [HealthCheck] error when calling AWS APIs. error details - ThrottlingException: Rate exceeded
status code: 400, request id: XXXXX-XXXXX-XXXX
INFO [HealthCheck] increasing error count by 1

ThrottlingException 오류를 방지하려면 다음 문제 해결 단계를 시도하세요.

  • API 호출 빈도를 줄입니다.
  • API를 호출할 때 오류 재시도 및 지수 백오프를 구현합니다.
  • 한 번에 모두 실행되지 않도록 API 호출 간격을 설정합니다.
  • UpdateInstanceInformation API 호출에 대한 조절 한도 증가를 요청합니다.

이 문서가 도움이 되었나요?


결제 또는 기술 지원이 필요하세요?