Session Manager 문제 해결
다음 정보를 사용하면 AWS Systems Manager Session Manager 관련 문제를 해결하는 데 도움이 됩니다.
주제
- Session Manager는 Amazon EC2 콘솔에서 연결할 수 없습니다.
- 세션을 시작할 권한 없음
- SSM Agent가 온라인 상태가 아님
- 세션 기본 설정을 변경할 권한 없음
- 관리형 노드를 사용할 수 없거나 Session Manager에 대해 구성되지 않음
- Session Manager 플러그인을 찾을 수 없음
- 명령줄 경로에 자동으로 추가되지 않는 Session Manager 플러그인(Windows)
- Session Manager 플러그 인이 응답하지 않음
- TargetNotConnected
- 세션 시작 후 빈 화면 표시
- 장기 실행 세션 동안 관리형 노드가 응답하지 않음
- StartSession 작업을 호출할 때 오류가 발생합니다(InvalidDocument)
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을 열고 호스트 관리 구성을 생성합니다
중요
호스트 관리 구성을 생성한 후 Amazon EC2에서 변경 사항을 등록하고 Session Manager 탭을 새로 고치는 데 몇 분 정도 걸릴 수 있습니다. 2분 후에도 탭에 연결 버튼이 표시되지 않으면 인스턴스를 재부팅 해보세요. 재부팅 후에도 연결 옵션이 표시되지 않으면 빠른 설정을
호스트 관리 구성을 생성한 후에도 여전히 연결할 수 없거나 오류(SSM Agent에 대한 오류 포함)가 표시되는 경우 다음과 같은 솔루션 중 하나를 참조하세요.
솔루션 방법 B: 오류가 없으나 여전히 연결할 수 없음
호스트 관리 구성을 생성하고 연결을 시도하기 전에 몇 분 정도 기다렸는데도 연결할 수 없으면 호스트 관리 구성을 인스턴스에 수동으로 적용해야 할 수도 있습니다. 다음 절차를 사용하여 Quick Setup 호스트 관리 구성을 업데이트하고 인스턴스에 변경 사항을 적용합니다.
Quick Setup을 사용하여 호스트 관리 구성을 업데이트하는 방법
AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/
)을 엽니다. 탐색 창에서 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 문제 해결를 참조하세요.
세션을 시작할 권한 없음
문제: 세션을 시작하려고 했지만 필요한 권한이 없다고 표시됩니다.
-
해결 방법: 시스템 관리자가 Session Manager 세션을 시작할 수 있는 AWS Identity and Access Management(IAM) 정책 권한을 부여하지 않았습니다. 자세한 내용은 인스턴스에 대한 사용자 세션 액세스 제어를 참조하세요.
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 기본 설정을 지정할 수 있는 IAM 정책 권한을 부여하지 않았습니다. 자세한 내용은 Session Manager 기본 설정을 업데이트하도록 사용자 권한 부여 또는 거부을 참조하세요.
관리형 노드를 사용할 수 없거나 Session Manager에 대해 구성되지 않음
문제 1: 세션 시작(Start a session) 콘솔 페이지에서 세션을 시작하려고 했지만 관리형 노드가 목록에 없습니다.
-
솔루션 A: 연결하려는 관리형 노드가 AWS Systems Manager에서 구성되지 않았을 수 있습니다. 자세한 내용은 AWS Systems Manager 설정 단원을 참조하십시오.
참고
IAM 인스턴스 프로파일을 연결할 때 AWS Systems Manager SSM Agent가 이미 실행 중이면 세션 시작(Start a session) 콘솔 페이지에 관리형 노드가 나열되기 전에 에이전트를 다시 시작해야 할 수 있습니다.
-
해결 방법 B: 관리형 노드의 SSM Agent에 적용한 프록시 구성이 올바르지 않을 수 있습니다. 프록시 구성이 올바르지 않으면 관리형 노드가 필요한 서비스 엔드포인트에 연결할 수 없거나 노드가 Systems Manager에 다른 운영 체제로 보고할 수 있습니다. 자세한 내용은 SSM Agent를 구성하여 Linux 노드에 프록시 사용 및 Windows Server 인스턴스에 프록시를 사용하도록 SSM Agent 구성 단원을 참조하세요.
문제 2: 연결하려는 관리형 노드가 세션 시작(Start a session) 콘솔 페이지의 목록에 있지만 이 페이지에 "선택한 인스턴스가 Session Manager를 사용하도록 구성되지 않았습니다.(The instance you selected isn't configured to use Session Manager.)"라는 메시지가 표시됩니다.
-
해결 방법 A: 관리형 노드가 Systems Manager 서비스에서 사용하도록 구성되어 있지만 노드에 연결된 IAM 인스턴스 프로파일에 Session Manager 기능에 대한 권한이 없을 수 있습니다. 자세한 내용은 Session Manager 권한이 있는 IAM 인스턴스 프로파일 확인 또는 생성(Verify or Create an IAM Instance Profile with Session Manager Permissions)을 참조하세요.
-
해결 방법 B: 관리형 노드가 Session Manager를 지원하는 SSM Agent 버전을 실행하지 않습니다. 노드에 대한 SSM Agent를 버전 2.3.68.0 이상으로 업데이트합니다.
운영 체제에 따라 SSM Agent용 EC2 인스턴스에 수동으로 Windows Server 설치 및 제거, Linux용 EC2 인스턴스에 수동으로 SSM Agent 설치 및 제거 또는 SSM Agent용 EC2 인스턴스에 수동으로 macOS 설치 및 제거의 단계를 수행하여 관리형 노드에 SSM Agent를 업데이트합니다.
또는 Run Command 문서
AWS-UpdateSSMAgent
를 사용하여 한 번에 하나 이상의 관리형 노드에서 에이전트 버전을 업데이트하세요. 자세한 내용은 Run Command를 사용하여 SSM Agent 업데이트을 참조하세요.작은 정보
에이전트를 항상 최신 상태로 유지하려면 다음 방법 중 하나를 사용하여 정의한 자동화된 일정에 따라 SSM Agent를 최신 버전으로 업데이트하는 것이 좋습니다.
-
State Manager 연결의 일부로
AWS-UpdateSSMAgent
를 실행합니다. 자세한 내용은 연습: AWS CLI를 사용하여 SSM Agent를 자동으로 업데이트을 참조하세요. -
AWS-UpdateSSMAgent
를 유지 관리 기간의 일부로 실행합니다. 유지 관리 기간 작업에 대한 자세한 내용은 콘솔을 사용하여 유지 관리 기간 생성 또는 선택 및 자습서: AWS CLI를 사용한 유지 관리 기간 생성 및 구성 섹션을 참조하세요.
-
-
해결 방법 C: 관리형 노드가 필수 서비스 엔드포인트에 연결할 수 없습니다. AWS PrivateLink에서 제공하는 인터페이스 엔드포인트를 사용하여 Systems Manager 엔드포인트에 연결하여 관리형 노드의 보안 태세를 개선할 수 있습니다. 인터페이스 엔드포인트 사용의 대체 방법은 관리형 노드에서 아웃바운드 인터넷 액세스를 허용하는 것입니다. 자세한 내용은 PrivateLink를 사용하여 Session Manager에 대한 VPC 엔드포인트 설정을 참조하세요.
-
솔루션 D: 관리형 노드에 사용 가능한 CPU 또는 메모리 리소스가 제한되어 있습니다. 관리형 노드가 작동할 수는 있지만 노드에 사용 가능한 리소스가 충분하지 않은 경우 세션을 설정할 수 없습니다. 자세한 내용은 연결할 수 없는 인스턴스 문제 해결을 참조하십시오.
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
PATH 변수(Windows)를 수정하려면
-
Windows 키를 누르고
environment variables
를 입력합니다. -
계정의 환경 변수 편집을 선택합니다.
-
PATH를 선택한 후 편집을 선택합니다.
-
다음 예제에 표시된 대로 세미콜론으로 구분하여 경로를 변수 값 필드에 추가합니다.
;C:\existing\path
C:\new\path
다음 예제들에 표시된 대로
는 필드에 이미 있는 값을 나타내고,C:\existing\path
는 추가하려는 경로를 나타냅니다.C:\new\path
-
64비트 시스템:
C:\Program Files\Amazon\SessionManagerPlugin\bin\
-
32비트 시스템:
C:\Program Files (x86)\Amazon\SessionManagerPlugin\bin\
-
-
확인을 두 번 선택하여 새 설정을 적용합니다.
-
실행 중인 명령 프롬프트를 모두 닫았다가 다시 엽니다.
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.)” 오류 메시지를 반환합니다.
-
해결 방법 A: 세션에 대해 지정된 대상 관리형 노드가 세션 관리자에서 사용하도록 완전히 구성되지 않은 경우 이 오류가 반환됩니다. 자세한 내용은 Session Manager 설정을 참조하세요.
-
해결 방법 B: 서로 다른 AWS 계정 또는 AWS 리전에 위치한 관리형 노드에서 세션을 시작하려고 시도하는 경우에도 이 오류가 반환됩니다.
세션 시작 후 빈 화면 표시
문제: 세션을 시작하면 Session Manager에 빈 화면이 표시됩니다.
-
해결 방법 A: 이 문제는 관리형 노드의 루트 볼륨이 가득 찬 경우 발생할 수 있습니다. 디스크 공간 부족으로 인해 노드에서 SSM Agent 작동이 중지됩니다. 이 문제를 해결하려면 Amazon CloudWatch를 사용하여 운영 체제의 지표 및 로그를 수집합니다. 자세한 내용은 Amazon CloudWatch 사용 설명서의 CloudWatch 에이전트를 사용하여 지표, 로그 및 추적 수집을 참조하세요.
-
해결 방법 B: 일치하지 않는 엔드포인트 및 리전 페어가 포함된 링크를 사용하여 콘솔에 액세스한 경우 빈 화면이 표시될 수 있습니다. 예를 들어 다음 콘솔 URL에서
us-west-2
는 지정된 엔드포인트이지만us-west-1
이 지정된 AWS 리전입니다.https://us-west-2.console.aws.amazon.com/systems-manager/session-manager/sessions?region=us-west-1
-
해결 방법 C: 관리형 노드가 VPC 엔드포인트를 사용하여 Systems Manager에 연결하고 있고 Session Manager 기본 설정에서 세션 출력을 Amazon S3 버킷 또는 Amazon CloudWatch Logs 로그 그룹에 기록하지만
s3
게이트웨이 엔드포인트 또는logs
인터페이스 엔드포인트는 VPC에 존재하지 않습니다. 관리형 노드가 VPC 엔드포인트를 사용하여 Systems Manager에 연결하고 Session Manager 기본 설정이 Amazon S3 버킷에 세션 출력을 쓰는 경우com.amazonaws.
형식의region
.s3s3
엔드포인트가 필요합니다. 대신 관리형 노드가 VPC 엔드포인트를 사용하여 Systems Manager에 연결하고 Session Manager 기본 설정이 CloudWatch Logs 로그 그룹에 세션 출력을 쓰는 경우com.amazonaws.
형식의region
.logslogs
엔드포인트가 필요합니다. 자세한 내용은 Systems Manager용 VPC 엔드포인트 생성 단원을 참조하십시오. -
해결 방법 D: 세션 기본 설정에서 지정한 로그 그룹 또는 Amazon S3 버킷이 삭제되었습니다. 이 문제를 해결하려면 유효한 로그 그룹 또는 S3 버킷으로 세션 기본 설정을 업데이트합니다.
-
해결 방법 E: 세션 기본 설정에서 지정한 로그 그룹 또는 Amazon S3 버킷은 암호화되지 않았지만
cloudWatchEncryptionEnabled
또는s3EncryptionEnabled
입력을true
로 설정했습니다. 이 문제를 해결하려면 암호화된 로그 그룹 또는 Amazon S3 버킷으로 세션 기본 설정을 업데이트하거나cloudWatchEncryptionEnabled
또는s3EncryptionEnabled
입력을false
로 설정합니다. 이 시나리오는 명령줄 도구를 사용하여 세션 기본 설정을 생성하는 고객에게만 적용됩니다.
장기 실행 세션 동안 관리형 노드가 응답하지 않음
문제: 장기 실행 세션 중에 관리형 노드가 응답하지 않거나 충돌합니다.
해결 방법: Session Manager에 대한 SSM Agent 로그 보존 기간을 줄입니다.
세션에 대한 SSM Agent 로그 보존 기간을 줄이려면
-
Linux의
/etc/amazon/ssm/
디렉터리 또는 Windows의C:\Program Files\Amazon\SSM
에서amazon-ssm-agent.json.template
을 찾습니다. -
amazon-ssm-agent.json.template
의 내용을 동일한 디렉터리의amazon-ssm-agent.json
이라는 새 파일에 복사합니다. -
SSM
속성에서SessionLogsRetentionDurationHours
값의 기본값을 줄이고 파일을 저장합니다. -
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에서 세션 문서의 목록을 봅니다.
세션 문서 목록 보기
AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/
)을 엽니다. -
탐색 창에서 Documents를 선택합니다.
-
범주 목록에서 세션 문서를 선택합니다.