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

7분 분량

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 Agent를 구성하지 않고 인스턴스의 아웃바운드 인터넷 연결용 프록시를 사용하기 때문입니다. 프록시를 사용하도록 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 Agent는 프록시를 사용하도록 구성되지 않습니다.

SSM Agent는 필수 Systems Manager API 직접 호출을 호출할 권한이 없습니다.

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

UpdateInstanceInformation API 직접 호출은 SSM Agent가 예상대로 작동하고 있음을 서비스에서 알 수 있도록 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를 동시에 호출하면 해당 호출이 제한될 수 있습니다.

인스턴스에 대한 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"가 표시됩니다를 참조하세요.

주제

관리 및 거버넌스

태그

AWS Systems Manager

언어

한국어

AWS 공식업데이트됨 일 년 전

댓글 없음