GKE에서 누락된 로그 문제 해결

Autopilot Standard

Google Kubernetes Engine (GKE)의 로깅 파이프라인에 문제가 있으면 클러스터 로그가 Cloud Logging에 표시되지 않아 모니터링 및 디버깅 작업이 방해될 수 있습니다.

이 문서를 사용하여 구성 및 권한을 확인하고, 리소스 및 성능 문제를 해결하고, 필터 및 애플리케이션 동작을 조사하고, 로그에 영향을 미치는 플랫폼 또는 서비스 문제를 해결하는 방법을 알아보세요.

이 정보는 클러스터 관측 가능성을 유지하는 플랫폼 관리자 및 운영자와 Cloud Logging을 사용하여 GKE 작업을 해결하는 모든 사용자에게 중요합니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE 사용자 역할 및 태스크를 참고하세요.

로그를 사용하여 워크로드와 클러스터 문제를 해결하는 방법에 대한 자세한 내용은 Cloud Logging으로 과거 데이터 분석 수행을 참고하세요.

증상별 해결 방법 찾기

누락된 로그와 관련된 특정 증상을 확인한 경우 다음 표를 사용하여 문제 해결 도움말을 확인하세요.

카테고리	증상 또는 관찰	잠재적 원인	문제 해결 단계
구성	프로젝트의 모든 클러스터의 로그가 표시되지 않습니다.	프로젝트에 Cloud Logging API가 사용 중지되었습니다.	Cloud Logging API 상태 확인
	특정 클러스터에서 로그가 누락되거나 특정 로그 유형만 누락됩니다.	필수 로그 유형에 대해 클러스터 수준 로깅이 사용 중지되어 있습니다.	클러스터 로깅 구성 확인
	특정 노드 풀의 노드에서 로그가 누락되었습니다.	노드 풀의 노드에 필요한 액세스 범위가 없습니다.	노드 풀 액세스 범위 확인
	권한 오류 (401 또는 403)가 로깅 에이전트 로그에 표시됩니다.	노드의 서비스 계정에 필요한 권한이 없습니다.	노드 서비스 계정 권한 확인
리소스 및 성능	로그가 간헐적으로 누락되거나 RESOURCE_EXHAUSTED 오류가 표시됩니다.	프로젝트가 Cloud Logging API 쓰기 할당량을 초과했습니다.	Cloud Logging API 할당량 사용량 조사
	특정 노드의 일부 로그가 누락됩니다(트래픽이나 부하가 높은 경우에 자주 발생).	노드가 로깅 에이전트 처리량 한도를 초과하거나 로그를 처리할 리소스 (CPU 또는 메모리)가 부족합니다.	노드 처리량 및 리소스 사용량 조사하기
필터링 및 애플리케이션 동작	특정 패턴과 일치하는 특정 로그가 지속적으로 누락됩니다.	Cloud Logging의 로그 제외 필터가 의도치 않게 로그를 삭제합니다.	로그 제외 필터 조사하기
	컨테이너의 로그가 크게 지연되거나 컨테이너가 종료된 후에만 표시됩니다.	애플리케이션의 출력이 완전히 버퍼링됩니다(stdout 파이핑으로 인한 경우가 많음).	컨테이너 로그 버퍼링 및 지연 조사
	예상 로그가 검색 결과에 표시되지 않습니다.	로그 탐색기의 쿼리 필터가 너무 제한적일 수 있습니다.	로그 탐색기 쿼리 조사
	특정 애플리케이션 포드에서는 로그가 표시되지 않지만 다른 클러스터 로그는 표시됩니다.	컨테이너 내부의 애플리케이션이 stdout 또는 stderr에 쓰지 않습니다.	애플리케이션별 로깅 동작 조사
플랫폼 및 서비스	특정 날짜보다 오래된 로그는 표시되지 않습니다.	로그의 보관 기간이 지나 Cloud Logging에서 삭제되었습니다.	로그 보관 기간 조사하기
	프로젝트 또는 클러스터 전반에서 광범위한 로그 손실 또는 지연이 발생합니다.	Cloud Logging 서비스 문제 또는 수집 지연	Cloud Logging 서비스 문제 및 지연 조사
	로깅 문제는 클러스터 버전 제한과 관련이 있습니다.	지원되지 않는 GKE 버전입니다.	클러스터 버전 조사

자동 진단 도구 사용

다음 섹션에서는 일반적인 잘못된 구성을 자동으로 검사하고 복잡한 문제를 조사하는 데 도움이 되는 도구를 다룹니다.

gcpdiag로 GKE 로깅 문제 디버그

GKE 클러스터에서 로그가 누락되거나 불완전한 경우 gcpdiag 도구를 사용하여 문제를 해결합니다.

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

GKE 클러스터에서 로그가 누락되거나 불완전한 경우 다음 핵심 구성 설정에 집중하여 잠재적인 원인을 조사합니다.

• 프로젝트 수준 로깅: GKE 클러스터가 있는 Google Cloud 프로젝트에 Cloud Logging API가 사용 설정되었는지 확인합니다.
• 클러스터 수준 로깅: 로깅이 GKE 클러스터 구성 내에서 명시적으로 사용 설정되었는지 확인합니다.
• 노드 풀 권한: 로그 데이터를 전송할 수 있도록 클러스터의 노드 풀 내 노드에 Cloud Logging Write 범위가 사용 설정되어 있는지 확인합니다.
• 서비스 계정 권한: 노드 풀에서 사용하는 서비스 계정에 Cloud Logging과 상호작용하는 데 필요한 IAM 권한이 있는지 확인합니다. 특히 일반적으로 roles/logging.logWriter 역할이 필요합니다.
• Cloud Logging API 쓰기 할당량: Cloud Logging API 쓰기 할당량이 지정된 기간 내에 초과되지 않았는지 확인합니다.

Google Cloud 콘솔

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

gcpdiag runbook gke/logs \
    --parameter project_id=PROJECT_ID \
    --parameter name=CLUSTER_NAME \
    --parameter location=LOCATION

2. Google Cloud 콘솔을 열고 Cloud Shell을 활성화합니다.
Cloud 콘솔 열기
3. 복사한 명령어를 붙여넣습니다.
4. gcpdiag 명령어를 실행하면 gcpdiag Docker 이미지를 다운로드한 후 진단 검사를 수행합니다. 해당하는 경우 출력 안내에 따라 실패한 검사를 수정합니다.

Docker

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

1. 로컬 워크스테이션에서 다음 명령어를 복사하고 실행합니다.

   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag

2. gcpdiag 명령어를 실행합니다.

   ./gcpdiag runbook gke/logs \
       --parameter project_id=PROJECT_ID \
       --parameter name=CLUSTER_NAME \
       --parameter location=LOCATION

이 런북에 사용 가능한 파라미터를 봅니다.

다음을 바꿉니다.

• PROJECT_ID: 리소스가 포함된 프로젝트의 ID입니다.
• CLUSTER_NAME: GKE 클러스터의 이름입니다.
• LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)입니다.

유용한 플래그:

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

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

Gemini Cloud Assist 조사 사용

Gemini Cloud Assist 조사를 사용하여 로그에 대한 추가 통계를 얻고 문제를 해결하는 것이 좋습니다. 로그 탐색기를 사용하여 조사를 시작하는 다양한 방법에 대한 자세한 내용은 Gemini 문서의 Gemini Cloud Assist 조사로 문제 해결을 참고하세요.

로깅 구성 및 권한 확인

잘못된 설정은 GKE 로그가 누락되는 일반적인 이유입니다. 다음 섹션을 사용하여 Cloud Logging 구성을 확인하세요.

Cloud Logging API 상태 확인

프로젝트의 클러스터에서 로그를 수집하려면 Cloud Logging API가 활성 상태여야 합니다.

증상:

프로젝트의 GKE 리소스 로그가 Cloud Logging에 표시되지 않습니다.

원인:

Google Cloud 프로젝트에서 Cloud Logging API가 사용 중지되어 노드의 로깅 에이전트가 로그를 전송할 수 없습니다.

해결 방법:

Cloud Logging API가 사용 설정되어 있는지 확인하고 필요한 경우 사용 설정하려면 다음 옵션 중 하나를 선택합니다.

콘솔

1. Google Cloud 콘솔에서 사용 설정된 API 및 서비스 페이지로 이동합니다.

   사용 설정된 API 및 서비스로 이동

2. 필터 필드에 Cloud Logging API을 입력하고 Enter 키를 누릅니다.

3. API가 사용 설정되어 있으면 목록에 표시됩니다. API가 표시되지 않으면 다음 안내에 따라 사용 설정하세요.

   1. API 및 서비스 사용 설정을 클릭합니다.
   2. 검색 필드에 Cloud Logging API를 입력하고 Enter 키를 누릅니다.
   3. Cloud Logging API 결과를 클릭합니다.
   4. 사용 설정을 클릭합니다.

gcloud

1. API가 사용 설정되었는지 확인합니다.

   gcloud services list --enabled --filter="NAME=logging.googleapis.com"
   

   출력이 다음과 같이 표시됩니다.

   NAME: logging.googleapis.com
   TITLE: Cloud Logging API
   

2. 사용 설정된 서비스에 API가 나열되지 않으면 다음 안내에 따라 사용 설정하세요.

   gcloud services enable logging.googleapis.com \
       --project=PROJECT_ID
   

   PROJECT_ID를 Google Cloud프로젝트 ID로 바꿉니다.

클러스터 로깅 구성 확인

GKE를 사용하면 클러스터에서 수집되는 로그 유형 (예: SYSTEM 또는 WORKLOAD)을 구성할 수 있습니다.

증상:

특정 GKE 클러스터의 로그가 Cloud Logging에 표시되지 않거나 특정 유형의 로그 (예: SYSTEM)만 누락됩니다.

원인:

필수 로그 유형에 대해 클러스터 수준 로깅이 사용 중지되어 있습니다. Autopilot 클러스터를 사용하는 경우 로깅 문제가 발생한 원인이 아닙니다. 이 설정은 Standard 클러스터에서 구성할 수 있지만 Autopilot 클러스터에서는 기본적으로 항상 사용 설정되어 있으며 사용 중지할 수 없습니다.

해결 방법:

클러스터의 로깅 구성을 확인하고 업데이트하려면 다음 옵션 중 하나를 선택하세요.

콘솔

1. Google Cloud 콘솔에서 Kubernetes 클러스터 페이지로 이동합니다.

   Kubernetes 클러스터로 이동

2. 조사할 클러스터의 이름을 클릭합니다.

3. 세부정보 탭을 클릭하고 기능 섹션으로 이동합니다.

4. 로깅 행에서 시스템 또는 워크로드와 같은 사용 설정된 로그 유형을 검토합니다.

5. 수집하려는 로그 유형이 사용 중지되었거나 잘못된 경우 로깅 수정을 클릭합니다.

6. 구성요소 목록에서 수집할 로그 유형의 체크박스를 선택하고 확인을 클릭합니다. 사용 가능한 로그 유형에 대한 자세한 내용은 GKE 로그 정보를 참고하세요.

7. 변경사항 저장을 클릭합니다.

gcloud

1. 로깅 구성을 확인하려면 클러스터를 설명하세요.

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(name,loggingConfig.componentConfig.enableComponents)"
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 클러스터 이름입니다.
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

   로깅이 사용 설정된 경우 출력은 다음과 비슷합니다.

   example-cluster    SYSTEM_COMPONENTS;WORKLOADS
   

   출력이 NONE이면 로깅이 사용 중지된 것입니다.

2. 원하는 로그 유형이 사용 중지되었거나 잘못된 경우 로깅 구성을 업데이트합니다.

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=LOGGING_TYPE
   

   LOGGING_TYPE을 SYSTEM, WORKLOAD 또는 둘 다로 바꿉니다. 로그를 수집하려면 SYSTEM을 사용 설정해야 합니다. WORKLOAD 로그는 단독으로 수집할 수 없습니다. 사용 가능한 로그 유형에 대한 자세한 내용은 GKE 로그 정보를 참고하세요.

노드 풀 액세스 범위 확인

GKE 클러스터의 노드는 OAuth 액세스 범위를 사용하여 Cloud Logging을 비롯한 Google Cloud API와 상호작용할 권한을 얻습니다.

증상:

특정 노드 풀의 노드에서 로그가 누락되었습니다.

원인:

노드 풀의 노드에 필요한 OAuth 액세스 범위가 없습니다. Cloud Logging에 로그를 쓰려면 노드에 다음 범위 중 하나가 필요합니다.

• https://www.googleapis.com/auth/logging.write: 로그를 작성할 권한을 부여합니다. 이것이 필요한 최소 범위입니다.
• https://www.googleapis.com/auth/logging.admin: logging.write의 권한을 포함하는 Cloud Logging API에 대한 전체 액세스 권한을 부여합니다.
• https://www.googleapis.com/auth/cloud-platform: 사용 설정된 모든 Google Cloud API에 대한 전체 액세스 권한을 부여합니다. 여기에는 logging.write의 권한이 포함됩니다.

해결 방법:

권한을 확인하고 필요한 역할이 누락된 경우 부여하려면 다음 옵션 중 하나를 선택합니다.

콘솔

1. 노드 풀의 액세스 범위를 확인합니다.

   1. Google Cloud 콘솔에서 Kubernetes 클러스터 페이지로 이동합니다.

      Kubernetes 클러스터로 이동

   2. 조사할 클러스터의 이름을 클릭하여 클러스터의 세부정보 페이지를 엽니다.

   3. 노드 탭을 클릭합니다.

   4. 노드 풀 섹션에서 조사하려는 노드 풀의 이름을 클릭합니다.

   5. 보안 섹션으로 이동합니다.

   6. 액세스 범위 필드에 나열된 범위를 검토합니다. 필수 범위 중 하나 이상이 있는지 확인합니다.

      • Stackdriver Logging API - 쓰기 전용
      • Stackdriver Logging API - 전체
      • Cloud Platform - Enabled(클라우드 플랫폼 - 사용 설정됨)

      필수 범위가 누락된 경우 노드 풀을 다시 만듭니다. 기존 노드 풀에서는 액세스 범위를 변경할 수 없습니다.

2. 필요한 경우 필요한 범위로 새 노드 풀을 만듭니다.

   1. 수정하려는 클러스터의 클러스터 세부정보 페이지로 다시 이동합니다.
   2. 노드 탭을 클릭합니다.
   3. 사용자 관리 노드 풀 만들기를 클릭합니다.
   4. 노드 풀 세부정보 섹션을 작성합니다.
   5. 왼쪽 탐색 메뉴에서 보안을 클릭합니다.
   6. 액세스 범위 섹션에서 추가할 역할을 선택합니다.
      • 특정 범위를 추가하려면 각 API에 액세스 설정을 선택합니다.
      • 전체 액세스를 허용하려면 모든 Cloud API에 대한 전체 액세스 허용을 선택합니다.
   7. 필요에 따라 다른 섹션을 구성합니다.
   8. 만들기를 클릭합니다.

3. 워크로드를 새 노드 풀로 마이그레이션합니다. 워크로드를 새 노드 풀로 마이그레이션하면 Cloud Logging에 로그를 전송하는 데 필요한 범위가 있는 노드에서 애플리케이션이 실행됩니다.

4. 이전 노드 풀을 삭제합니다.

   1. 클러스터 세부정보 페이지로 돌아가 노드 탭을 선택합니다.
   2. 노드 풀 섹션에서 이전 노드 풀을 찾습니다.
   3. 노드 풀 옆에 있는 삭제를 클릭합니다 .
   4. 메시지가 표시되면 노드 풀 이름을 입력하여 삭제를 확인하고 삭제를 클릭합니다.

gcloud

1. 노드 풀의 액세스 범위를 확인합니다.

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePools[].name,nodePools[].config.oauthScopes)"
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 클러스터 이름입니다.
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

   각 노드 풀의 출력을 검토합니다. 필수 범위 (https://www.googleapis.com/auth/logging.write, https://www.googleapis.com/auth/cloud-platform 또는 https://www.googleapis.com/auth/logging.admin) 중 하나 이상이 나열되어 있는지 확인합니다. 필수 범위가 누락된 경우 노드 풀을 다시 만듭니다. 기존 노드 풀에서는 액세스 범위를 변경할 수 없습니다.

2. 필요한 경우 필요한 범위로 새 노드 풀을 만듭니다.

   gcloud container node-pools create NEW_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --scopes=https://www.googleapis.com/auth/logging.write,OTHER_SCOPES
   

   다음을 바꿉니다.

   • NEW_NODE_POOL_NAME: 새 노드 풀의 이름입니다.
   • OTHER_SCOPES: 노드에 필요한 기타 범위의 쉼표로 구분된 목록입니다. 다른 범위가 필요하지 않으면 이 자리표시자와 앞의 쉼표를 생략합니다.

3. 워크로드를 새 노드 풀로 마이그레이션합니다. 워크로드를 새 노드 풀로 마이그레이션하면 Cloud Logging에 로그를 전송하는 데 필요한 범위가 있는 노드에서 애플리케이션이 실행됩니다.

4. 이전 노드 풀을 삭제합니다.

   gcloud container node-pools delete OLD_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID
   

노드 서비스 계정 권한 확인

노드는 서비스 계정을 사용하여 Google Cloud 서비스로 인증하며, 이 계정에는 로그를 작성하기 위한 특정 IAM 권한이 필요합니다.

증상:

• 노드에서 로그가 누락되었습니다.
• 로깅 에이전트 로그 (예: Fluent Bit)를 검사하면 Cloud Logging에 쓰려고 할 때 401 또는 403 코드와 같은 권한 관련 오류가 표시될 수 있습니다.
• Google Cloud 콘솔에 클러스터에 대한 Grant Critical Permissions to Node Service Account 알림이 표시될 수 있습니다.

원인:

노드 풀의 노드에서 사용하는 서비스 계정에 Cloud Logging에 로그를 작성하는 데 필요한 IAM 권한이 없습니다. 노드에는 logging.logEntries.create 권한이 포함된 logging.logWriter 역할이 있는 서비스 계정이 필요합니다.

또한 GKE 버전 1.33 이상의 경우 GKE 기본 노드 서비스 에이전트([e-mail])에 최소한 Kubernetes 기본 노드 서비스 에이전트 (roles/container.defaultNodeServiceAgent) 역할이 있어야 합니다. 이 역할을 사용하면 GKE가 로깅 구성요소를 비롯한 노드 리소스와 작업을 관리할 수 있습니다.

해결 방법:

권한을 확인하고 누락된 경우 필요한 역할을 부여하려면 다음을 실행하세요.

• 노드의 서비스 계정 권한을 확인합니다.
• GKE 서비스 에이전트에 필요한 역할이 있는지 확인합니다.

노드 서비스 계정 권한 확인

노드 서비스 계정은 노드에서 인증하고 로그를 전송하는 데 사용하는 계정입니다. 이 서비스 계정을 식별하고 필요한 roles/logging.logWriter 권한이 있는지 확인하려면 다음을 실행하세요.

1. 노드 풀에서 사용하는 서비스 계정을 확인하려면 다음 옵션 중 하나를 선택합니다.

   콘솔

   1. Google Cloud 콘솔에서 Kubernetes 클러스터 페이지로 이동합니다.

      Kubernetes 클러스터로 이동

   2. 클러스터 목록에서 검사할 클러스터 이름을 클릭합니다.

   3. 클러스터 작업 모드에 따라 다음 중 하나를 실행합니다.

      • Standard 클러스터의 경우 다음을 실행합니다.

        1. 노드 탭을 클릭합니다.
        2. 노드 풀 표에서 노드 풀 이름을 클릭합니다. 노드 풀 세부정보 페이지가 열립니다.
        3. 보안 섹션에서 서비스 계정 필드를 찾습니다.

      • Autopilot 클러스터의 경우 다음을 수행합니다.

        1. 세부정보 탭으로 이동합니다.
        2. 보안 섹션에서 서비스 계정 필드를 찾습니다.

      서비스 계정 필드의 값이 default이면 노드에서는 Compute Engine 기본 서비스 계정을 사용합니다. 이 필드의 값이 default이 아닌 경우 노드에서 커스텀 서비스 계정을 사용합니다. 커스텀 서비스 계정에 필요한 역할을 부여하려면 최소 권한 IAM 서비스 계정 사용을 참고하세요.

   gcloud

   사용하는 클러스터 유형에 따라 다음 명령어를 실행합니다.

   Standard 클러스터

   gcloud container node-pools describe NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(config.serviceAccount)"
   

   다음을 바꿉니다.

   • NODE_POOL_NAME: 노드 풀의 이름입니다.
   • CLUSTER_NAME: 표준 클러스터의 이름입니다.
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)
   • PROJECT_ID: Google Cloud프로젝트 ID

   출력이 default인 경우 노드 풀은 Compute Engine 기본 서비스 계정을 사용합니다. 값이 default가 아닌 경우 노드에서 커스텀 서비스 계정을 사용합니다. 커스텀 서비스 계정에 필요한 역할을 부여하려면 최소 권한 IAM 서비스 계정 사용을 참고하세요.

   Autopilot 클러스터

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePoolDefaults.nodeConfigDefaults.serviceAccount)"
   

   다음을 바꿉니다.

   • CLUSTER_NAME: Autopilot 클러스터의 이름입니다.
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

   출력이 default인 경우 노드 풀은 Compute Engine 기본 서비스 계정을 사용합니다. 값이 default가 아닌 경우 노드에서 커스텀 서비스 계정을 사용합니다. 커스텀 서비스 계정에 필요한 역할을 부여하려면 최소 권한 IAM 서비스 계정 사용을 참고하세요.

   누락된 권한을 식별하는 자세한 스크립트는 권한이 누락된 모든 노드 서비스 계정 식별을 참고하세요.

2. GKE는 누락된 권한을 자동으로 검색하고 추천을 제공합니다. 추천을 사용하여 누락된 권한을 확인하려면 다음 옵션 중 하나를 선택하세요.

   콘솔

   1. Kubernetes 클러스터 페이지에서 알림 열을 찾습니다.
   2. 중요 권한 부여 추천을 확인하려면 알림 열을 확인합니다. 이 권장사항은 NODE_SA_MISSING_PERMISSIONS 확인이 실패했음을 의미합니다.
   3. 추천이 표시되면 클릭합니다. 세부정보 패널이 열려 누락된 권한을 설명하고 문제를 해결하는 단계를 제공합니다.

   gcloud

   1. 누락된 서비스 계정 권한에 대한 추천을 나열합니다.

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. 명령어 결과를 분석합니다.

      • 명령어가 빈 목록을 반환하면 추천 도구에서 활성 NODE_SA_MISSING_PERMISSIONS 추천을 찾지 못한 것입니다. 확인된 서비스 계정에 필요한 권한이 있는 것으로 보입니다.

      • 명령어가 하나 이상의 YAML 블록을 반환하면 추천 도구에서 권한 문제를 식별한 것입니다. 출력에서 다음 주요 필드를 검토합니다.

        • description: 노드 서비스 계정에 roles/logging.logWriter 역할이 누락되었거나 GKE 서비스 에이전트에 roles/container.defaultNodeServiceAgent 역할이 누락되었다는 등의 문제 요약을 제공합니다.
        • resource: 영향을 받는 클러스터를 지정합니다.
        • content.operations: 권장 해결 방법이 포함되어 있습니다. 이 섹션에서는 누락된 특정 역할을 부여하는 데 필요한 정확한 gcloud projects add-iam-policy-binding 명령어를 제공합니다.

   추천자에 최근 변경사항이 반영되는 데 최대 24시간이 걸릴 수 있습니다.

3. 권한을 즉시 확인하려면 권한을 확인하고 역할을 부여하는 다음 옵션 중 하나를 선택합니다.

   콘솔

   1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

      IAM으로 이동

   2. 노드 풀에서 사용하는 서비스 계정을 찾습니다.

   3. 역할 열에서 서비스 계정에 로그 작성자 (roles/logging.logWriter) 역할이 있는지 확인합니다.

   4. 권한이 누락된 경우 추가합니다.

      1. 주 구성원 수정을 클릭합니다.
      2. 다른 역할 추가를 클릭합니다.
      3. 검색 필드에 Logs Writer을 입력합니다.
      4. 로그 작성자 체크박스를 선택하고 적용을 클릭합니다.
      5. 저장을 클릭합니다.

   gcloud

   1. 노드 서비스 계정의 현재 역할을 확인합니다.

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT_EMAIL"
      

   2. 없는 경우 logging.logWriter 역할을 부여합니다.

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/logging.logWriter"
      

GKE 서비스 에이전트 권한 확인

로그가 계속 누락되고 버전 1.33 이상을 사용하는 경우 GKE가 노드 구성요소를 관리하는 데 사용하는 Google 관리 에이전트에 필요한 권한이 있는지 확인합니다.

1. 서비스 에이전트의 이메일 주소를 확인하려면 프로젝트 번호를 가져오세요.

   gcloud projects describe PROJECT_ID --format="value(projectNumber)"
   

   PROJECT_ID를 프로젝트 ID로 바꿉니다. 출력을 확인합니다.

   GKE 서비스 에이전트의 이메일은 다음과 같습니다. [e-mail]

2. 추천을 사용하여 누락된 권한을 확인하려면 다음 옵션 중 하나를 선택하세요.

   콘솔

   1. Kubernetes 클러스터 페이지에서 알림 열을 찾습니다.
   2. 중요한 권한 부여 권장사항 열을 확인합니다.
   3. 추천이 표시되면 클릭합니다. 세부정보 패널이 열리고 누락된 권한을 설명하고 문제를 해결하는 단계를 제공합니다.

   gcloud

   1. 누락된 서비스 계정 권한에 대한 추천을 나열합니다.

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. 명령어 결과를 분석합니다. GKE 서비스 에이전트(gcp-sa-gkenode)에 roles/container.defaultNodeServiceAgent 역할이 누락되었다고 설명하는 출력을 검토합니다.

3. 권한을 즉시 확인하고 역할을 부여하려면 다음 옵션 중 하나를 선택합니다.

   콘솔

   1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

      IAM으로 이동

   2. 필터 필드에 GKE 서비스 에이전트의 이메일 주소를 입력하고 Enter 키를 누릅니다.

   3. 필터링된 목록에서 서비스 에이전트에 최소한 Kubernetes 기본 노드 서비스 에이전트(roles/container.defaultNodeServiceAgent) 역할이 있는지 확인합니다.

   4. 역할이 없는 경우 역할을 부여합니다.

      1. 서비스 에이전트 옆에 있는 주 구성원 수정을 클릭합니다.
      2. 역할 추가를 클릭합니다.
      3. 검색창에 Kubernetes Default Node Service Agent를 입력하고 역할을 선택합니다.
      4. 저장을 클릭합니다.

   gcloud

   1. roles/container.defaultNodeServiceAgent 역할이 서비스 에이전트에 바인드되었는지 확인합니다.

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:[e-mail]"
      

      출력에서 roles/container.defaultNodeServiceAgent을 찾습니다.

   2. 역할이 누락된 경우 Kubernetes 기본 노드 서비스 에이전트 역할을 부여합니다.

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:[e-mail]" \
          --role="roles/container.defaultNodeServiceAgent"
      

리소스 및 성능 문제 해결

로그가 간헐적으로 누락되거나 트래픽이 많은 노드에서 삭제되는 경우 원인이 잘못된 구성이 아니라 성능 문제일 수 있습니다. 다음 섹션을 사용하여 프로젝트가 API 할당량을 초과하는지 또는 높은 로그 볼륨이 특정 노드의 에이전트를 압도하는지 조사합니다.

Cloud Logging API 할당량 사용량 조사

서비스를 보호하기 위해 Cloud Logging은 모든 프로젝트에 쓰기 할당량을 적용하여 Cloud Logging이 분당 수집할 수 있는 총 로그 볼륨을 제한합니다.

증상:

• 로그가 간헐적으로 또는 완전히 누락됩니다.
• 노드 또는 로깅 에이전트 로그에 logging.googleapis.com와 관련된 RESOURCE_EXHAUSTED 오류가 표시됩니다.

원인:

프로젝트가 Cloud Logging API 쓰기 요청 할당량을 초과합니다. 이 문제로 인해 로깅 에이전트가 로그를 전송할 수 없습니다.

해결 방법:

할당량 사용량을 확인하고 상향을 요청하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 할당량 페이지로 이동합니다.

   할당량으로 이동

2. 필터 필드에 Cloud Logging API을 입력하고 Enter 키를 누릅니다.

3. 필터링된 목록에서 클러스터가 있는 리전의 리전별 분당 로그 쓰기 바이트 할당량을 찾습니다.

4. 현재 사용량 백분율 열의 값을 검토합니다. 사용량이 한도에 도달하거나 한도에 근접하면 할당량을 초과한 것일 수 있습니다.

5. 상향을 요청하려면 할당량 수정을 클릭하고 메시지를 따르세요. 자세한 내용은 할당량 보기 및 관리를 참조하세요.

사용량을 줄이려면 로그를 제외하거나 애플리케이션에서 로그 상세도를 줄이는 것이 좋습니다. 한도에 도달하기 전에 알림을 받도록 알림 정책을 설정할 수도 있습니다.

노드 처리량 및 리소스 사용량 조사

각 노드의 GKE 로깅 에이전트에는 자체 처리량 한도가 있으며 이 한도를 초과할 수 있습니다.

증상:

특히 클러스터 활동이 많거나 노드 리소스 사용량이 많은 기간에 특정 노드의 로그가 간헐적으로 누락되거나 지연됩니다.

원인:

GKE 로깅 에이전트에는 기본 처리량 한도(노드당 약 100KBps)가 있습니다. 노드의 애플리케이션이 이 한도보다 빠르게 로그를 생성하면 프로젝트의 전체 API 할당량이 초과되지 않더라도 에이전트가 로그를 삭제할 수 있습니다. 측정항목 탐색기의 kubernetes.io/node/logs/input_bytes 측정항목을 사용하여 노드 로깅 처리량을 모니터링할 수 있습니다.

노드에 CPU 또는 메모리 압력이 심해 에이전트가 로그를 처리할 리소스가 부족한 경우에도 로그가 누락될 수 있습니다.

해결 방법:

처리량을 줄이려면 다음 옵션 중 하나를 선택하세요.

Standard 클러스터

다음 해결 방법을 시도해 보세요.

• 처리량이 높은 로깅 사용 설정: 이 기능은 노드당 용량을 늘립니다. 자세한 내용은 Cloud Logging 에이전트 처리량 조정을 참고하세요.

• 로그 볼륨 줄이기: 애플리케이션 로깅 패턴을 분석합니다. 불필요하거나 지나치게 장황한 로깅을 줄입니다.

• 커스텀 로깅 에이전트 배포: 맞춤설정된 Fluent Bit DaemonSet을 배포하고 관리할 수 있지만 구성 및 유지보수는 사용자의 책임입니다.

• 노드 리소스 사용량 확인: 로그 볼륨이 한도 내에 있더라도 노드에 CPU 또는 메모리 압력이 심하지 않은지 확인합니다. 노드 리소스가 부족하면 로깅 에이전트가 로그를 처리하고 전송하는 데 방해가 될 수 있습니다. 측정항목 탐색기에서 kubernetes.io/node/cpu/core_usage_time 및 kubernetes.io/node/memory/used_bytes과 같은 측정항목을 확인할 수 있습니다.

Autopilot 클러스터

다음 해결 방법을 시도해 보세요.

• 로그 볼륨 줄이기: 애플리케이션 로깅 패턴을 분석합니다. 불필요하거나 지나치게 장황한 로깅을 줄입니다. 이러한 유형의 로그는 효율적인 처리에 도움이 될 수 있으므로 가능한 경우 로그가 구조화되어 있는지 확인하세요. 필수적이지 않은 로그를 제외합니다.

• 애플리케이션 성능 최적화: Autopilot 클러스터에서 노드 리소스가 관리되므로 애플리케이션이 CPU나 메모리를 과도하게 사용하지 않도록 해야 합니다. 이는 로깅 에이전트와 같은 노드 구성요소의 성능에 간접적으로 영향을 미칠 수 있습니다. 노드를 직접 관리하지는 않지만 애플리케이션 효율성은 전반적인 노드 상태에 영향을 미칩니다.

필터링 및 애플리케이션 문제 해결

애플리케이션에서 로그를 생성했지만 Cloud Logging에 표시되지 않는 경우 필터링 또는 애플리케이션의 로깅 동작으로 인해 문제가 발생하는 경우가 많습니다. 다음 섹션에서는 로그 제외 필터, 컨테이너 수준 버퍼링, 제한적인 검색 쿼리, stdout 또는 stderr에 쓰지 않는 애플리케이션과 같은 문제를 살펴봅니다.

로그 제외 필터 조사

로그 탐색기에는 쿼리의 모든 필터 및 선택한 기간과 일치하는 로그만 표시됩니다.

증상:

특정 기준을 충족하는 특정 로그가 Cloud Logging에서 누락되었지만 동일한 소스의 다른 로그는 있습니다.

원인:

로그 제외 필터는 Cloud Logging 싱크 (일반적으로 _Default 싱크)에 정의됩니다. 이러한 규칙은 노드에서 성공적으로 전송된 경우에도 특정 기준과 일치하는 로그를 자동으로 삭제합니다.

해결 방법:

제외 필터를 검토하고 수정하려면 다음 옵션 중 하나를 선택하세요.

콘솔

1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

   로그 라우터로 이동

2. 문제가 있는 필터를 식별합니다.

   1. 제외 필터가 있을 수 없는 _Required 싱크를 제외한 각 싱크에 대해 작업 더보기를 클릭하고 싱크 세부정보 보기를 선택합니다.
   2. 제외 필터 섹션에서 쿼리를 검토합니다. 필터 로직을 누락된 로그의 속성 (예: 리소스 유형, 라벨 또는 키워드)과 비교합니다.
   3. 제외 필터 쿼리를 복사합니다.

   4. 로그 탐색기 페이지로 이동합니다.

      로그 탐색기로 이동

   5. 제외 필터 쿼리를 쿼리 창에 붙여넣고 쿼리 실행을 클릭합니다.

   6. 결과를 검토합니다. 표시된 로그는 필터에서 제외하는 항목입니다. 누락된 로그가 이러한 결과에 표시되면 이 필터가 원인일 수 있습니다.

3. 필터를 사용 중지하거나 수정합니다.

   1. 로그 라우터 페이지로 돌아갑니다.
   2. 의심스러운 필터가 있는 싱크의 작업 더보기를 클릭하고 싱크 수정을 선택합니다.
   3. 싱크에서 필터링할 로그 선택 섹션을 찾아 제외 필터를 찾습니다.
   4. 사용 중지를 클릭하여 필터를 사용 중지하거나 쿼리를 수정하여 더 구체적으로 만들 수 있습니다.
   5. 싱크 업데이트를 클릭합니다. 변경사항은 새 로그에 적용됩니다.

gcloud

1. 프로젝트의 모든 싱크를 나열합니다.

   gcloud logging sinks list --project=PROJECT_ID
   

2. 각 싱크의 제외 필터를 확인합니다.

   gcloud logging sinks describe SINK_NAME --project=PROJECT_ID
   

   출력에서 exclusions 섹션을 검토합니다. 필터 로직을 누락된 로그의 속성 (예: 리소스 유형, 라벨, 키워드)과 비교합니다.

3. 제외를 수정하려면 싱크의 구성을 업데이트하세요.

   1. 싱크의 구성을 로컬 파일 (예: sink-config.yaml)로 내보냅니다.

      gcloud logging sinks describe SINK_NAME \
          --format=yaml > sink-config.yaml
      

   2. 텍스트 편집기에서 sink-config.yaml 파일을 엽니다.

   3. exclusions: 섹션을 찾아 문제가 있는 필터를 삭제하거나 수정합니다.

   4. 수정된 싱크를 업데이트합니다.

      gcloud logging sinks update SINK_NAME sink-config.yaml \
          --project=PROJECT_ID
      

      이 명령어에 대한 자세한 내용은 gcloud logging sinks update 문서를 참고하세요.

컨테이너 로그 버퍼링 및 지연 조사

애플리케이션과 운영체제는 성능을 향상하기 위해 줄 단위가 아닌 청크 단위로 데이터를 쓰는 데 버퍼링을 사용하는 경우가 많습니다.

증상:

• 특정 컨테이너의 로그는 컨테이너가 종료된 후에만 Cloud Logging에 표시되거나 로그가 표시되는 데 상당한 지연이 있습니다.
• 경우에 따라 로그가 불완전합니다.

원인:

이 문제는 로그 버퍼링으로 인해 발생하는 경우가 많습니다. 표준 출력 (stdout)은 일반적으로 터미널에 연결될 때 라인 버퍼링되지만 출력이 파이프될 때는 이 동작이 변경됩니다. 컨테이너 내 애플리케이션의 로그 또는 시작 스크립트가 stdout를 다른 명령어 (예: my-app | grep ...)로 파이프하는 경우 출력이 완전히 버퍼링될 수 있습니다. 따라서 버퍼가 가득 차거나 파이프가 닫힐 때까지 로그가 보관됩니다. 이 동작으로 인해 컨테이너가 예기치 않게 종료되면 지연이나 데이터 손실이 발생할 수 있습니다. 애플리케이션 내부 버퍼링으로 인해 지연이 발생할 수도 있습니다.

해결 방법:

이 문제를 해결하려면 다음 해결 방법을 시도해 보세요.

• stdout 파이핑 방지: 가능한 경우 컨테이너 내에서 grep 또는 sed와 같은 다른 명령어를 통해 파이핑하지 않고 stdout 또는 stderr에 직접 로그를 작성하도록 컨테이너 진입점 또는 애플리케이션 명령어를 수정합니다.
• 라인 버퍼링 보장:
  • 파이핑을 피할 수 없는 경우 라인 버퍼링을 지원하는 도구를 사용하세요. 예를 들어 grep --line-buffered를 사용합니다.
  • 맞춤 애플리케이션의 경우 stdout에 쓸 때 각 줄 뒤에 이상적으로는 자주 로그를 플러시해야 합니다. 많은 로깅 라이브러리에는 버퍼링을 제어하는 설정이 있습니다.

• 버퍼링 동작 테스트: 다음 포드 매니페스트를 배포하고 kubectl logs -f buffered-pod 명령어를 사용하여 로그에서 효과를 관찰합니다. buffered-container 매니페스트에서 다양한 command 배열을 주석 처리하거나 주석 해제하여 실험합니다.

  # buffered.yaml
  apiVersion: v1
  kind: ConfigMap
  metadata:
  name: run-script
  data:
  run.sh: |
      #!/bin/bash
      echo "Starting..."
      for i in $(seq 3600); do
      echo "Log ${i}"
      sleep 1
      done
      echo "Exiting."
  ---
  apiVersion: v1
  kind: Pod
  metadata:
  name: buffered-pod
  spec:
  containers:
      - name: buffered-container
      image: ubuntu  # Or any other image with bash
  
      # Case 1: Direct execution - line buffered by default to TTY
      # Logs appear immediately.
      command: ['/bin/bash', '-c', '/mnt/run.sh']
  
      # Case 2: Piped to grep - fully buffered by default
      # Logs might be delayed or appear in chunks.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep Log']
  
      # Case 3: Piped to grep with --line-buffered
      # Logs appear immediately.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep --line-buffered Log']
  
      volumeMounts:
          - name: scripts
          mountPath: /mnt
  volumes:
      - name: scripts
      configMap:
          name: run-script
          defaultMode: 0777
  restartPolicy: Never
  

로그 탐색기 쿼리 조사

로그가 수집되고 있다고 확신하지만 로그를 찾을 수 없는 경우 검색어 또는 기간이 문제일 수 있습니다.

증상:

애플리케이션에서 로그를 생성하는 것을 알고 있지만 예상되는 로그가 검색 결과에 표시되지 않습니다.

원인:

로그 탐색기의 쿼리에 실수로 찾고 있는 로그를 제외하는 필터 (예: 네임스페이스, 라벨, 리소스 유형 또는 텍스트)가 있을 수 있습니다.

해결 방법:

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

   로그 탐색기로 이동

2. 기간 선택을 클릭합니다. 로그가 발생한 시간을 알고 있다고 생각하더라도 타이밍 문제를 배제하기 위해 훨씬 넓은 범위를 시도해 보세요.

3. 쿼리를 단순화합니다.

   1. 모든 필터를 지웁니다.

   2. 클러스터별로만 필터링해 보세요.

      resource.type="k8s_container"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      

      다음을 바꿉니다.

      • CLUSTER_NAME: 클러스터 이름입니다.
      • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)

   3. 쿼리 실행을 클릭합니다.

4. 광범위한 쿼리가 작동하면 원래 필터를 하나씩 다시 도입합니다.

   • 리소스 유형: 올바른 리소스 유형을 사용해야 합니다. 예를 들어 k8s_node로 필터링해야 하는데 k8s_container로 필터링하고 있나요?
   • 라벨: namespace_name, container_name 또는 맞춤 라벨과 같은 resource.labels의 맞춤법을 다시 확인합니다.
   • 심각도: 심각도 수준 (예: severity=ERROR)이 너무 제한적이지 않은지 확인합니다.
   • 텍스트 페이로드: 검색어에 맞춤법 오류와 지나치게 제한적인 문자열이 있는지 확인합니다. 예를 들어 정확한 일치 (jsonPayload.message="error" 대신 jsonPayload.message:"error")를 위해 =를 사용하는 대신 '포함'에 :를 사용합니다.

5. 필터에서 대소문자를 구분하는지 확인하고 (텍스트는 일반적으로 대소문자를 구분하지 않지만 라벨은 그렇지 않을 수 있음) 값에 숨겨진 문자나 추가 공백이 없는지 확인하고 특수문자가 있는 용어를 따옴표로 묶어야 하는지 확인합니다.

6. 타임라인을 검토합니다. 필터를 추가할 때 갑자기 감소하면 쿼리의 문제가 있는 부분을 식별하는 데 도움이 됩니다.

효과적인 로깅 쿼리에 관한 자세한 내용은 Cloud Logging 문서의 로그 항목 빨리 찾기를 참고하세요.

쿼리를 구체화한 후에도 로그를 찾을 수 없다면 쿼리가 문제가 아니라 이 문서의 다른 섹션에 설명된 문제일 수 있습니다.

애플리케이션별 로깅 동작 조사

GKE 로깅 에이전트는 stdout 및 stderr 스트림에 기록된 로그만 수집합니다.

증상:

클러스터의 다른 로그는 표시되지만 특정 포드 또는 컨테이너의 로그는 Cloud Logging에 표시되지 않습니다.

원인:

애플리케이션이 stdout 또는 stderr에 쓰지 않습니다. 로깅 에이전트가 수집할 수 없는 컨테이너 내부의 파일에 로그를 쓰도록 잘못 구성되었을 수 있습니다.

애플리케이션이 출력에서 JSON과 JSON이 아닌 텍스트를 혼합할 수도 있습니다. 로깅 에이전트의 파서는 단일 스트림에서 일관된 형식 (JSON 또는 텍스트)을 예상합니다. JSON 로깅용으로 구성된 애플리케이션이 일반 텍스트 줄을 출력하면 파서가 중단되어 로그가 삭제되거나 잘못 수집될 수 있습니다.

해결 방법:

1. 로그가 누락된 애플리케이션의 포드 이름과 네임스페이스를 확인합니다.

   kubectl get pods -n NAMESPACE_NAME
   

2. 컨테이너 로그를 확인합니다.

   • 포드에 컨테이너가 하나만 있는 경우 다음 명령어를 실행합니다.

     kubectl logs POD_NAME \
         -n NAMESPACE_NAME
     

     다음을 바꿉니다.

     • POD_NAME: 포드의 이름입니다.
     • NAMESPACE_NAME: 포드의 네임스페이스입니다.

   • 포드에 컨테이너가 여러 개 있는 경우 컨테이너 이름을 지정합니다.

     kubectl logs POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     CONTAINER_NAME을 포드 내 컨테이너의 이름으로 바꿉니다.

   • 로그를 실시간으로 확인하려면 다음 명령어를 실행합니다.

     kubectl logs -f POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     다음을 바꿉니다.

     • POD_NAME: 포드의 이름입니다.
     • CONTAINER_NAME: 포드 내 컨테이너의 이름입니다.
     • NAMESPACE_NAME: 포드의 네임스페이스입니다.

3. 출력을 분석합니다.

   • kubectl logs 명령어에 출력이 없거나 명령어 출력에 예상 로그가 포함되지 않으면 애플리케이션 자체에 문제가 있는 것입니다. kubectl logs 명령어는 컨테이너 런타임에서 캡처한 stdout 및 stderr 스트림에서 직접 읽습니다. 로그가 여기에 없으면 GKE의 로깅 에이전트가 로그를 볼 수 없습니다.

     파일에 쓰는 대신 모든 메시지를 stdout (일반 로그) 및 stderr (오류 로그)에 직접 로깅하도록 애플리케이션의 코드 또는 구성을 변경합니다.

   • JSON 문자열과 일반 텍스트 줄이 혼합되어 표시되면 혼합 형식 문제가 있는 것입니다. 유효한 단일 행 JSON 객체만 stdout 및 stderr에 작성하도록 애플리케이션을 구성합니다.

   • kubectl logs 명령어에 예상되는 로그가 표시되는 경우 문제는 로깅 파이프라인의 더 아래에 있을 가능성이 높습니다 (예: 에이전트, 권한 또는 Cloud Logging 서비스).

플랫폼 및 서비스 문제 해결

다음 섹션에서는 로그 보관 정책, Cloud Logging 상태, 지원되지 않는 GKE 버전 등 즉각적인 구성 외부의 문제를 조사하는 방법을 설명합니다.

로그 보관 기간 조사

로그는 버킷에 저장되며 각 버킷에는 로그가 자동으로 삭제되기 전에 보관되는 기간을 정의하는 보관 기간이 있습니다.

증상:

특정 날짜보다 오래된 로그가 누락되었습니다.

원인:

검색 중인 로그가 라우팅된 로그 버킷의 보관 기간보다 오래되었습니다.

해결 방법:

보관 기간을 식별하고 업데이트하려면 다음 옵션 중 하나를 선택합니다.

콘솔

1. GKE 로그가 라우팅되는 버킷을 식별합니다.

   1. Google Cloud 콘솔에서 로그 라우터 페이지로 이동합니다.

      로그 라우터로 이동

   2. 로그가 라우팅되는 위치를 보여주는 대상 열을 검토합니다.

      대상은 다음과 유사합니다.

      logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
      

      PROJECT_ID, LOCATION, BUCKET_ID를 확인합니다.

      로그는 _Default 버킷으로 라우팅되는 경우가 많지만 맞춤 싱크를 구성한 경우 다른 버킷으로 라우팅될 수도 있습니다.

2. 로그 버킷 보관 기간을 확인합니다.

   1. Google Cloud 콘솔에서 로그 스토리지 페이지로 이동합니다.

      로그 스토리지로 이동

   2. 싱크 대상에서 BUCKET_ID, LOCATION, PROJECT_ID와 일치하는 버킷을 찾습니다.

   3. 관련 버킷마다 보관 기간 열을 확인합니다.

   4. 보려는 로그가 보관 기간보다 오래된 경우 Cloud Logging에서 삭제한 것입니다. 더 긴 보관 기간이 필요한 경우 다음 단계를 따르세요.

      1. 보관 기간을 연장하려는 버킷에서 작업 더보기를 클릭합니다.
      2. 버킷 수정을 선택하고 보관 기간을 업데이트합니다. 잠재적인 비용 영향을 고려하세요.

gcloud

1. GKE 로그가 라우팅되는 버킷을 식별합니다.

   gcloud logging sinks list --project=PROJECT_ID
   

   출력을 검토합니다. 각 싱크의 destination 필드에는 로그가 라우팅되는 위치가 표시됩니다. 로그 버킷의 대상 형식은 다음과 같습니다.

   logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
   

   PROJECT_ID, LOCATION, BUCKET_ID를 확인합니다.

   로그는 _Default 버킷으로 라우팅되는 경우가 많습니다.

2. 로그 버킷 보관 기간을 확인합니다.

   gcloud logging buckets describe BUCKET_ID \
       --location=LOCATION \
       --project=PROJECT_ID
   

   출력에서 retentionDays 필드를 확인합니다. 필요한 로그가 retentionDays에 나열된 값보다 오래된 경우 Cloud Logging에서 삭제한 것입니다.

3. 더 긴 보관 기간이 필요한 경우 다음과 같이 업데이트합니다.

   gcloud logging buckets update BUCKET_ID \
       --location=LOCATION \
       --retention-days=RETENTION_DAYS \
       --project=PROJECT_ID
   

   다음을 바꿉니다.

   • BUCKET_ID: 로그 버킷의 ID
   • LOCATION: 버킷의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)
   • RETENTION_DAYS: 로그 보관 일수입니다. 보관 기간을 늘릴 경우 발생할 수 있는 비용을 고려하세요.
   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

Cloud Logging 서비스 문제 및 수집 지연 조사

경우에 따라 서비스 전체 중단이나 일시적인 대규모 수집 지연으로 인해 로깅 파이프라인 자체에 문제가 발생할 수 있습니다.

증상:

• 여러 프로젝트 또는 클러스터에서 광범위하거나 간헐적인 로그 손실이 발생합니다.
• 로그가 로그 탐색기에 표시되는 데 상당한 지연이 있습니다.

원인:

• Cloud Logging 서비스 중단: 드물지만 서비스 전반에 걸친 중단으로 인해 로그 수집이 방해되어 광범위한 지연 또는 전체 로그 손실이 발생할 수 있습니다.
• 로그 볼륨이 높음: 공식적인 중단이 없더라도 프로젝트 또는 리전의 로그 볼륨이 높으면 수집 서비스가 일시적으로 과부하되어 로그가 지연될 수 있습니다.

해결 방법:

• Google Cloud서비스 상태 대시보드를 방문하여 Google Cloud 서비스 상태를 확인하세요. Cloud Logging 또는 GKE와 관련된 미해결 인시던트가 있는지 확인합니다.

• 잠재적인 인제스트 지연을 고려합니다. 로그가 즉시 표시되지 않고 활성 인시던트가 없는 경우, 특히 로그 볼륨이 높은 경우 인제스트하는 데 시간이 걸릴 수 있습니다. 몇 분 후에 다시 확인해 보세요.

클러스터 버전 조사

GKE는 로깅 에이전트를 비롯한 구성요소의 버그 수정 및 성능 개선이 포함된 새 버전을 정기적으로 출시합니다.

증상:

로깅 문제는 클러스터 버전 제한과 관련이 있습니다.

원인:

클러스터가 알려진 로깅 에이전트 문제가 있거나 특정 로깅 기능이 없는 이전 버전 또는 지원되지 않는 GKE 버전을 실행하고 있을 수 있습니다.

해결 방법:

이 문제를 해결하려면 다음 단계를 따르세요.

1. 클러스터 버전을 확인합니다.

   gcloud container clusters describe CLUSTER_NAME \
       --location LOCATION \
       --format="value(currentMasterVersion)"
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 클러스터 이름입니다.
   • LOCATION: 클러스터의 Compute Engine 리전 또는 영역 (예: us-central1 또는 us-central1-a)

2. 지원되는 버전인지 확인하려면 이 버전을 GKE 출시 일정과 비교하세요.

3. 클러스터에서 지원되지 않는 버전을 사용하는 경우 클러스터를 업그레이드합니다.

다음 단계

• 문서에서 문제 해결 방법을 찾을 수 없으면 지원 받기를 참조하여 다음 주제에 대한 조언을 포함한 추가 도움을 요청하세요.

  • Cloud Customer Care에 문의하여 지원 케이스를 엽니다.
  • StackOverflow에서 질문하고 google-kubernetes-engine 태그를 사용하여 유사한 문제를 검색해 커뮤니티의 지원을 받습니다. #kubernetes-engine Slack 채널에 가입하여 더 많은 커뮤니티 지원을 받을 수도 있습니다.
  • 공개 Issue Tracker를 사용하여 버그나 기능 요청을 엽니다.