SSM Agent 문서 워커 시간 초과 오류를 어떻게 해결합니까?

간략한 설명

다음 AWS Systems Manager 기능을 사용하면 Systems Manager 명령이 대상 Amazon Elastic Compute Cloud(Amazon EC2) 인스턴스에서 실패할 수 있습니다.

• Run Command
• 연결
• 자동화
• Session Manager

다음 예시 메시지와 비슷한 오류 메시지가 표시되면 Systems Manager 명령이 실패했다는 뜻입니다.

‘document process failed unexpectedly: document worker timed out; check 12345678-abcd-1234-efgh-123456789012 log for crash reason.’

참고: 이전 오류 메시지 예시에서 자리 표시자 값 12345678-abcd-1234-efgh-123456789012는 실제 ssm-document-worker 또는 ssm-session-worker ID 번호를 나타냅니다.

이 오류를 해결하려면 다음 문제를 해결하십시오.

• 리소스 부족 문제
• 메모리 부족 문제
• 인스턴스의 디스크 공간 부족
• ‘Too many open files’ 오류

해결 방법

전제 조건: SSM Agent를 최신 버전으로 업데이트해야 합니다.

참고: GitHub 웹 사이트에서 amazon-ssm-agent/RELEASE NOTES를 구독하여 SSM Agent 업데이트에 관한 알림을 받을 수 있습니다.

오류를 초래하는 문제가 무엇인지 알아보려면 SSM Agent 로그를 봅니다. 그런 다음, 파악한 문제점별로 다음 섹션의 단계를 따라 문제 해결을 완료합니다.

리소스 부족 문제 해결

세션에서 리소스 제한 문제가 발생하면(예: 인스턴스가 사용 가능한 메모리 또는 디스크 공간을 초과함) 대상 인스턴스가 있는 세션이 충돌할 수 있습니다. 리소스 제한은 SSM Agent가 올바로 작동하지 못하게 합니다. 이 문제를 해결하려면 인스턴스에 대상 인스턴스에서 실행되는 워크로드를 관리하는 데 충분한 메모리 및 디스크 공간이 있는지 확인합니다.

메모리 부족 오류 해결

인스턴스의 프로세스가 사용 가능한 메모리를 모두 사용해서 프로그램 또는 운영 체제가 공간을 할당할 수 없으면 인스턴스가 추가적인 프로그램을 로드할 수 없습니다. 그러면 프로세스가 응답을 멈추고, 운영 체제는 우선순위가 낮은 프로세스를 종료합니다.

이 문제를 해결하려면 연결할 수 없는 인스턴스 문제 해결을 참조하십시오. Linux OOM 문제는 메모리 부족: 프로세스 종료를 참조하십시오.

인스턴스의 디스크 공간 부족 문제 해결

데이터를 작성하거나 파일을 저장하려 하는데 Linux 인스턴스에 가용 스토리지가 부족하면 인스턴스에서 디스크 공간 부족 오류가 발생합니다. 이 문제를 해결하려면 다음 작업을 수행하십시오.

• 파티션에서 대량의 디스크 공간을 사용하는 파일이 무엇이지 파악합니다.
• 불필요한 파일을 삭제하거나 데이터를 이동하여 파티션에서 여유 공간을 확보합니다.
• /var/lib/amazon/ssm의 Systems Manager 오케스트레이션 폴더를 포함해 작업 중인 디렉터리에 공간이 충분한지 확인합니다.
• 볼륨 크기를 늘립니다. 자세한 지침은 파일 시스템에 남은 공간이 없다는 오류가 표시되는 경우, EBS 볼륨의 크기를 늘리려면 어떻게 해야 합니까?를 참조하십시오.

‘too many open files’ 오류 해결

SSM Agent 워커 프로세스가 실패해서 Linux 인스턴스가 Systems Manager Run Command 처리를 중지하는 경우, ‘too many open files’ 오류가 발생합니다. 인스턴스가 파일을 너무 많이 열면 SSM Agent가 명령 프로세서를 시작할 수 없고, 이 오류를 SSM Agent 로그에 보고합니다. 이 오류는 다음과 같은 상황에서 발생합니다.

• SSM Agent 프로세스가 운영 체제 사용자 계정에서 허용된 최대 열린 파일 수에 도달했습니다.
• 시스템에서 열린 파일의 총 수가 시스템 전체의 최대 열린 파일 수 제한에 도달했습니다.
• 시스템이 파일 시스템 변경을 모니터링하는 커널의 inofy 감시 한도에 도달했습니다.

이 문제를 해결하려면 다음 단계를 완료하십시오.

1. SSM Agent 프로세스의 PID를 확인합니다.

   sudo ps -C amazon-ssm-agent -o pid=

   참고: 다음 단계의 명령에서 PID를 이 명령이 반환하는 프로세스 ID로 바꾸십시오.

2. SSM Agent 프로세스의 파일 설명자 한도를 확인합니다. 첫 번째 숫자는 소프트 한도(현재 적용된 한도)를 나타내고, 두 번째 숫자는 하드 한도(소프트 한도가 도달할 수 있는 최대값)를 나타냅니다.

   sudo cat /proc/PID/limits |grep "Max open files"

3. SSM Agent 프로세스의 열린 파일 전체 수 확인:

   sudo lsof -p PID |wc -l

4. 열린 파일 전체 수(3단계)를 하드 한도(2단계)와 비교합니다. 열린 파일 전체 수가 하드 한도와 가까우면 시스템이 새 파일을 열 수 없습니다.

이 문제를 해결하려면 SSM Agent 서비스 구성 파일에서 하드 한도 값을 늘린 다음 SSM Agent를 다시 시작하십시오.

하드 한도를 늘릴 때 동시 사용자 수, 네트워크 연결 수 및 파일 작업 수 등 인스턴스의 워크로드 요구 사항을 고려하십시오. Linux 배포는 우발적인 리소스 소진을 예방하기 위해 기본 하드 한도를 설정합니다.

하드 한도를 업데이트하려면 운영 체제에 따라 다음 작업을 완료하십시오.

Amazon Linux 1, Ubuntu 14.04 및 Ubuntu 16.04(.deb 패키지 포함)의 경우 다음 명령을 실행합니다.

echo "limit nofile example-hard-limit" >> /etc/init/amazon-ssm-agent.override

Amazon Linux 2, RHEL 7.x 및 RHEL 8.x/의 경우 다음 명령을 실행합니다.

sudo systemctl edit amazon-ssm-agent

그런 다음, 편집기가 열리면 파일에 다음 코드를 추가하십시오.

[Service]
LimitNOFILE=example-hard-limit

Ubuntu 22.04 LTS, 20.10 STR 및 20.04, 18.04의 경우 다음 명령을 실행합니다.

sudo systemctl edit snap.amazon-ssm-agent.amazon-ssm-agent

그런 다음, 편집기가 열리면 파일에 다음 코드를 추가하십시오.

[Service]
LimitNOFILE=example-hard-limit

참고: 이전 명령에서 example-hard-limit를 업데이트된 값으로 바꾸십시오.

새 하드 한도의 스트레스 테스트를 실시해야 합니다. 새 하드 한도를 모니터링하여 새 하드 한도 때문에 다른 문제가 생기면 조정하십시오.

워커 로그 확인

문서 워커 시간 초과 오류의 근본 원인을 알아보려면 SSM Agent 로그와 인스턴스의 OS 수준 로그를 검토하십시오.

OS에 따라 다음 위치에서 SSM Agent와 관련된 오류 메시지, 충돌 보고서 또는 커널 문제에 대한 OS 수준 로그를 확인하십시오.

• Windows의 경우:
  C:\Windows\System32\winevt\Logs
• Ubuntu 및 Debian의 경우:
  /var/log/syslog
• Amazon Linux, CentOS 및 RHEL의 경우:
  /var/log/messages
• Suse의 경우:
  /var/log/messages

더 자세한 문제 해결을 위해 디버그 로깅을 활성화해야 하는 경우, SSM Agent 디버그 로깅 허용를 참조하십시오.

참고: SSM Agent 디버그 로깅은 시스템 스토리지에 영향을 미칠 수 있는 대량의 로그 데이터를 생성합니다. 문제 해결을 마친 후에는 디버그 로깅을 비활성화하는 것이 좋습니다.

관련 정보

SSM Agent 문제 해결