Session Manager 문제 해결

다음 정보를 사용하면 AWS Systems Manager Session Manager 관련 문제를 해결하는 데 도움이 됩니다.

문서 프로세스가 예기치 않게 실패: 문서 작업자 제한 시간 초과됨

문제: Linux 호스트에 대한 세션을 시작할 때 Systems Manager는 다음 오류를 반환합니다.

document process failed unexpectedly: document worker timed out, 
check [ssm-document-worker]/[ssm-session-worker] log for crash reason

SSM Agent 로그 보기에서 설명한 대로 SSM Agent 로깅을 구성한 경우 디버깅 로그에서 세부 정보를 볼 수 있습니다. 이 문제의 경우 Session Manager에서는 다음 로그 항목을 보여줍니다.

failed to create channel: too many open files

이 오류는 일반적으로 실행 중인 Session Manager 작업자 프로세스가 너무 많고 기본 운영 체제가 한도에 도달했음을 나타냅니다. 이 문제를 해결하기 위한 두 가지 옵션이 있습니다.

해결 방법 A: 운영 체제 파일 알림 한도 증가

별도의 Linux 호스트에서 다음 명령을 실행하여 한도를 늘릴 수 있습니다. 이 명령은 Systems Manager Run Command를 사용합니다. 지정된 값은 max_user_instances에서 8,192로 증가합니다. 이 값은 기본값인 128보다 상당히 높지만 호스트 리소스를 제한하지는 않습니다.

aws ssm send-command --document-name AWS-RunShellScript \
--instance-id i-02573cafcfEXAMPLE  --parameters \
"commands=sudo sysctl fs.inotify.max_user_instances=8192"

솔루션 B: 대상 호스트의 Session Manager에서 사용하는 파일 알림 감소

별도의 Linux 호스트에서 다음 명령을 실행하여 대상 호스트에서 실행되는 세션을 나열합니다.

aws ssm describe-sessions --state Active --filters key=Target,value=i-02573cafcfEXAMPLE

명령 출력을 검토하여 더 이상 필요하지 않은 세션을 식별합니다. 별도의 Linux 호스트에서 다음 명령을 실행하여 해당 세션을 종료할 수 있습니다.

aws ssm terminate-session —session-id session ID

선택적으로 원격 서버에서 더 이상 실행되는 세션이 없으면 별도의 Linux 호스트에서 다음 명령을 실행하여 추가 리소스를 해제할 수 있습니다. 이 명령은 원격 호스트에서 실행되는 모든 Session Manager 프로세스를 종료하고 이후 원격 호스트에 대한 모든 세션을 종료합니다. 이 명령을 실행하기 전에 유지하려는 진행 중인 세션이 없는지 확인합니다.

aws ssm send-command --document-name AWS-RunShellScript \
            --instance-id i-02573cafcfEXAMPLE --parameters \
'{"commands":["sudo kill $(ps aux | grep ssm-session-worker | grep -v grep | awk '"'"'{print $2}'"'"')"]}'

Session Manager는 Amazon EC2 콘솔에서 연결할 수 없습니다.

문제: 새 인스턴스를 생성한 후 Amazon Elastic Compute Cloud(Amazon EC2) 콘솔의 Session Manager 탭에 연결 옵션이 표시되지 않습니다.

솔루션 A: 인스턴스 프로파일 생성: 아직 그렇게(EC2 콘솔의 Session Manager 탭에 있는 정보의 지침대로) 하지 않았다면 Quick Setup을 사용하여 AWS Identity and Access Management(IAM) 인스턴스 프로파일을 생성합니다. Quick Setup은 AWS Systems Manager의 기능입니다.

인스턴스에 연결하려면 IAM 인스턴스 프로파일이 Session Manager에 필요합니다. Quick Setup으로 호스트 관리 구성을 생성하면 인스턴스 프로파일을 생성하여 인스턴스에 할당할 수 있습니다. 호스트 관리 구성에서는 필요한 권한이 있는 인스턴스 프로파일을 생성하여 인스턴스에 할당합니다. 또한 호스트 관리 구성에서는 다른 Systems Manager 기능을 활성화하고 해당 기능을 실행할 IAM 역할을 생성합니다. 호스트 관리 구성을 통해 활성화된 Quick Setup 또는 기능을 사용하는 요금은 없습니다. Quick Setup을 열고 호스트 관리 구성을 생성합니다.

호스트 관리 구성을 생성한 후에도 여전히 연결할 수 없거나 오류(SSM Agent에 대한 오류 포함)가 표시되는 경우 다음과 같은 솔루션 중 하나를 참조하세요.

솔루션 방법 B: 오류가 없으나 여전히 연결할 수 없음

호스트 관리 구성을 생성하고 연결을 시도하기 전에 몇 분 정도 기다렸는데도 연결할 수 없으면 호스트 관리 구성을 인스턴스에 수동으로 적용해야 할 수도 있습니다. 다음 절차를 사용하여 Quick Setup 호스트 관리 구성을 업데이트하고 인스턴스에 변경 사항을 적용합니다.

EC2에서 Session Manager 탭 새로 고침이 진행되는 동안 몇 분 정도 기다립니다. 그래도 연결할 수 없거나 오류가 표시되는 경우 이 문제에 대한 나머지 솔루션을 검토합니다.

솔루션 C: 누락 SSM Agent에 대한 오류

Quick Setup을 사용하여 호스트 관리 구성을 생성할 수 없거나 설치되지 않은 SSM Agent에 대한 오류가 표시되면 인스턴스에 수동으로 SSM Agent를 설치해야 할 수 있습니다. SSM Agent는 Session Manager를 사용하여 인스턴스에 연결하도록 Systems Manager를 활성화하는 Amazon 소프트웨어입니다. SSM Agent는 대부분의 Amazon Machine Image(AMI)에 기본적으로 설치되어 있습니다. 비표준 AMI 또는 오래된 AMI에서 인스턴스를 생성한 경우 에이전트를 수동으로 설치해야 할 수도 있습니다. SSM Agent 설치 절차는 인스턴스 운영 체제에 해당하는 다음 주제를 참조하세요.

SSM Agent 관련 문제는 SSM Agent 문제 해결를 참조하세요.

세션을 시작할 권한 없음

문제: 세션을 시작하려고 했지만 필요한 권한이 없다고 표시됩니다.

SSM Agent가 온라인 상태가 아님

문제: Amazon EC2 인스턴스 Session Manager 탭에 SSM Agent가 온라인 상태가 아니라는 메시지가 표시됩니다. SSM Agent가 서비스에 등록하기 위해 Systems Manager 엔드포인트에 연결하지 못했습니다.

해결 방법: SSM Agent는 Session Manager가 Amazon EC2 인스턴스에 연결할 수 있도록 해당 인스턴스에서 실행되는 Amazon 소프트웨어입니다. 이 오류가 표시되면 SSM Agent가 Systems Manager 엔드포인트와 연결을 설정할 수 없는 것입니다. 문제의 원인은 방화벽 제한, 라우팅 문제 또는 인터넷 연결 부재일 수 있습니다. 이 문제를 해결하려면 네트워크 연결 문제를 조사하세요.

세션 기본 설정을 변경할 권한 없음

문제: 조직에 대한 전역 세션 기본 설정을 업데이트하려고 했는데 필요한 권한이 없다는 메시지가 표시됩니다.

관리형 노드를 사용할 수 없거나 Session Manager에 대해 구성되지 않음

문제 1: 세션 시작(Start a session) 콘솔 페이지에서 세션을 시작하려고 했지만 관리형 노드가 목록에 없습니다.

문제 2: 연결하려는 관리형 노드가 세션 시작(Start a session) 콘솔 페이지의 목록에 있지만 이 페이지에 "선택한 인스턴스가 Session Manager를 사용하도록 구성되지 않았습니다.(The instance you selected isn't configured to use Session Manager.)"라는 메시지가 표시됩니다.

Session Manager 플러그인을 찾을 수 없음

AWS CLI를 사용하여 세션 명령을 실행하려면 Session Manager 플러그인도 로컬 시스템에 설치해야 합니다. 자세한 내용은 AWS CLI의 Session Manager 플러그인 설치을 참조하세요.

명령줄 경로에 자동으로 추가되지 않는 Session Manager 플러그인(Windows)

Windows에 Session Manager 플러그인을 설치하면 session-manager-plugin 실행 파일이 운영 체제의 PATH 환경 변수에 자동으로 추가되어야 합니다. Session Manager 플러그인이 제대로 설치되었는지 확인하기 위해 이 환경 변수를 실행한 후 명령에 실패하면(aws ssm start-session --target instance-id) 다음 절차를 수행하여 수동으로 설정해야 할 수 있습니다.

Session Manager 플러그 인이 응답하지 않음

포트 전달 세션 중에 로컬 컴퓨터에 바이러스 백신 소프트웨어가 설치되어 있는 경우 트래픽 전달을 중지할 수 있습니다. 어떤 경우에는 Session Manager 플러그 인이 포함된 바이러스 백신 소프트웨어가 프로세스 교착 상태를 일으킵니다. 이 문제를 해결하려면 바이러스 백신 소프트웨어에서 Session Manager 플러그 인을 허용하거나 제외합니다. Session Manager 플러그 인의 기본 설치 경로에 대한 자세한 내용은 AWS CLI의 Session Manager 플러그인 설치 섹션을 참조하세요.

TargetNotConnected

문제: 세션을 시작하려고 하지만 시스템에서 “StartSession 작업을 호출할 때 (targetNotConnected) 오류가 발생했습니다. InstanceID가 연결되어 있지 않습니다.(An error occurred (TargetNotConnected) when calling the StartSession operation: InstanceID isn't connected.)” 오류 메시지를 반환합니다.

세션 시작 후 빈 화면 표시

문제: 세션을 시작하면 Session Manager에 빈 화면이 표시됩니다.

장기 실행 세션 동안 관리형 노드가 응답하지 않음

문제: 장기 실행 세션 중에 관리형 노드가 응답하지 않거나 충돌합니다.

해결 방법: Session Manager에 대한 SSM Agent 로그 보존 기간을 줄입니다.

StartSession 작업을 호출할 때 오류가 발생합니다(InvalidDocument)

문제: AWS CLI을(를) 사용하여 세션을 시작할 때 다음 오류가 발생합니다.

An error occurred (InvalidDocument) when calling the StartSession operation: Document type: 'Command' is not supported. Only type: 'Session' is supported for Session Manager.

해결 방법: --document-name 파라미터에 지정한 SSM 문서는 세션 문서가 아닙니다. 다음 절차에 따라 AWS Management Console에서 세션 문서의 목록을 봅니다.