SSM 접속 시 발생하는 SSM Agent unable to acquire credentials 문제 해결

안녕하세요 클래스메소드 김재욱(Kim Jaewook) 입니다. 이번 블로그에서는 SSM 접속 시 발생하는 SSM Agent unable to acquire credentials 문제를 해결하는 방법에 대해서 정리해 봤습니다.

문제 발생

NAT Gateway를 생성하고 EC2 인스턴스에서 SSM 접속을 시도했더니 다음과 같은 에러 메시지가 출력되었습니다.

SSM Agent unable to acquire credentials: <error>unexpected error getting instance profile role credentials or calling UpdateInstanceInformation. Skipping default host management fallback: retrieved credentials failed to report to ssm. Error: RequestError: send request failed

해당 에러 메시지는 SSM Agent가 인스턴스 프로파일(IAM Role) 자격 증명을 가져오지 못해 AWS Systems Manager와 통신할 수 없는 상태임을 의미합니다.

원인 파악

해당 문제는 대부분 아래 세 가지 이유 중 하나에서 발생합니다.

• IAM Role 미부착 또는 권한 부족
  • EC2 인스턴스에는 SSM Agent가 AWS Systems Manager와 통신할 수 있는 권한이 필요합니다.
    • 필요 권한: AmazonSSMManagedInstanceCore

Role이 없거나 권한이 충분하지 않으면 자격 증명을 가져올 수 없습니다.

• Instance Metadata Service(IMDS) 접근 문제
  • SSM Agent는 IMDS를 통해 IAM Role 자격 증명을 가져옵니다.
    • IMDS가 비활성화되어 있거나 IMDSv2 토큰을 제대로 사용하지 않으면 오류가 발생합니다.

정상이라면 JSON이 출력됩니다.

curl http://169.254.169.254/latest/meta-data/iam/info

• 네트워크 문제 (NAT Gateway)
  • 프라이빗 서브넷에서 인터넷으로 나가지 못하면 SSM API 호출이 실패합니다.
    • NAT Gateway가 없거나 라우팅 테이블 연결이 잘못됨
    • 혹은 VPC Endpoint(ssm, ec2messages, ssmmessages)가 없으면 통신 불가

마지막으로 IAM Role 자격 증명을 갱신하지 못해서 생긴 문제일 가능성도 있습니다.

• IAM Role 자격 증명 갱신 지연 문제
  • 인스턴스 실행 중 Role 연결/권한 변경이 적용되지 않은 상태에서 발생
  • 일부 환경에서는 IAM Role과 네트워크 설정이 올바른데도 접속이 실패
  • 이 경우 EC2 인스턴스를 중지 후 다시 시작하면 SSM Agent가 자격 증명을 갱신하여 정상 접속 가능

일부 환경에서는 IAM Role과 NAT Gateway 설정이 올바른데도 SSM 접속이 실패하는 경우가 있습니다. 이때는 EC2 인스턴스를 중지 후 다시 시작하면 SSM Agent가 IAM 자격증명을 갱신하여 정상적으로 접속할 수 있습니다.

이는 인스턴스 실행 중 자격증명 갱신이 지연되거나 실패했을 때 발생하는 임시 문제로, 재시작만으로 해결되는 경우가 많습니다.

이번에 발생한 문제 원인

이번에 발생한 문제 원인은 IAM Role 자격 증명을 갱신하지 못해서 생긴 문제였습니다.

이럴 경우 EC2 인스턴스를 중지 후 다시 시작하면 정상적으로 접속되는 경우가 있습니다.

• EC2 인스턴스가 실행 중인 상태에서 IAM Role이 새로 연결되었거나 권한 변경이 적용됨
• SSM Agent는 실행 중인 인스턴스의 IAM Role 자격증명을 주기적으로 가져오지만, 초기 상태에서 갱신이 실패할 수 있음
• 인스턴스를 재시작하면 IMDS에서 자격증명을 새로 가져오면서 SSM Agent가 정상 동작

즉, 인스턴스를 재시작하면 Role 정보가 초기화되고 SSM Agent가 올바른 자격증명을 획득하게 되는 것입니다.

마무리

SSM Agent unable to acquire credentials 오류는 대부분 다음과 같은 원인으로 발생합니다.

• IAM Role 미부착 또는 권한 부족: EC2에 필요한 Role이 없거나 AmazonSSMManagedInstanceCore 권한이 없으면 SSM Agent가 자격 증명을 가져올 수 없습니다.
• IMDS 접근 불가: SSM Agent는 인스턴스 메타데이터 서비스(IMDS)를 통해 Role 자격 증명을 가져옵니다. IMDS가 비활성화되어 있거나 IMDSv2 토큰을 제대로 사용하지 못하면 통신이 실패합니다.
• NAT Gateway 또는 VPC Endpoint 미설정: 프라이빗 서브넷에서 인터넷이나 AWS SSM 서비스로 나갈 수 없으면 접속이 불가합니다.
• IAM Role 자격 증명 갱신 지연: 인스턴스 실행 중 Role이 새로 연결되거나 권한 변경이 적용되지 않은 상태에서 발생할 수 있으며, 이 경우 EC2 인스턴스를 중지 후 재시작하면 해결되는 경우가 많습니다.

이번 사례에서는 IAM Role 자격 증명 갱신 지연이 원인이었으며, 인스턴스 재시작으로 정상 접속이 가능했습니다.

정리하자면, SSM Agent 관련 오류가 발생했을 때는 IAM Role, 네트워크, IMDS 상태를 먼저 점검하고, 모든 설정이 올바른데도 접속이 실패하면 인스턴스 재시작으로 간단히 문제를 해결할 수 있다는 점을 기억하면 좋습니다.

또한, 프라이빗 서브넷 환경에서 SSM을 안정적으로 사용하려면 다음 사항을 항상 확인하는 것이 중요합니다.

• EC2에 올바른 IAM Role이 연결되어 있는지 확인
• IMDS 접근이 정상적으로 가능한지 확인
• NAT Gateway 또는 필요한 VPC Endpoint가 설정되어 있는지 확인

이러한 점검 과정을 미리 갖춰 두면, 운영 환경에서 발생할 수 있는 SSM 접속 문제를 빠르게 진단하고 대응할 수 있습니다.
결과적으로, SSM Agent와 관련된 문제는 대부분 권한과 네트워크 구성, 자격 증명 갱신 상태와 연결되어 있으므로, 이 세 가지 요소를 중심으로 점검하면 대부분의 오류를 예방하거나 빠르게 해결할 수 있습니다.