OS 로그인 문제 해결

이 문서에서는 메타데이터 서버를 사용하여 OS 로그인 문제를 해결하는 방법을 설명합니다. OS 로그인 설정에 대한 자세한 내용 또는 단계별 안내는 OS 로그인 설정을 참조하세요.

가상 머신(VM) 인스턴스 내에서 메타데이터 서버를 쿼리할 수 있습니다. 자세한 내용은 인스턴스 메타데이터 저장 및 검색을 참조하세요.

시작하기 전에

아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인하는 프로세스입니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음과 같이 Compute Engine에 인증하면 됩니다.

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

일반적인 오류 메시지

다음은 OS 로그인을 사용할 때 발생할 수 있는 일반적인 오류의 예시입니다.

그룹 이름을 찾을 수 없음

OS 로그인을 사용하는 일부 VM에서는 연결이 설정된 후 다음과 같은 오류 메시지가 표시될 수 있습니다.

/usr/bin/id: cannot find name for group ID 123456789

이 오류 메시지는 무시하세요. 이 오류는 VM에 영향을 주지 않습니다.

그룹 가져오기 실패

VM을 만들 때 다음과 비슷한 로그가 표시될 수 있습니다.

Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Refreshing group entry cache
Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Failure getting groups, quitting

이러한 로그는 조직에 OS 로그인 Linux 그룹이 구성되어 있지 않음을 나타냅니다. 이러한 메시지는 무시하세요.

실패함 전제조건

SSH를 사용하여 VM에 연결할 때 다음과 비슷한 오류가 표시될 수 있습니다.

ERROR: (gcloud.compute.ssh) FAILED_PRECONDITION: The specified username or UID is not unique within given system ID.

이 오류는 OS 로그인이 조직 내에 이미 존재하는 사용자 이름을 생성하려고 할 때 발생합니다. 이는 사용자 계정이 삭제되고 바로 같은 이메일 주소를 가진 신규 사용자가 생성되는 경우에 일반적입니다. 사용자 계정이 삭제된 후 사용자의 POSIX 정보를 삭제하는 데 최대 48시간이 걸립니다.

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

삭제된 계정을 복원합니다.
계정을 삭제하기 전에 계정의 POSIX 정보를 삭제합니다.

잘못된 인수

SSH를 사용하여 VM에 연결하거나 SCP를 사용하여 파일을 전송할 때 다음과 비슷한 오류가 표시될 수 있습니다.

ERROR: (gcloud.compute.ssh) INVALID_ARGUMENT: Login profile size exceeds 32 KiB. Delete profile values to make additional space.

ERROR: (gcloud.compute.scp) INVALID_ARGUMENT: Login profile size exceeds 32 KiB. Delete profile values to make additional space.

이 오류를 해결하려면 다음 안내를 따르세요.

gcloud compute os-login describe-profile 명령어를 실행하여 OS 로그인 프로필을 확인합니다.

gcloud compute os-login describe-profile

결과는 다음과 유사합니다.

name: '00000000000000'
posixAccounts:
...
sshPublicKeys:
 ...:
   fingerprint: ...
   key: |
     ssh-rsa AAAAB3NzaC1yc2...
   name: ...
 ...

출력을 검토하여 사용되지 않은 SSH 키를 식별합니다.
gcloud compute os-login ssh-keys remove 명령어를 사용하여 출력에서 사용하지 않는 키를 삭제합니다.
```
gcloud compute os-login ssh-keys remove --key=KEY
```
KEY를 키의 디지털 지문 또는 키 문자열로 바꿉니다.

향후 이 문제가 발생하지 않도록 하려면 SSH 키의 만료 시간을 추가합니다. 만료된 키는 만료 48시간 후 또는 프로필에 새 키를 추가할 때 로그인 프로필에서 자동으로 삭제됩니다.

HTTP 응답 코드: 503

SSH를 사용하여 VM에 연결하려고 하면 다음 오류가 표시될 수 있습니다.

Failed to validate organization user USERNAME has login permission, got HTTP response code: 503

이 문제는 메타데이터 서버 비율 제한이 가상 머신 인스턴스별로 초당 100개 쿼리 수로 인해 발생합니다. 이 한도는 조정할 수 없습니다. 이 문제를 해결하려면 몇 초 정도 기다린 후 연결을 다시 시도합니다.

향후 이 문제가 발생하지 않도록 하려면 다음을 시도해 보세요.

애플리케이션 코드에서 재시도 메커니즘을 구현합니다. 자세한 내용은 다음을 참조하세요.
- 지수 백오프
- 재시도 전략
기존 SSH 연결을 재사용합니다.
명령어를 일괄적으로 전송하여 SSH 연결 및 OS 로그인 메타데이터 쿼리를 줄입니다.

기본 OS 로그인 메타데이터 항목

Compute Engine은 OS 로그인 정보를 제공하는 기본 메타데이터 항목의 집합을 정의합니다. 기본 메타데이터는 항상 서버에서 정의되고 설정됩니다. 기본 메타데이터 키는 대소문자를 구분합니다.

다음 표에는 쿼리할 수 있는 항목이 설명되어 있습니다.

`http://metadata.google.internal/computeMetadata/v1/` 관련
메타데이터 항목	설명
`project/attributes/enable-oslogin`	현재 Google Cloud 프로젝트에서 OS 로그인이 사용 설정되어 있는지 확인합니다.
`instance/attributes/enable-oslogin`	현재 VM에서 OS 로그인이 사용 설정되어 있는지 확인합니다.
`oslogin/users/`	OS 로그인 사용자의 프로필 정보를 검색합니다. `username`, `uid`, `pagesize`, `pagetoken`과 같은 쿼리 매개변수를 전달할 수 있습니다.
`oslogin/authorize/`	OS 로그인 사용자의 로그인 또는 관리 수준 권한 설정값을 검색합니다. 권한을 확인하려면 `policy` 쿼리 매개변수를 지정해야 합니다. 정책 매개변수의 값은 `login`(로그인 권한 확인) 또는 `adminLogin`(sdo 액세스 확인)으로 설정해야 합니다.

OS 로그인이 구성 여부 확인

Google Cloud 콘솔이나 Google Cloud CLI를 사용하여 메타데이터를 쿼리해 OS 로그인이 사용 설정되었는지 확인합니다. 프로젝트 또는 인스턴스 메타데이터에서 enable-oslogin 메타데이터 키가 TRUE로 설정되었으면 OS 로그인이 사용 설정된 것입니다. 인스턴스 및 프로젝트 메타데이터가 모두 설정되었으면 인스턴스 메타데이터에 설정된 값이 우선 적용됩니다.

OS 로그인 사용자 보기

여러 사용자의 프로필 정보를 보려면 pagesize 및 pagetoken 매개변수를 지정해야 합니다. pagesize 및 pagetoken을 필요한 숫자 값으로 바꿉니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=PAGE_SIZE&
pagetoken=PAGE_TOKEN" -H "Metadata-Flavor: Google"

예를 들어 pagesize를 1로 설정하고 pagetoken을 0으로 설정하려면 다음 명령어를 실행합니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=1&pagetoken=0" -H "Metadata-Flavor: Google"

대부분의 배포판에서는 Unix 명령어 getent passwd를 실행하여 조직 사용자의 비밀번호 항목을 검색할 수도 있습니다.

특정 OS 로그인 사용자 보기

VM에서 특정 사용자의 프로필 정보를 보려면 다음 명령어를 실행합니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=USERNAME" -H "Metadata-Flavor: Google"

USERNAME을 쿼리할 사용자의 사용자 이름으로 바꿉니다.

예를 들어 사용자 user_example_com을 검색하는 요청을 수행할 수 있습니다. 다음 명령어 및 결과는 가독성을 높이기 위해 추가된 형식을 보여줍니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

출력은 다음과 비슷합니다.

{
    "loginProfiles": [{
        "name": "12345678912345",
        "posixAccounts": [{
            "primary": true,
            "username": "user_example_com",
            "uid": "123451",
            "gid": "123451",
            "homeDirectory": "/home/user_example_com",
            "operatingSystemType": "LINUX"
        }],
        "sshPublicKeys": {
            "204c4b4fb...": {
                "key": "ssh-rsa AAAAB3Nz...",
                "fingerprint": "204c4b4fb..."
            }
        }
    }]
}

대부분의 배포판에서는 getent passwd username 또는 getent passwd uid와 같은 Unix 명령어를 실행하여 프로필 정보를 검색할 수도 있습니다.

사용자의 SSH 키를 검색하려면 /usr/bin/google_authorized_keys USERNAME을 실행하면 됩니다. 키가 반환되지 않으면 해당 사용자에게 VM에 로그인하는 데 필요한 권한이 없을 수 있습니다.

로그인 권한 확인

로그인 및 관리 수준 권한을 보려면 policy=login&email=LOGIN_NAME 쿼리 매개변수를 제공해야 합니다.

사용자 프로필을 쿼리하여 name 필드 값을 가져옵니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

결과에서 name을 기록해 둡니다.

name 값을 사용하여 다음 login 명령어를 실행합니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=LOGIN_NAME" -H "Metadata-Flavor: Google"

예를 들어 이전 섹션에서 조회한 사용자 user_example_com의 로그인 권한을 쿼리할 수 있습니다.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=12345678912345" -H "Metadata-Flavor: Google"

명령어 출력은 사용자가 VM에 로그인할 권한이 있음을 나타냅니다.

{"success":true}

VM에 서비스 계정이 있는지 확인

메타데이터 서버를 쿼리하여 VM과 연결된 서비스 계정을 찾을 수 있습니다. VM에서 다음 명령어를 실행합니다.

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" -H "Metadata-Flavor: Google"

출력은 다음과 비슷합니다.

12345-sa@developer.gserviceaccount.com/
default/

서비스 계정이 없으면 결과가 비어 있습니다.

gcpdiag로 OS 로그인 문제 디버깅

gcpdiag는 오픈소스 도구입니다. 공식적으로 지원되는 Google Cloud 제품이 아닙니다. gcpdiag 도구를 사용하여 Google Cloud 프로젝트 문제를 식별하고 해결할 수 있습니다. 자세한 내용은 GitHub의 gcpdiag 프로젝트를 참조하세요.

이 gcpdiag 런북은 Google Cloud의 Windows 및 Linux VM 모두에서 SSH 액세스 문제의 잠재적인 원인을 조사합니다. 다음 사항에 중점을 둡니다.

VM 상태: VM이 실행 중이고 리소스(CPU, 메모리, 디스크)가 충분한지 확인합니다.
권한: SSH 키를 구성할 수 있는 올바른 IAM 권한이 있는지 확인합니다.
VM 설정: SSH 키 및 기타 메타데이터가 올바르게 구성되었는지 확인합니다.
네트워크 규칙: 방화벽 규칙을 검토하여 SSH 트래픽이 허용되는지 확인합니다.
게스트 OS: SSH를 차단할 수 있는 내부 OS 문제를 찾습니다.

Google Cloud 콘솔

다음 명령어를 작성하고 복사합니다.

gcpdiag runbook gce/ssh --project=PROJECT_ID \
    --parameter name=VM_NAME \
    --parameter zone=ZONE \
    --parameter principal=PRINCIPAL \
    --parameter tunnel_through_iap=IAP_ENABLED

Google Cloud 콘솔을 열고 Cloud Shell을 활성화합니다.

Cloud 콘솔 열기

복사한 명령어를 붙여넣습니다.
gcpdiag 명령어를 실행하면 gcpdiag Docker 이미지를 다운로드한 후 진단 검사를 수행합니다. 해당하는 경우 출력 안내에 따라 실패한 검사를 수정합니다.

Docker

Docker 컨테이너에서 gcpdiag를 시작하는 래퍼를 사용하여 gcpdiag를 실행할 수 있습니다. Docker 또는 Podman이 설치되어 있어야 합니다.

로컬 워크스테이션에서 다음 명령어를 복사하고 실행합니다.
```
curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
```

gcpdiag 명령어를 실행합니다.

./gcpdiag runbook gce/ssh --project=PROJECT_ID \
    --parameter name=VM_NAME \
    --parameter zone=ZONE \
    --parameter principal=PRINCIPAL \
    --parameter tunnel_through_iap=IAP_ENABLED

이 런북에 사용 가능한 매개변수를 봅니다.

다음을 바꿉니다.

PROJECT_ID: 리소스가 포함된 프로젝트의 ID
VM_NAME: 프로젝트 내의 대상 VM 이름
ZONE: 대상 VM이 있는 영역
PRINCIPAL: SSH 연결을 시작하는 사용자 또는 서비스 계정 주 구성원. 키 기반 인증의 경우 Cloud Shell 명령줄 도구로 인증되었거나 Google Cloud 콘솔에 로그인한 사용자를 사용합니다. 서비스 계정 가장의 경우 서비스 계정의 이메일이어야 합니다.
IAP_ENABLED: SSH 연결을 설정하는 데 Identity-Aware Proxy가 사용되는지 여부를 나타내는 불리언 값(true 또는 false) 기본값: true

유용한 플래그:

--project: PROJECT_ID
--universe-domain: 해당되는 경우 리소스를 호스팅하는 신뢰할 수 있는 파트너 주권 클라우드 도메인
--parameter 또는 -p: 런북 파라미터

모든 gcpdiag 도구 플래그의 목록과 설명은 gcpdiag 사용 안내를 참고하세요.

다음 단계

OS 로그인 자세히 알아보기
Compute Engine에서 Linux VM에 대한 SSH 연결이 작동하는 방식 알아보기
단계별 안내를 보려면 다음 중 하나를 검토하세요.
- OS 로그인 설정
- 2단계 인증으로 OS 로그인 설정
조직의 OS 로그인 관리하기 검토