Systems Manager Agent가 시작 상태에서 멈추거나 시작하지 못하는 문제를 해결하려면 어떻게 해야 하나요?

6분 분량

AWS Systems Manager Agent(SSM Agent)가 시작 상태에서 멈추거나 시작하지 못하는 이유를 해결하고 싶습니다.

간략한 설명

관리형 인스턴스는 시스템 관리자와 함께 사용하도록 구성된 Amazon EC2 인스턴스입니다. 관리형 인스턴스는 실행 명령, 패치 관리자, 세션 관리자와 같은 시스템 관리자 서비스를 사용할 수 있습니다.

관리형 인스턴스가 되려면 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스가 다음 사전 요구 사항을 충족하는지 확인하세요.

인스턴스에 SSM 에이전트가 설치되어 실행 중입니다.
인스턴스가 인스턴스 메타데이터 서비스에 연결되어 있습니다.
인스턴스가 SSM 에이전트를 사용하여 시스템 관리자 엔드포인트와 연결되어 있습니다.
인스턴스에 올바른 AWS IAM(신원 및 액세스 관리) 역할이 연결되어 있습니다.

이러한 필수 구성 요소가 충족되지 않으면 SSM 에이전트가 시작되지 않습니다.

SSM 에이전트 버전 3.1.501.0 이상의 경우, ssm-cli 도구를 사용하여 인스턴스가 이러한 요구 사항을 충족하는지 확인할 수 있습니다. 이 도구를 사용하면 실행 중인 EC2 인스턴스가 시스템 관리자의 관리되는 인스턴스 목록에 포함되지 않는 이유를 진단할 수 있습니다.

인스턴스가 시스템 관리자 콘솔에 관리되는 인스턴스로 나타나지 않는 경우, SSM 에이전트 로그를 확인하여 추가 문제를 해결하세요.

Linux용 SSM 에이전트 로그는 /var/log/amazon/ssm에서 찾을 수 있습니다.
%PROGRAMDATA%\Amazon\SSM\Logs에서 Windows용 SSM 에이전트 로그를 찾을 수 있습니다.

참고: 인스턴스가 시스템 관리자에 보고하지 않는 경우 RDP(Windows) 또는 SSH(Linux)를 사용하여 로그인하여 로그를 수집해 보세요. 그래도 로그인할 수 없으면 인스턴스를 중지하고 루트 볼륨을 분리합니다. 그런 다음 루트 볼륨을 보조 볼륨과 동일한 가용성 영역에 있는 다른 인스턴스에 연결하여 로그를 가져옵니다.

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 최신 AWS CLI 버전을 사용하고 있는지 확인합니다.

인스턴스 메타데이터 서비스에 대한 연결 확인

참고: 이 연결은 하이브리드 활성화가 아닌 EC2 인스턴스에만 필요합니다.

SSM 에이전트가 올바르게 작동하려면 EC2 인스턴스 메타데이터에 의존합니다. SSM 에이전트는 IMDSv1(인스턴스 메타데이터 서비스 버전 1) 또는 IMDSv2(인스턴스 메타데이터 서비스 버전 2)를 사용하여 인스턴스 메타데이터에 액세스할 수 있습니다. 인스턴스가 인스턴스 메타데이터 서비스의 IPv4 주소에 액세스할 수 있는지 확인하세요. 169.254.169.254.

인스턴스 메타데이터 서비스에 대한 연결을 확인하려면 EC2 인스턴스에서 다음 명령을 실행합니다.

Linux:

telnet 169.254.169.254 80
or
curl -I http://169.254.169.254/latest/meta-data/

Windows:

curl http://169.254.169.254/latest/meta-data/  
or
Test-NetConnection 169.254.169.254  -port 80

인스턴스에서 메타데이터에 액세스할 수 없는 경우, 메타데이터가 켜져 있는지 확인하세요.

기존 EC2 인스턴스의 경우 다음을 수행하여 메타데이터가 켜져 있는지 확인합니다.

Amazon EC2 콘솔을 엽니다.
탐색 창에서 인스턴스를 선택합니다.
본인의 인스턴스를 선택합니다.
작업, 인스턴스 설정, 인스턴스 메타데이터 옵션 수정을 선택합니다.
인스턴스 메타데이터 옵션 수정 대화 상자에서 인스턴스 메타데이터 서비스가 활성화되어 있는지 확인합니다.

또는 describe-instances 명령을 사용하여 인스턴스 메타데이터 서비스가 켜져 있는지 확인합니다:

aws ec2 describe-instances --query "Reservations[*].Instances[*].MetadataOptions" --instance-ids i-012345678910

출력은 다음과 같습니다.

[
  [
    {
      "State": "applied",
      "HttpTokens": "optional",
      "HttpPutResponseHopLimit": 1,
      "HttpEndpoint": "enabled",
      "HttpProtocolIpv6": "disabled",
      "InstanceMetadataTags": "disabled"
    }
  ]
]

앞의 출력에서 HttpEndpoint 필드는 메타데이터가 켜져 있는지 여부를 나타냅니다.

메타데이터 액세스가 꺼져 있으면 켭니다.

인스턴스에 프록시가 구성된 경우 인스턴스가 메타데이터 IP(169.254.169.254)를 우회하는지 확인하세요. 자세한 내용은 다음 사용 가이드를 참조하세요.

Linux: 프록시를 사용하도록 SSM 에이전트 구성하기(Linux)

Windows: Windows Server 인스턴스에 프록시를 사용하도록 SSM 에이전트 구성

Windows의 경우 메타데이터에 대한 특정 경로(169.254.169.254)를 확인합니다.

PowerShell에서 route print 및 ipconfig /all 명령을 실행합니다. 그런 다음 메타데이터 출력을 확인합니다.

    Network Address        Netmask             Gateway Address
    169.254.169.254        255.255.255.255     <Subnet Router Address>

출력의 게이트웨이 주소 필드가 인스턴스의 기본 네트워크 인터페이스에 대한 기본 게이트웨이와 일치하는지 확인합니다.

경로가 없거나 게이트웨이 주소 필드가 일치하지 않으면 다음을 수행합니다.

인스턴스에 최신 버전의 EC2Config(Windows Server 2012R2 이하) 또는 EC2Launch(Windows Server 2016 이상)가 설치되어 있는지 확인합니다.
인스턴스에 경로를 적용하려면 EC2Config 서비스를 다시 시작합니다.
경로가 올바르지만 인스턴스에서 여전히 메타데이터를 검색할 수 없는 경우 인스턴스의 Windows 방화벽, 타사 방화벽 및 바이러스 백신 구성을 검토하세요. 169.254.169.254에 대한 트래픽이 명시적으로 거부되지 않았는지 확인합니다.

메타데이터 경로를 수동으로 재설정하려면 다음과 같이 하세요.

참고: 이렇게 구성된 변경 사항은 즉시 적용됩니다. 변경 사항을 적용하기 위해 인스턴스를 다시 시작할 필요가 없습니다.

다음 명령을 실행하여 라우팅 테이블에서 기존 메타데이터 경로를 제거합니다.

route delete 169.254.169.123
route delete 169.254.169.249
route delete 169.254.169.250
route delete 169.254.169.251
route delete 169.254.169.252
route delete 169.254.169.253
route delete 169.254.169.254

다음 명령을 실행합니다.
```
ipconfig /all
```
2단계의 명령에서 반환된 기본 게이트웨이 IP에 유의하세요.

다음 명령을 실행합니다. DefaultGatewayIP를 3단계에서 검색한 IP 주소로 바꿉니다.

route -p add 169.254.169.123 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.249 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.250 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.251 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.252 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.253 MASK 255.255.255.255 DefaultGatewayIP
route -p add 169.254.169.254 MASK 255.255.255.255 DefaultGatewayIP

SSM 에이전트를 다시 시작합니다.

Systems Manager 엔드포인트와의 연결 확인

이 연결을 확인하는 가장 좋은 방법은 운영 체제에 따라 다릅니다. 리전별 Systems Manager 엔드포인트 목록은 AWS Systems Manager 엔드포인트 및 할당량을 참고하세요.

참고: 다음 예에서 ssmmessages 엔드포인트는 AWS Systems Manager Session Manager에 대해서만 필요합니다.

EC2 Linux 인스턴스의 경우 telnet 또는 netcat 명령을 실행하여 포트 443의 엔드포인트에 대한 연결을 확인합니다.

Telnet

telnet ssm.RegionID.amazonaws.com 443
telnet ec2messages.RegionID.amazonaws.com 443
telnet ssmmessages.RegionID.amazonaws.com 443

RegionID를 AWS Region ID로 바꾸어야 합니다.

연결에 성공하면 다음과 비슷한 출력이 표시됩니다.

root@111800186:~# telnet ssm.us-east-1.amazonaws.com 443
Trying 52.46.141.158...
Connected to ssm.us-east-1.amazonaws.com.
Escape character is '^]'.
To exit from telnet, hold down the Ctrl key and press the ] key. Enter quit, and then press Enter.

Netcat

nc -vz ssm.RegionID.amazonaws.com 443
nc -vz ec2messages.RegionID.amazonaws.com 443
nc -vz ssmmessages.RegionID.amazonaws.com 443

참고: Netcat이 Amazon EC2 인스턴스에 사전 설치되어 있지 않습니다. Netcat을 수동으로 설치하려면 Nmap 웹 사이트에서 Ncat을 참조하세요.

EC2 Windows 인스턴스의 경우, 다음 Windows PowerShell 명령을 실행하여 포트 443의 엔드포인트에 대한 연결을 확인합니다.

Test-NetConnection ssm.RegionID.amazonaws.com -port 443
Test-NetConnection ec2messages.RegionID.amazonaws.com -port 443
Test-NetConnection ssmmessages.RegionID.amazonaws.com -port 443

연결에 성공하면 다음과 비슷한 출력이 표시됩니다.

PS C:\Users\ec2-user> Test-NetConnection ssm.us-east-1.amazonaws.com -port 443
ComputerName     : ssm.us-east-1.amazonaws.com
RemoteAddress    : 52.46.145.233
RemotePort       : 443
InterfaceAlias   : Ethernet
SourceAddress    : 10.35.218.225
TcpTestSucceeded : True

SSM 에이전트에 대한 IAM 역할 확인

SSM 에이전트가 시스템 관리자 API를 호출하려면 특정 IAM 권한이 필요합니다. 다음 방법 중 하나를 사용하여 이러한 권한을 관리할 수 있습니다.

기본 호스트 관리 구성을 사용하면 시스템 관리자가 Amazon EC2 인스턴스를 자동으로 관리할 수 있습니다. 이 구성을 사용하면 인스턴스 프로파일을 사용하지 않고도 인스턴스를 관리할 수 있습니다. 이 구성을 사용하면 시스템 관리자가 리전 및 계정의 모든 인스턴스를 관리할 수 있는 권한을 갖도록 합니다.
IAM 인스턴스 프로파일을 사용하여 인스턴스 수준에서 액세스 권한을 부여할 수 있습니다. 인스턴스 프로파일은 시작 시 인스턴스에 IAM 역할 정보를 전달하는 컨테이너입니다. 자세한 내용은 대체 구성을 참조하세요.

Systems Manager Agent가 시작 상태에서 멈추거나 시작하지 못하는 문제를 해결하려면 어떻게 해야 하나요?

간략한 설명

최신 버전의 SSM 에이전트를 설치했는지 확인합니다.

인스턴스 메타데이터 서비스에 대한 연결 확인

Systems Manager 엔드포인트와의 연결 확인

SSM 에이전트에 대한 IAM 역할 확인

관련 정보

관련 콘텐츠