Session Manager 문제 해결 - AWS Systems Manager

Session Manager 문제 해결

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

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분 후에도 탭에 연결 버튼이 표시되지 않으면 인스턴스를 재부팅 해보세요. 재부팅 후에도 연결 옵션이 표시되지 않으면 빠른 설정을 열고 호스트 관리 구성이 하나뿐인지 확인합니다. 구성이 2개라면 오래된 구성을 삭제하고 몇 분 정도 기다립니다.

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

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

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

Quick Setup을 사용하여 호스트 관리 구성을 업데이트하는 방법
  1. AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/)을 엽니다.

  2. 탐색 창에서 Quick Setup를 선택합니다.

  3. 생성한 호스트 관리 구성을 구성 목록에서 선택합니다.

  4. 작업을 선택한 다음에 구성 편집을 선택합니다.

  5. 대상 섹션 아래쪽의 대상 인스턴스 지정 방식 선택에서 수동을 선택합니다.

  6. 생성한 인스턴스를 인스턴스 섹션에서 선택합니다.

  7. 업데이트를 선택합니다.

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) 콘솔 페이지에서 세션을 시작하려고 했지만 관리형 노드가 목록에 없습니다.

  • 솔루션 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.)"라는 메시지가 표시됩니다.

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)를 수정하려면
  1. Windows 키를 누르고 environment variables를 입력합니다.

  2. 계정의 환경 변수 편집을 선택합니다.

  3. PATH를 선택한 후 편집을 선택합니다.

  4. 다음 예제에 표시된 대로 세미콜론으로 구분하여 경로를 변수 값 필드에 추가합니다. 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\

  5. 확인을 두 번 선택하여 새 설정을 적용합니다.

  6. 실행 중인 명령 프롬프트를 모두 닫았다가 다시 엽니다.

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.s3 형식의 s3 엔드포인트가 필요합니다. 대신 관리형 노드가 VPC 엔드포인트를 사용하여 Systems Manager에 연결하고 Session Manager 기본 설정이 CloudWatch Logs 로그 그룹에 세션 출력을 쓰는 경우 com.amazonaws.region.logs 형식의 logs 엔드포인트가 필요합니다. 자세한 내용은 Systems Manager용 VPC 엔드포인트 생성 단원을 참조하십시오.

  • 해결 방법 D: 세션 기본 설정에서 지정한 로그 그룹 또는 Amazon S3 버킷이 삭제되었습니다. 이 문제를 해결하려면 유효한 로그 그룹 또는 S3 버킷으로 세션 기본 설정을 업데이트합니다.

  • 해결 방법 E: 세션 기본 설정에서 지정한 로그 그룹 또는 Amazon S3 버킷은 암호화되지 않았지만 cloudWatchEncryptionEnabled 또는 s3EncryptionEnabled 입력을 true로 설정했습니다. 이 문제를 해결하려면 암호화된 로그 그룹 또는 Amazon S3 버킷으로 세션 기본 설정을 업데이트하거나 cloudWatchEncryptionEnabled 또는 s3EncryptionEnabled 입력을 false로 설정합니다. 이 시나리오는 명령줄 도구를 사용하여 세션 기본 설정을 생성하는 고객에게만 적용됩니다.

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

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

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

세션에 대한 SSM Agent 로그 보존 기간을 줄이려면
  1. Linux의 /etc/amazon/ssm/ 디렉터리 또는 Windows의 C:\Program Files\Amazon\SSM에서 amazon-ssm-agent.json.template을 찾습니다.

  2. amazon-ssm-agent.json.template의 내용을 동일한 디렉터리의 amazon-ssm-agent.json이라는 새 파일에 복사합니다.

  3. SSM 속성에서 SessionLogsRetentionDurationHours 값의 기본값을 줄이고 파일을 저장합니다.

  4. 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에서 세션 문서의 목록을 봅니다.

세션 문서 목록 보기
  1. AWS Systems Manager 콘솔(https://console.aws.amazon.com/systems-manager/)을 엽니다.

  2. 탐색 창에서 Documents를 선택합니다.

  3. 범주 목록에서 세션 문서를 선택합니다.