SSM Agent 로그를 사용하여 관리형 인스턴스의 SSM Agent 문제를 해결하려면 어떻게 해야 하나요?
AWS Systems Manager Agent(SSM Agent)가 정상적으로 실행되지 않는데 SSM Agent 로그를 사용하여 문제를 해결하는 방법을 모르겠습니다.
간략한 설명
SSM Agent는 관리형 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스에서 실행되고 AWS Systems Manager 서비스의 요청을 처리합니다. SSM Agent를 사용하려면 다음 조건이 충족되어야 합니다.
- SSM Agent가 필요한 서비스 엔드포인트에 연결되어야 합니다.
- SSM Agent는 Systems Manager API 호출을 호출하기 위해 AWS Identity and Access Management(IAM) 권한을 필요로 합니다.
- Amazon EC2가 IAM 인스턴스 프로파일의 유효한 보안 인증 정보를 수임해야 합니다.
이러한 조건 중 하나라도 충족되지 않으면 SSM Agent가 정상적으로 실행되지 않습니다.
SSM Agent 실행 실패의 근본 원인을 확인하려면 다음 위치에서 SSM Agent 로그를 검토하세요.
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 Agent는 새 기능으로 자주 업데이트되므로 SSM Agent에 대한 자동 업데이트를 구성하는 것이 좋습니다.
해결 방법
먼저, 로그를 검토하고 엔드포인트 연결 누락, 권한 누락 또는 보안 인증 정보 누락으로 인해 문제가 발생했는지 확인합니다. 그런 다음, 관련된 문제 해결 단계를 수행하여 문제를 해결합니다.
SSM Agent가 필요한 엔드포인트와 통신할 수 없음
SSM Agent가 메타데이터 서비스에 연결할 수 없음
SSM Agent가 메타데이터 서비스에 연결할 수 없으면 해당 서비스에서 AWS 리전 정보, IAM 역할 또는 인스턴스 ID도 찾을 수 없습니다. 이 경우 SSM Agent 로그에 다음과 비슷한 오류 메시지가 표시됩니다.
"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 에이전트를 구성하지 않고 인스턴스에서 아웃바운드 인터넷 연결에 프록시를 사용하기 때문입니다. 프록시를 사용하도록 SSM Agent를 구성하세요.
Windows 인스턴스에서는 사용자 지정 AMI를 사용하여 인스턴스를 시작할 때 잘못 구성된 영구 네트워크 경로로 인해 이 오류가 발생할 수도 있습니다. 메타데이터 서비스 IP의 경로가 올바른 기본 게이트웨이를 가리키는지 확인해야 합니다.
인스턴스의 메타데이터가 활성화되었는지 확인하려면 AWS Command Line Interface(AWS CLI)에서 다음 명령을 실행합니다. i-1234567898abcdef0을 인스턴스 ID로 바꿔야 합니다.
참고: AWS CLI 명령을 실행할 때 오류가 발생하는 경우 최신 버전의 AWS CLI를 사용하고 있는지 확인하세요.
aws ec2 describe-instances --instance-ids i-1234567898abcdef0 --query 'Reservations[*].Instances[*].MetadataOptions'
그러면 다음과 유사한 출력이 나타납니다.
[ [{ "State": "applied", "HttpTokens": "optional", "HttpPutResponseHopLimit": 1, "HttpEndpoint": "enabled", "HttpProtocolIpv6": "disabled", "InstanceMetadataTags": "disabled" }] ]
이 출력에서 **"HttpEndpoint": "enabled"**는 인스턴스의 메타데이터가 활성화되었음을 나타냅니다.
메타데이터가 활성화되지 않은 경우 aws ec2 modify-instance-metadata-options 명령을 사용하여 활성화할 수 있습니다. 자세한 내용은 기존 인스턴스의 인스턴스 메타데이터 옵션 수정을 참조하세요.
SSM Agent가 Systems Manager 서비스 엔드포인트에 연결할 수 없음
SSM Agent가 서비스 엔드포인트에 연결할 수 없는 경우 SSM Agent가 실패합니다. SSM Agent는 포트 443에서 다음 Systems Manager 서비스 API 호출과의 아웃바운드 연결을 생성해야 합니다.
- SSM 엔드포인트: ssm.REGION.amazonaws.com
- EC2 메시징 엔드포인트: ec2messages.REGION.amazonaws.com
- SSM 메시징 엔드포인트: ssmmessages.REGION.amazonaws.com
참고: SSM Agent는 인스턴스 메타데이터 서비스에서 검색한 리전 정보를 사용하여 이러한 엔드포인트의 REGION 값을 대체합니다.
SSM Agent가 Systems Manager 엔드포인트와 연결할 수 없는 경우 SSM Agent 로그에 다음과 유사한 오류 메시지가 표시됩니다.
"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 Agent가 포트 443의 Systems Manager API 엔드포인트와 연결할 수 없는 몇 가지 일반적인 이유는 다음과 같습니다.
- 인스턴스 송신 보안 그룹 규칙은 포트 443에서 발신 연결을 허용하지 않습니다.
- Virtual Private Cloud(VPC) 엔드포인트 수신 및 송신 보안 그룹 규칙이 포트 443에서 VPC 인터페이스 엔드포인트에 대한 수신 및 발신 연결을 허용하지 않습니다.
- 인스턴스가 퍼블릭 서브넷에 있을 때 라우팅 테이블 규칙이 인터넷 게이트웨이를 사용하여 트래픽을 전달하도록 구성되지 않았습니다.
- 인스턴스가 프라이빗 서브넷에 있을 때 라우팅 테이블 규칙이 NAT 게이트웨이 또는 VPC 엔드포인트를 사용하여 트래픽을 전달하도록 구성되지 않았습니다.
- 라우팅 테이블 규칙이 모든 발신 연결에 프록시를 사용하도록 구성되었는데 SSM 에이전트는 프록시를 사용하도록 구성되지 않았습니다.
필요한 Systems Manager API 호출을 호출할 수 있는 권한이 SSM Agent에 없음
SSM Agent가 서비스에 대한 UpdateInstanceInformation API 호출을 수행할 권한이 없기 때문에 SSM Agent가 Systems Manager에서 온라인으로 자신을 등록하지 못했습니다.
SSM Agent가 예상대로 작동하고 있음을 서비스에서 알 수 있도록 UpdateInstanceInformation API 호출이 SSM Agent와의 연결을 유지해야 합니다. SSM Agent는 5분마다 클라우드에서 Systems Manager 서비스를 호출하여 상태 확인 정보를 제공하도록 합니다. SSM Agent에 올바른 IAM 권한이 없는 경우 SSM Agent 로그에 오류 메시지가 표시됩니다.
SSM Agent가 잘못된 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 Agent에 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 서비스 핵심 기능을 사용하도록 허용하는 데 필요한 권한이 포함되어 있는지 확인합니다. 또는 인스턴스 프로파일 역할이 아직 연결되어 있지 않은 경우 인스턴스 프로파일 역할을 연결하고 AmazonSSMManagedInstanceCore 권한을 포함시킵니다.
Systems Manager의 필수 IAM 권한에 대한 자세한 내용은 관리형 인스턴스에 대한 추가 정책 고려 사항을 참조하세요.
Systems Manager API 호출 제한
SSM Agent를 실행하는 대량의 관리형 인스턴스가 여러 UpdateInstanceInformation API 호출을 동시에 수행하는 경우 API 호출이 제한될 수 있습니다.
인스턴스에 대한 UpdateInstanceInformation API 호출이 제한될 경우 SSM Agent 로그에 다음과 유사한 오류 메시지가 표시됩니다.
"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 호출에 대한 제한 한도 증가를 요청합니다.
Amazon EC2가 IAM 인스턴스 프로파일의 유효한 보안 인증 정보를 수임할 수 없음
Amazon EC2가 IAM 역할을 수임할 수 없는 경우 SSM Agent 로그에 다음 예와 유사한 메시지가 표시됩니다.
2023-01-25 09:56:19 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:19 INFO [CredentialRefresher] Sleeping for 1s before retrying retrieve credentials 2023-01-25 09:56:20 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:20 INFO [CredentialRefresher] Sleeping for 2s before retrying retrieve credentials 2023-01-25 09:56:22 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:22 INFO [CredentialRefresher] Sleeping for 4s before retrying retrieve credentials 2023-01-25 09:56:26 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:26 INFO [CredentialRefresher] Sleeping for 9s before retrying retrieve credentials 2023-01-25 09:56:35 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:35 INFO [CredentialRefresher] Sleeping for 17s before retrying retrieve credentials 2023-01-25 09:56:52 ERROR [CredentialRefresher] Retrieve credentials produced error: no valid credentials could be retrieved for ec2 identity 2023-01-25 09:56:52 INFO [CredentialRefresher] Sleeping for 37s before retrying retrieve credentials
EC2 인스턴스에서 메타데이터를 검색하려고 하면 다음 예와 유사한 오류도 표시됩니다.
# curl http://169.254.169.254/latest/meta-data/iam/security-credentials/profile-name { "Code" : "AssumeRoleUnauthorizedAccess", "Message" : "EC2 cannot assume the role profile-name. Please see documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-ec2.html#troubleshoot_iam-ec2_errors-info-doc.", "LastUpdated" : "2023-01-25T09:57:56Z" }
참고: 이 예에서 profile-name은 인스턴스 프로파일의 이름입니다.
이 오류를 해결하려면 IAM 역할에 연결된 신뢰 정책을 확인하세요. 정책에서 Amazon EC2를 IAM 역할을 수임할 수 있는 서비스로 지정해야 합니다. UpdateAssumeRolePolicy API를 통해 IAM 정책이 다음 예와 비슷하게 표시되도록 업데이트하세요.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": ["ec2.amazonaws.com"] }, "Action": ["sts:AssumeRole"] } ] }
자세한 내용은 iam/security-credentials/[role-name] 문서에 "Code":"AssumeRoleUnauthorizedAccess"가 표시됨를 참조하세요.
