Amazon EC2 Windows 인스턴스에서 SSM Agent를 시작할 수 없는 이유는 무엇입니까?

해결 방법

참고: EC2 인스턴스에 관리형 노드에 필요한 구성이 있는지 확인하려면 ssm-cli 버전 3.1.501.0 이상을 사용하는 것이 모범 사례입니다. 자세한 내용은 ssm-cli를 사용하여 관리형 노드 가용성 문제 해결을 참조하십시오.

IAM 역할에 필요한 권한이 있는지 확인

인스턴스의 AWS Identity and Access Management(IAM) 역할에는 AWS Systems Manager 엔드포인트에 대한 API 직접 호출을 수행하는 데 필요한 권한이 있어야 합니다. AmazonSSMManagedInstanceCore 정책을 역할에 연결하거나 사용자 지정 정책에 AmazonSSMManagedInstanceCore에 나열된 모든 권한이 포함되어 있는지 확인하십시오.

또한 역할의 신뢰 정책에서 ec2.amazonaws.com이 역할을 수임할 수 있도록 허용하는지 확인하십시오.

신뢰 정책 예시:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com",
                    "ssm.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

SSM Agent가 인스턴스의 메타데이터에 액세스할 수 있는지 확인

SSM Agent는 인스턴스의 메타데이터 서비스와 통신하여 인스턴스에 대한 필수 정보를 가져와야 합니다. 인스턴스의 메타데이터에 액세스하려면 실행 중인 인스턴스 내에서 브라우저를 사용하십시오.

인스턴스 메타데이터 서비스 버전 2(IMDSv2)를 사용하는 경우 운영 체제(OS)에 따라 다음 명령을 실행합니다.

Linux:

TOKEN=curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" \
    && curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/

Windows:

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/

참고: 자세한 내용은 인스턴스 메타데이터 서비스 버전 2의 작동 방식을 참조하십시오.

메타데이터에 액세스할 수 없는 경우 Windows PowerShell 또는 명령 프롬프트에서 다음 명령을 실행합니다.

route print

출력에서 169.254.169.254에 대한 경로가 있는지 확인합니다.

출력 예시:

Persistent Routes:     
Network Address     Netmask             Gateway Address     Metric  
169.254.169.254     255.255.255.255     172.31.16.1         15  
169.254.169.250     255.255.255.255     172.31.16.1         15  
169.254.169.251     255.255.255.255     172.31.16.1         15  
169.254.169.249     255.255.255.255     172.31.16.1         15  
169.254.169.123     255.255.255.255     172.31.16.1         15  
169.254.169.253     255.255.255.255     172.31.16.1         15

경로가 없거나 게이트웨이 주소가 현재 서브넷과 일치하지 않으면 다음 작업 중 하나를 수행하십시오.

• 다음 명령을 실행하여 경로를 수동으로 추가합니다.

  route add -p 169.254.169.254 mask 255.255.255.255 0.0.0.0

  참고: 0.0.0.0을 인스턴스의 게이트웨이 주소로 바꾸십시오.

• 인스턴스가 EC2Launch v1을 사용하는 경우 관리자 권한으로 실행된 Windows PowerShell 세션에서 다음 명령을 실행하여 메타데이터 경로를 추가합니다.

  import-Module c:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psm1 ; Add-Routes

• 인스턴스가 EC2Launch v2 또는 EC2Config를 사용하는 경우 다음 명령을 실행하여 서비스를 재시작합니다.

  Restart-Service -Name EC2Launch

  참고: 위 명령은 메타데이터 서비스에 도달하기 위한 비영구 정적 경로를 설정합니다.

경로가 존재하는데 인스턴스가 메타데이터를 검색할 수 없는 경우 인스턴스의 방화벽 또는 바이러스 백신 구성이 169.254.169.254에 대한 트래픽을 명시적으로 거부하지 않는지 확인하십시오. 자세한 내용은 Amazon EC2 Windows 인스턴스의 "Waiting for the metadata service" 오류를 어떻게 해결합니까?를 참조하십시오.

인스턴스가 필요한 엔드포인트에 연결할 수 있는지 확인

인스턴스가 포트 443에서 Systems Manager 엔드포인트에 연결할 수 있는지 확인하려면 다음 Windows PowerShell 명령을 실행합니다.

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

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

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

참고: RegionID를 인스턴스의 AWS 리전으로 바꾸십시오.

인스턴스가 포트 443에서 연결할 수 없는 경우 인스턴스가 속한 서브넷 유형에 따라 다음 작업을 수행하십시오.

퍼블릭 서브넷

Systems Manager에는 퍼블릭 엔드포인트가 있으므로 인스턴스가 인터넷에 연결하려면 인터넷 게이트웨이를 사용해야 합니다. 인스턴스의 라우팅 테이블에 인터넷 경로가 포함되어 있는지 확인하십시오. 또한 Amazon Virtual Private Cloud(Amazon VPC) 보안 그룹 및 네트워크 액세스 제어 목록(네트워크 ACL)이 포트 443에서 아웃바운드 연결을 허용하는지 확인합니다.

프라이빗 서브넷

프라이빗 서브넷의 경우 인스턴스가 NAT 게이트웨이를 사용하여 인터넷에 연결해야 합니다. 또는 Systems Manager 엔드포인트에 도달하도록 Amazon VPC 엔드포인트를 구성해야 합니다.

네트워크 구성 요구 사항에 대한 자세한 내용은 Systems Manager에서 Amazon EC2 인스턴스를 관리형 인스턴스로 표시하지 않는 이유는 무엇입니까?를 참조하십시오.

프록시 설정 확인

프록시를 사용하는 경우 SSM Agent를 시작할 때 Systems Manager가 프록시 설정을 평가하여 에이전트 구성에 적용합니다. 프록시를 사용하도록 SSM Agent를 올바르게 구성했는지 확인하십시오.

SSM Agent 업그레이드

최신 SSM Agent 버전을 다운로드하여 설치하는 것이 모범 사례입니다. 최신 SSM Agent 버전을 확인하려면 GitHub 웹 사이트에서 aws/amazon-ssm-agent Releases를 참조하십시오.

추가 문제 해결

인스턴스가 여전히 에이전트를 시작할 수 없는 경우 SSM Agent 로그를 보고 해결해야 하는 오류를 식별하십시오.