Image Builder에서 “Step timed out while step is verifying the Systems Manager Agent availability on the target instance(s)”(대상 인스턴스에서 Systems Manager Agent 가용성 확인 단계 시간 초과) 오류와 함께 내 이미지 빌드 파이프라인이 실패하는 이유는 무엇입니까?

간략한 설명

EC2 Image Builder는 AWS Systems Manager Automation을 사용하여 사용자 지정 이미지를 빌드합니다. 이미지를 빌드하고 테스트를 실행하는 데 사용되는 Amazon EC2 인스턴스가 AWS Systems Manager 서비스에 액세스할 수 있는지 확인합니다.

failure message = 'Step timed out while step is verifying the SSM Agent availability on the target instance(s)' 오류 메시지는 다음과 같은 이유로 인해 발생할 수 있습니다.

• 빌드 또는 테스트 인스턴스가 Systems Manager 엔드포인트에 액세스할 수 없습니다. 이 문제를 해결하려면 보안 그룹 및 네트워크 액세스 제어 목록(네트워크 ACL)에 대한 인바운드 및 아웃바운드 규칙을 확인하세요.
• 인스턴스 프로파일에 필요한 권한이 없습니다. 이 문제를 해결하려면 인스턴스 프로파일에 올바른 정책이 연결되어 있는지 확인합니다.
• 인스턴스가 인스턴스 메타데이터 서비스(IMDS)에 연결할 수 없습니다. 이 문제를 해결하려면 인스턴스가 IMDS에 연결할 수 있는지 확인하세요.
• AWS Systems Manager Agent(SSM Agent)가 기본 이미지에 설치되어 있지 않습니다.

해결 방법

보안 그룹 및 네트워크 ACL에 대한 아웃바운드 및 인바운드 규칙 확인

빌드 또는 테스트 인스턴스가 Systems Manager 엔드포인트에 액세스할 수 없는 경우 다음을 확인하세요.

• 보안 그룹의 경우 포트 443의 아웃바운드가 열려 있습니다.
• 네트워크 ACL의 경우 임시 포트(1024~65535)의 인바운드가 열려 있고 포트 443의 아웃바운드가 열려 있습니다.

퍼블릭 서브넷 빌드의 경우:

• 서브넷에서 퍼블릭 IPv4 주소 자동 할당 활성화(Enable auto-assign public IPv4 address)가 활성화되어 있어야 합니다.
• 라우팅 테이블에는 인터넷 게이트웨이가 연결되어 있어야 합니다.

프라이빗 서브넷 빌드의 경우:

• 라우팅 테이블에는 NAT 게이트웨이나 인스턴스, 또는 System Manager(ssm, ssmmessages, ec2messages) 및 Image Builder에 대한 AWS PrivateLink 엔드포인트가 있어야 합니다. 로깅이 활성화된 경우 라우팅 테이블에도 Amazon Simple Storage Service(Amazon S3) 또는 Amazon CloudWatch에 대한 엔드포인트가 있어야 합니다.
• Amazon Virtual Private Cloud(VPC) 엔드포인트의 보안 그룹은 포트 443에서 VPC CIDR로의 인바운드 트래픽을 허용해야 합니다.

인스턴스 프로파일에 올바른 정책이 있는지 확인

인스턴스 프로파일은 인프라 구성에 정의된 AWS Identity and Access Management(IAM) 역할입니다. 필요한 권한이 없으면 빌드가 실패합니다. 이미지 빌드 권한을 가지려면 인스턴스 프로파일에 다음과 같은 관리형 정책이 연결되어 있어야 합니다.

• EC2InstanceProfileForImageBuilder
• EC2InstanceProfileForImageBuilderECRContainerBuilds(도커 이미지용)
• AmazonSSMManagedInstanceCore

이전 관리형 정책과 유사한 권한을 가진 사용자 지정 정책을 생성할 수도 있습니다.

참고: 역할의 신뢰 정책을 확인하여 ec2.amazonaws.com이 역할을 수임할 수 있는지 확인합니다.

인스턴스가 IMDS에 연결할 수 있는지 확인

IMDS는 실행 중인 인스턴스에서 메타데이터에 액세스하는 데 사용됩니다. 인스턴스가 IMDS에 연결할 수 없는 경우 빌드가 실패합니다. 인스턴스가 IMDS에 연결할 수 있도록 운영 체제(OS)의 방화벽이 포트 80에서 트래픽 169.254.169.254를 허용하는지 확인하세요.

다음 명령을 실행하여 연결성을 테스트합니다.

$ telnet 169.254.169.254 80

프록시를 사용하는 경우, 프록시와 함께 작동하도록 SSM 에이전트를 구성합니다. Linux의 경우, 프록시를 사용하도록 SSM Agent 구성(Linux)을 참조하세요. 자세한 내용은 Windows Server 인스턴스에 프록시를 사용하도록 SSM Agent 구성을 참조하세요.

SSM Agent가 기본 이미지에 설치되어 있는지 확인

Image Builder가 이미지를 구축하고 테스트를 실행하는 데 사용하는 인스턴스에는 Systems Manager Agent가 설치되어 있어야 합니다.

Linux

SSM Agent가 없는 Amazon EC2 Linux 인스턴스의 경우 Image Builder는 기본적으로 빌드 인스턴스에 SSM Agent를 설치합니다. 하지만 레시피에 사용자 데이터를 제공하는 경우에는 SSM Agent가 기본 이미지에 설치되어 있는지 확인해야 합니다. 또는 사용자 데이터 입력으로 SSM Agent를 설치합니다.

Windows

Image Builder는 윈도우 서버용 Amazon EC2 빌드 인스턴스에 SSM Agent를 설치하지 않습니다. SSM Agent가 기본 이미지에 사전 설치되어 있는지 확인하려면 기본 이미지를 사용하여 EC2 인스턴스를 시작합니다. 그런 다음 PowerShell에서 다음 명령을 실행합니다.

Get-Service AmazonSSMAgent

SSM Agent가 기본 이미지에 사전 설치되어 있지 않은 경우 소스 이미지에서 인스턴스를 시작해야 합니다. 다음으로 EC2 인스턴스에 SSM Agent를 수동으로 설치한 다음 인스턴스에서 새 기본 이미지를 생성합니다.

‘장애 시 인스턴스 종료(Terminate instance on failure)’ 비활성화

위의 해결 방법으로도 문제가 해결되지 않으면 다음을 수행합니다.

1.    EC2 Image Builder 콘솔을 엽니다.

2.    **인프라 구성(Infrastructure configuration)**에서 **장애 시 인스턴스 종료(Terminate instance on failure)**를 활성화하고 파이프라인을 다시 실행합니다.

3.    인스턴스에 연결하고 다음 명령을 실행하여 Systems Manager 엔드포인트에 대한 연결을 확인합니다.

Linux 인스턴스

$ curl -v https://ssm.region.amazonaws.com

$ curl -v https://ec2messages.region.amazonaws.com

$ curl -v https://ssmmessages.region.amazonaws.com

Windows 인스턴스

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

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

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

참고: region을 사용자의 AWS 리전으로 바꿉니다.

4.    다음 경로를 사용하여 SSM 로그에서 실패나 오류를 확인합니다.

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

---