GKE 문제 해결 소개

이 페이지에서는 Google Kubernetes Engine (GKE)의 기본적인 문제 해결 기법을 소개합니다. 이 페이지는 효과적인 문제 해결 방법을 배우려는 Kubernetes 및 GKE 신규 사용자를 위한 것입니다.

이 페이지에서는 GKE 문제를 모니터링, 진단, 해결하기 위한 다음 도구와 기법을 간략하게 설명합니다.

핵심 개념 이해하기

Kubernetes와 GKE를 처음 사용하는 경우 문제 해결을 시작하기 전에 클러스터 아키텍처, 포드와 노드 간의 관계와 같은 핵심 개념을 이해하는 것이 중요합니다. 자세히 알아보려면 GKE 학습 시작하기를 참고하세요.

또한 GKE에서 유지관리할 책임이 있는 부분과 Google Cloud 유지관리할 책임이 있는 부분을 이해하는 것도 도움이 됩니다. 자세한 내용은 GKE 공유 책임을 참고하세요.

Google Cloud 콘솔에서 클러스터 및 워크로드 상태 검토

Google Cloud 콘솔은 클러스터 및 워크로드의 상태를 빠르게 확인할 수 있으므로 문제 해결을 시작하기에 적합합니다. 클러스터 상태는 노드, 네트워킹과 같은 기본 GKE 인프라의 상태를 나타내고, 워크로드 상태는 클러스터에서 실행되는 앱의 상태와 성능을 나타냅니다.

다음 섹션에서는 클러스터 및 워크로드 페이지를 설명합니다. 앱의 상태를 Google Cloud 완전히 파악할 수 있도록 콘솔에서는 강력한 로깅 및 모니터링 도구에 대한 액세스 권한도 제공하므로 과거 실패의 근본 원인을 조사하고 향후 실패를 사전 예방할 수 있습니다. 이러한 도구에 대한 자세한 내용은 Cloud Logging으로 기록 분석 수행 및 Cloud Monitoring으로 사전 모니터링 실행 섹션을 참고하세요.

클러스터 문제 찾기

Kubernetes 클러스터 페이지에서는 클러스터의 상태를 개략적으로 확인할 수 있습니다. 클러스터의 문제를 식별하려면 이 페이지에서 시작하세요.

다음은 이 페이지를 사용하여 문제를 해결하는 방법의 몇 가지 예입니다.

  • 클러스터 상태, 업그레이드 전략, 비용 최적화 개선에 관한 조언을 보려면 추천 보기를 클릭하세요.
  • 비정상 클러스터를 식별하려면 상태 열을 검토하세요. 녹색 체크표시가 없는 클러스터에는 주의가 필요합니다.
  • 잠재적인 문제를 확인하려면 알림 열을 검토하세요. 자세한 내용을 보려면 알림 메시지를 클릭하세요.

특정 클러스터 조사

클러스터에 문제가 있는 것을 발견한 후 클러스터의 세부정보 페이지를 살펴보고 클러스터 문제를 해결하고 구성을 이해하는 데 도움이 되는 자세한 정보를 확인하세요.

클러스터의 세부정보 페이지로 이동하려면 다음 단계를 따르세요.

  1. Kubernetes 클러스터 페이지로 이동합니다.

    Kubernetes 클러스터로 이동

  2. 이름 열을 검토하고 조사할 클러스터의 이름을 클릭합니다.

다음은 클러스터 세부정보 페이지를 사용하여 클러스터 문제를 해결하는 방법의 몇 가지 예입니다.

  • 일반 상태 점검의 경우 다음 옵션을 시도해 보세요.

    • 클러스터 수준 대시보드를 보려면 모니터링 가능성 탭으로 이동합니다. 기본적으로 GKE는 클러스터를 만들 때 Cloud Monitoring을 사용 설정합니다. Cloud Monitoring이 사용 설정되면 GKE가 이 페이지에 대시보드를 자동으로 설정합니다. 문제 해결에 가장 유용할 수 있는 보기는 다음과 같습니다.

      • 개요: 클러스터의 상태, 리소스 사용률, 주요 이벤트의 개략적인 요약을 볼 수 있습니다. 이 대시보드를 사용하면 클러스터의 전반적인 상태를 빠르게 평가하고 잠재적인 문제를 식별할 수 있습니다.
      • 트래픽 측정항목: 노드 기반 네트워킹 측정항목을 보고 Kubernetes 워크로드 간 트래픽에 대한 인사이트를 얻으세요.
      • 워크로드 상태: 배포, 포드, 컨테이너의 상태를 확인합니다. 실패하거나 비정상 인스턴스를 식별하고 리소스 제약 조건을 감지합니다.

      • 컨트롤 플레인: 컨트롤 플레인의 상태와 성능을 확인합니다. 이 대시보드를 사용하면 kube-apiserver, etcd과 같은 구성요소의 주요 측정항목을 모니터링하고, 성능 병목 현상을 파악하고, 구성요소 장애를 감지할 수 있습니다.

    • 최근 앱 오류를 보려면 앱 오류 탭으로 이동합니다. 이 탭의 정보는 발생 횟수, 오류가 처음 표시된 시간, 마지막으로 발생한 시간을 보여주어 오류의 우선순위를 정하고 오류를 해결하는 데 도움이 됩니다.

      오류를 자세히 조사하려면 오류 메시지를 클릭하여 관련 로그 링크를 포함한 자세한 오류 보고서를 확인하세요.

  • 최근 업그레이드 또는 변경 후 문제를 해결하는 경우 클러스터 세부정보 탭의 클러스터 기본사항 섹션을 확인하세요. 버전 필드에 나열된 버전이 예상한 버전인지 확인합니다. 자세히 조사하려면 업그레이드 섹션에서 업그레이드 기록 표시를 클릭합니다.

  • Standard 클러스터를 사용 중이고 포드가 Pending 상태에서 멈추거나 노드가 과부하된 것으로 의심되는 경우 노드 탭을 확인합니다. GKE에서 노드를 관리하므로 Autopilot 클러스터에는 노드 탭이 제공되지 않습니다.

    • 노드 풀 섹션에서 자동 확장 기능이 올바르게 구성되어 있고 머신 유형이 워크로드에 적합한지 확인합니다.
    • 노드 섹션에서 상태가 Ready가 아닌 노드를 찾습니다. NotReady 상태는 리소스 압력이나 kubelet 문제 (kubelet은 컨테이너를 관리하기 위해 각 노드에서 실행되는 에이전트임)와 같은 노드 자체의 문제를 나타냅니다.

워크로드 문제 찾기

배포 실패와 같은 특정 앱에 문제가 있다고 의심되는 경우 Google Cloud 콘솔의 워크로드 페이지로 이동합니다. 이 페이지에서는 클러스터 내에서 실행되는 모든 앱을 중앙에서 확인할 수 있습니다.

다음은 이 페이지를 사용하여 문제를 해결하는 방법의 몇 가지 예입니다.

  • 비정상 워크로드를 식별하려면 상태 열을 검토합니다. 녹색 체크표시가 없는 워크로드에는 주의가 필요합니다.
  • 앱이 응답하지 않으면 포드 열을 검토합니다. 예를 들어 1/3과 같은 상태는 3개의 앱 복제본 중 하나만 실행되고 있음을 의미하며 이는 문제가 있음을 나타냅니다.

특정 워크로드 조사

개요에서 문제가 있는 워크로드를 확인한 후 워크로드 세부정보 페이지를 살펴보고 근본 원인을 파악합니다.

워크로드의 세부정보 페이지로 이동하려면 다음 단계를 따르세요.

  1. 워크로드 페이지로 이동합니다.

    워크로드로 이동

  2. 이름 열을 확인하고 조사할 워크로드의 이름을 클릭합니다.

워크로드 세부정보 페이지를 사용하여 워크로드 문제를 해결하는 방법의 몇 가지 예는 다음과 같습니다.

  • 워크로드의 구성을 확인하려면 워크로드 개요 및 세부정보 탭을 사용합니다. 이 정보를 사용하여 올바른 컨테이너 이미지 태그가 배포되었는지와 같은 이벤트를 확인하거나 워크로드의 리소스 요청 및 제한을 확인할 수 있습니다.

  • 비정상 종료되는 특정 포드의 이름을 찾으려면 관리형 포드 섹션으로 이동합니다. kubectl 명령어에 이 정보가 필요할 수 있습니다. 이 섹션에는 워크로드에 의해 제어되는 모든 포드와 해당 상태가 나열됩니다. 워크로드의 최근 변경사항 내역을 보려면 업데이트 기록 탭으로 이동하세요. 새 배포 후 성능 문제가 발생하면 이 섹션을 사용하여 활성 버전이 무엇인지 확인하세요. 그런 다음 현재 버전의 구성을 이전 버전과 비교하여 문제의 원인을 파악할 수 있습니다. 이 탭이 표시되지 않으면 워크로드가 버전을 사용하지 않는 유형이거나 아직 업데이트가 없는 것입니다.

  • 배포가 실패한 것 같으면 이벤트 탭으로 이동합니다. 이 페이지는 Kubernetes 수준 이벤트를 표시하므로 가장 유용한 정보 소스인 경우가 많습니다.

  • 앱의 로그를 보려면 로그 탭을 클릭합니다. 이 페이지에서는 클러스터 내부에서 어떤 일이 일어나고 있는지 파악할 수 있습니다. 여기에서 문제를 진단하는 데 도움이 되는 오류 메시지와 스택 트레이스를 확인하세요.

  • 배포된 항목을 정확하게 확인하려면 YAML 탭을 확인하세요. 이 페이지에는 클러스터에 있는 워크로드의 라이브 YAML 매니페스트가 표시됩니다. 이 정보는 소스 제어 매니페스트와의 불일치를 찾는 데 유용합니다. 단일 포드의 YAML 매니페스트를 보는 경우 이 탭에는 포드의 상태도 표시되므로 포드 수준 실패에 관한 유용한 정보를 확인할 수 있습니다.

kubectl 명령줄 도구로 클러스터 상태 조사

Google Cloud 콘솔을 사용하면 문제가 있는지 파악할 수 있지만 kubectl 명령줄 도구는 이유를 파악하는 데 필수적입니다. Kubernetes 제어 영역과 직접 통신하는 kubectl 명령줄 도구를 사용하면 GKE 환경 문제를 해결하는 데 필요한 세부정보를 수집할 수 있습니다.

다음 섹션에서는 GKE 문제 해결을 위한 강력한 시작점이 되는 몇 가지 필수 명령어를 소개합니다.

시작하기 전에

시작하기 전에 다음 작업을 수행하세요.

  • kubectl을 설치합니다.

  • 클러스터와 통신하도록 kubectl 명령줄 도구를 구성합니다.

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    다음을 바꿉니다.

    • CLUSTER_NAME: 클러스터 이름입니다.
    • LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 위치입니다. 리전 클러스터의 경우 리전을, 영역 클러스터의 경우 영역을 제공합니다.

  • 권한을 검토합니다. kubectl 명령어를 실행하는 데 필요한 권한이 있는지 확인하려면 kubectl auth can-i 명령어를 사용하세요. 예를 들어 kubectl get nodes를 실행할 권한이 있는지 확인하려면 kubectl auth can-i get nodes 명령어를 실행합니다.

    필요한 권한이 있는 경우 명령어는 yes를 반환하고, 그렇지 않으면 no를 반환합니다.

    kubectl 명령어를 실행할 권한이 없으면 다음과 유사한 오류 메시지가 표시될 수 있습니다.

    Error from server (Forbidden): pods "POD_NAME" is forbidden: User
"USERNAME@DOMAIN.com" cannot list resource "pods" in API group "" in the
namespace "default"

    필요한 권한이 없으면 클러스터 관리자에게 필요한 역할을 할당해 달라고 요청하세요.

실행 중인 항목 개요 확인

kubectl get 명령어를 사용하면 클러스터에서 발생하는 상황을 전반적으로 파악할 수 있습니다. 다음 명령어를 사용하여 가장 중요한 클러스터 구성요소인 노드와 포드의 상태를 확인합니다.

  1. 노드가 정상인지 확인하려면 모든 노드와 해당 상태에 관한 세부정보를 확인하세요.

    kubectl get nodes

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

    NAME                                        STATUS   ROLES    AGE     VERSION

gke-cs-cluster-default-pool-8b8a777f-224a   Ready    <none>   4d23h   v1.32.3-gke.1785003
gke-cs-cluster-default-pool-8b8a777f-egb2   Ready    <none>   4d22h   v1.32.3-gke.1785003
gke-cs-cluster-default-pool-8b8a777f-p5bn   Ready    <none>   4d22h   v1.32.3-gke.1785003

    Ready 이외의 상태는 추가 조사가 필요합니다.

  2. 포드가 정상인지 확인하려면 모든 포드와 해당 상태에 관한 세부정보를 확인하세요.

    kubectl get pods --all-namespaces

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

    NAMESPACE   NAME       READY   STATUS      RESTARTS   AGE
kube-system netd-6nbsq 3/3     Running     0          4d23h
kube-system netd-g7tpl 3/3     Running     0          4d23h

    Running 이외의 상태는 추가 조사가 필요합니다. 다음은 일반적으로 표시되는 상태입니다.

    • Running: 정상적으로 실행되는 상태입니다.
    • Pending: 포드가 노드에 예약되기를 기다리고 있습니다.
    • CrashLoopBackOff: 앱이 시작되고 오류와 함께 종료된 후 Kubernetes에 의해 다시 시작되기 때문에 포드의 컨테이너가 루프에서 반복적으로 비정상 종료됩니다.
    • ImagePullBackOff: 포드에서 컨테이너 이미지를 가져올 수 없습니다.

위 명령어는 kubectl get 명령어를 사용하는 방법의 두 가지 예일 뿐입니다. 이 명령어를 사용하여 다양한 유형의 Kubernetes 리소스에 대해 자세히 알아볼 수도 있습니다. 탐색할 수 있는 리소스의 전체 목록은 Kubernetes 문서의 kubectl get을 참고하세요.

특정 리소스 자세히 알아보기

문제를 파악한 후에는 세부정보를 확인해야 합니다. 문제의 예로는 상태가 Running이 아닌 포드가 있습니다. 자세한 내용을 확인하려면 kubectl describe 명령어를 사용하세요.

예를 들어 특정 포드를 설명하려면 다음 명령어를 실행합니다.

kubectl describe pod POD_NAME -n NAMESPACE_NAME

다음을 바꿉니다.

  • POD_NAME: 문제가 발생한 포드의 이름입니다.
  • NAMESPACE_NAME: 포드가 있는 네임스페이스입니다. 네임스페이스를 잘 모르겠다면 kubectl get pods 명령어의 출력에서 Namespace 열을 검토하세요.

kubectl describe 명령어의 출력에는 리소스에 관한 세부정보가 포함됩니다. 다음은 Pod 문제를 해결할 때 검토하면 가장 도움이 되는 섹션입니다.

  • Status: 포드의 현재 상태입니다.
  • Conditions: 포드의 전반적인 상태 및 준비 상태입니다.
  • Restart Count: 포드의 컨테이너가 다시 시작된 횟수입니다. 높은 수치는 우려의 원인이 될 수 있습니다.
  • Events: 노드에 예약되고, 컨테이너 이미지를 가져오고, 오류가 발생했는지 등 이 포드에 발생한 중요한 사항의 로그입니다. Events 섹션에는 포드가 실패하는 이유에 대한 직접적인 단서가 있는 경우가 많습니다.

kubectl get 명령어와 마찬가지로 kubectl describe 명령어를 사용하여 여러 유형의 리소스에 대해 자세히 알아볼 수 있습니다. 탐색할 수 있는 리소스의 전체 목록은 Kubernetes 문서의 kubectl describe를 참고하세요.

Cloud Logging으로 기록 분석 실행

kubectl 명령줄 도구는 Kubernetes 객체의 실시간 상태를 검사하는 데 매우 유용하지만 보기가 현재 시점으로 제한되는 경우가 많습니다. 문제의 근본 원인을 파악하려면 시간에 따라 발생한 상황을 조사해야 하는 경우가 많습니다. 이전 컨텍스트가 필요한 경우 Cloud Logging을 사용하세요.

Cloud Logging은 GKE 클러스터, 컨테이너화된 앱, 기타 Google Cloud 서비스의 로그를 집계합니다.

문제 해결을 위한 주요 로그 유형 이해하기

Cloud Logging은 문제 해결에 도움이 되는 여러 유형의 GKE 로그를 자동으로 수집합니다.

  • 노드 및 런타임 로그 (kubelet, containerd): 기본 노드 서비스의 로그입니다. kubelet는 노드의 모든 포드의 수명 주기를 관리하므로 컨테이너 시작, 메모리 부족 (OOM) 이벤트, 프로브 실패, 볼륨 마운트 오류와 같은 문제를 해결하는 데 로그가 필수적입니다. 이러한 로그는 NotReady 상태인 노드와 같은 노드 수준 문제를 진단하는 데도 중요합니다.

    containerd는 이미지를 가져오는 것을 비롯해 컨테이너의 수명 주기를 관리하므로 kubelet이 컨테이너를 시작하기 전에 발생하는 문제를 해결하는 데 로그가 중요합니다. containerd 로그는 컨테이너 런타임의 구체적인 활동과 잠재적인 오류를 문서화하므로 GKE에서 노드 수준 문제를 진단하는 데 도움이 됩니다.

  • 앱 로그 (stdout, stderr): 컨테이너화된 프로세스의 표준 출력 및 오류 스트림입니다. 이러한 로그는 비정상 종료, 오류, 예기치 않은 동작과 같은 앱 관련 문제를 디버깅하는 데 필수적입니다.

  • 감사 로그: 이러한 로그는 클러스터에 대해 '누가 언제 어디서 무엇을 했는지'에 대한 답을 제공합니다. 구성 변경 또는 무단 액세스로 인해 발생하는 문제를 진단하는 데 유용한 Kubernetes API 서버에 대한 관리 작업 및 API 호출을 추적합니다.

일반적인 문제 해결 시나리오

문제를 식별한 후 이러한 로그를 쿼리하여 발생한 상황을 확인할 수 있습니다. 시작하는 데 도움이 되도록 로그를 검토하면 다음 문제를 해결하는 데 도움이 됩니다.

  • 노드 상태가 NotReady이면 노드 로그를 검토합니다. kubelet 및 containerd 로그는 네트워크 문제나 리소스 제약과 같은 근본 원인을 자주 보여줍니다.
  • 새 노드가 프로비저닝되고 클러스터에 가입되지 않으면 노드의 직렬 포트 로그를 검토하세요. 이러한 로그는 노드의 로깅 에이전트가 완전히 활성화되기 전의 초기 부팅 및 kubelet 시작 활동을 캡처합니다.
  • 이전에 포드가 시작되지 않은 경우 해당 포드의 앱 로그를 검토하여 비정상 종료가 있는지 확인합니다. 로그가 비어 있거나 포드를 예약할 수 없는 경우 감사 로그에서 관련 이벤트를 확인하거나 타겟 노드의 노드 로그에서 리소스 압력 또는 이미지 가져오기 오류에 관한 단서를 확인합니다.
  • 중요한 배포가 삭제되었는데 이유를 모르는 경우 관리자 활동 감사 로그를 쿼리합니다. 이러한 로그는 삭제 API 호출을 실행한 사용자 또는 서비스 계정을 식별하는 데 도움이 되므로 조사를 시작할 명확한 지점을 제공합니다.

로그에 액세스하는 방법

로그 탐색기를 사용하여 Google Cloud 콘솔에서 GKE 로그를 쿼리, 보기, 분석합니다. 로그 탐색기는 문제를 격리하는 데 도움이 되는 강력한 필터링 옵션을 제공합니다.

로그 탐색기에 액세스하고 사용하려면 다음 단계를 완료하세요.

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

    로그 탐색기로 이동

  2. 쿼리 창에 쿼리를 입력합니다. Logging 쿼리 언어를 사용하여 타겟팅된 쿼리를 작성합니다. 시작하는 데 도움이 되는 몇 가지 일반적인 필터는 다음과 같습니다.

    필터 유형 설명 예시 값
    resource.type Kubernetes 리소스의 유형입니다. k8s_cluster, k8s_node, k8s_pod, k8s_container
    log_id 리소스의 로그 스트림입니다. stdout, stderr
    resource.labels.RESOURCE_TYPE.name 특정 이름이 있는 리소스를 필터링합니다.
    RESOURCE_TYPE을 쿼리하려는 리소스의 이름으로 바꿉니다. 예를 들면 namespace 또는 pod입니다.    		 example-namespace-name, example-pod-name
    severity 로그 심각도 수준입니다. DEFAULT, INFO, WARNING, ERROR, CRITICAL
    jsonPayload.message=~ 로그 메시지 내 텍스트에 대한 정규 표현식 검색입니다. scale.down.error.failed.to.delete.node.min.size.reached

    예를 들어 특정 포드의 문제를 해결하려면 오류 로그를 격리해야 할 수 있습니다. 해당 포드의 심각도가 ERROR인 로그만 보려면 다음 쿼리를 사용하세요.

    resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
resource.labels.namespace_name="NAMESPACE_NAME"
severity=ERROR

    다음을 바꿉니다.

    • POD_NAME: 문제가 발생한 포드의 이름입니다.
    • NAMESPACE_NAME: 포드가 있는 네임스페이스입니다. 네임스페이스를 잘 모르겠다면 kubectl get pods 명령어의 출력에서 Namespace 열을 검토하세요.

    자세한 예는 Google Cloud Observability 문서의 Kubernetes 관련 쿼리를 참고하세요.

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

  4. JSON 페이로드, 메타데이터, 타임스탬프를 비롯한 전체 로그 메시지를 보려면 로그 항목을 클릭합니다.

GKE 로그에 대한 자세한 내용은 GKE 로그 정보를 참고하세요.

Cloud Monitoring으로 사전 모니터링 실행

문제가 발생한 후 로그를 검토하는 것은 문제 해결에 있어 중요한 단계입니다. 하지만 진정으로 복원력이 있는 시스템에는 장애가 발생하기 전에 문제를 식별하는 사전 대응 방식도 필요합니다.

향후 문제를 사전 예방적으로 식별하고 시간 경과에 따른 주요 실적 지표를 추적하려면 Cloud Monitoring을 사용하세요. Cloud Monitoring은 대시보드, 측정항목, 알림 기능을 제공합니다. 이러한 도구를 사용하면 오류율 증가, 지연 시간 증가, 리소스 제약 조건을 파악하여 사용자가 영향을 받기 전에 조치를 취할 수 있습니다.

유용한 측정항목 검토

GKE는 측정항목 집합을 Cloud Monitoring으로 자동 전송합니다. 다음 섹션에는 문제 해결에 가장 중요한 측정항목이 나열되어 있습니다.

GKE 측정항목의 전체 목록은 GKE 시스템 측정항목을 참고하세요.

컨테이너 성능 및 상태 측정항목

특정 앱에 문제가 있다고 의심되는 경우 이러한 측정항목부터 시작하세요. 이러한 측정항목은 컨테이너가 자주 다시 시작되는지, 메모리가 부족한지, CPU 제한으로 인해 제한되는지 등을 파악하여 앱의 상태를 모니터링하는 데 도움이 됩니다.

측정항목 설명 문제 해결의 중요성
kubernetes.io/container/cpu/limit_utilization 현재 인스턴스에서 사용 중인 CPU 한도의 비율입니다. 컨테이너가 CPU 한도를 초과할 수 있으므로 이 값은 1을 초과할 수 있습니다. CPU 제한을 식별합니다. 값이 높으면 성능이 저하될 수 있습니다.
kubernetes.io/container/memory/limit_utilization 현재 인스턴스에서 사용 중인 메모리 한도의 비율입니다. 이 값은 1을 초과할 수 없습니다. OutOfMemory (OOM) 오류 위험을 모니터링합니다.
kubernetes.io/container/memory/used_bytes 컨테이너에서 실제로 사용한 메모리(바이트)입니다. 메모리 소비를 추적하여 잠재적인 메모리 누수 또는 OOM 오류 위험을 식별합니다.
kubernetes.io/container/memory/page_fault_count 유형(주 오류 및 부 오류)별로 분류된 페이지 오류 수입니다. 상당한 메모리 압력을 나타냅니다. 심각한 페이지 오류는 메모리 한도에 도달하지 않았더라도 메모리가 디스크에서 읽히고 있음을 의미합니다 (스왑).
kubernetes.io/container/restart_count 컨테이너에서 재시작한 횟수입니다. 앱 비정상 종료, 구성 오류, 다시 시작 횟수 증가로 인한 리소스 소진과 같은 잠재적인 문제를 강조합니다.
kubernetes.io/container/ephemeral_storage/used_bytes 로컬 임시 스토리지 사용량(단위: 바이트)입니다. 임시 스토리지가 가득 차서 포드가 삭제되는 것을 방지하기 위해 임시 디스크 사용량을 모니터링합니다.
kubernetes.io/container/cpu/request_utilization 현재 인스턴스에서 사용 중인 요청 CPU의 비율입니다. 사용량이 요청을 초과할 수 있으므로 이 값은 1을 초과할 수 있습니다. 리소스 할당을 최적화할 수 있도록 과다 또는 과소 프로비저닝된 CPU 요청을 식별합니다.
kubernetes.io/container/memory/request_utilization 현재 인스턴스에서 사용 중인 요청 메모리의 비율입니다. 사용량이 요청을 초과할 수 있으므로 이 값은 1을 초과할 수 있습니다. 과도하게 프로비저닝되거나 부족하게 프로비저닝된 메모리 요청을 식별하여 일정을 개선하고 OOM 오류를 방지합니다.

노드 성능 및 상태 측정항목

기본 GKE 인프라 문제를 진단해야 하는 경우 이러한 측정항목을 검사하세요. 이러한 측정항목은 노드의 전반적인 상태와 용량을 파악하는 데 중요하며, 노드가 비정상적이거나 압박을 받고 있는지 또는 노드에 새 포드를 예약할 메모리가 충분한지 조사하는 데 도움이 됩니다.

측정항목 설명 문제 해결의 중요성
kubernetes.io/node/cpu/allocatable_utilization 현재 인스턴스에서 사용 중인 할당 가능한 CPU의 비율입니다. 포드 사용량의 합계가 노드의 사용 가능한 CPU 리소스에 부담을 주고 있는지 나타냅니다.
kubernetes.io/node/memory/allocatable_utilization 현재 인스턴스에서 사용 중인 할당 가능한 메모리의 비율입니다. 사용량이 할당 가능한 메모리 바이트를 초과할 수 없으므로 이 값은 1을 초과할 수 없습니다. 특히 값이 높은 경우 새 포드를 예약하거나 기존 포드가 작동하는 데 노드에 메모리가 부족함을 나타냅니다.
kubernetes.io/node/status_condition (베타) 노드 상태 조건 필드의 노드 조건입니다. Ready, MemoryPressure, DiskPressure과 같은 노드 상태 조건을 보고합니다.
kubernetes.io/node/ephemeral_storage/used_bytes 노드에서 사용한 로컬 임시 스토리지 바이트입니다. 높은 임시 저장소 사용량에 관한 경고를 제공하여 포드 시작 실패 또는 제거를 방지합니다.
kubernetes.io/node/ephemeral_storage/inodes_free 로컬 임시 스토리지의 여유 색인 노드 (아이노드) 수입니다. 여유 아이노드 수를 모니터링합니다. 아이노드가 부족하면 디스크 공간이 있어도 작업이 중단될 수 있습니다.
kubernetes.io/node/interruption_count (베타) 중단은 고객이 인프라를 제어하는 동안 발생하는 인프라의 시스템 퇴출입니다. 이 측정항목은 유형 및 이유별 현재 인터럽트 수입니다. 시스템 퇴출로 인해 노드가 예기치 않게 사라질 수 있는 이유를 설명합니다.

Pod 성능 및 상태 측정항목

이러한 측정항목은 네트워킹, 스토리지 등 포드의 환경과의 상호작용과 관련된 문제를 해결하는 데 도움이 됩니다. 시작이 느린 포드를 진단하거나, 잠재적인 네트워크 연결 문제를 조사하거나, 쓰기 실패를 방지하기 위해 스토리지 볼륨을 사전 예방적으로 관리해야 하는 경우 이러한 측정항목을 사용하세요.

측정항목 설명 문제 해결의 중요성
kubernetes.io/pod/network/received_bytes_count 네트워크를 통해 Pod에서 수신한 누적 바이트 수입니다. 앱 또는 네트워크 문제를 나타낼 수 있는 비정상적인 네트워크 활동 (높음 또는 낮음)을 식별합니다.
kubernetes.io/pod/network/policy_event_count (베타) 데이터 플레인에 표시되는 네트워크 정책 이벤트 수의 변화 네트워크 정책으로 인해 발생하는 연결 문제를 식별합니다.
kubernetes.io/pod/volume/utilization 현재 인스턴스에서 사용 중인 볼륨의 비율입니다. 사용량이 제공되는 총 볼륨 공간을 초과할 수 없으므로 이 값은 1을 초과할 수 없습니다. 높은 사용률 (1에 가까움)로 인해 쓰기 실패가 발생할 수 있는 경우 경고를 표시하여 볼륨 공간을 사전 관리할 수 있습니다.
kubernetes.io/pod/latencies/pod_first_ready (베타) 이미지 풀을 포함한 포드 전체 시작 지연 시간 (포드 생성부터 준비까지)입니다. 시작이 느린 포드를 진단합니다.

측정항목 탐색기로 측정항목 시각화

GKE 환경의 상태를 시각화하려면 측정항목 탐색기로 측정항목을 기반으로 차트를 만드세요.

측정항목 탐색기를 사용하려면 다음 단계를 완료하세요.

  1. Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.

    측정항목 탐색기로 이동

  2. 측정항목 필드에서 검사할 측정항목을 선택하거나 입력합니다.

  3. 결과를 확인하고 시간 경과에 따른 추세를 관찰합니다.

예를 들어 특정 네임스페이스의 포드 메모리 소비를 조사하려면 다음을 실행하면 됩니다.

  1. 측정항목 선택 목록에서 kubernetes.io/container/memory/used_bytes 측정항목을 선택하고 적용을 클릭합니다.
  2. 필터 추가를 클릭하고 namespace_name을 선택합니다.
  3. 값 목록에서 조사할 네임스페이스를 선택합니다.
  4. 집계 필드에서 합계 > pod_name을 선택하고 확인을 클릭합니다. 이 설정을 사용하면 각 포드에 별도의 시계열 선이 표시됩니다.
  5. 차트 저장을 클릭합니다.

결과 차트에는 시간 경과에 따른 각 포드의 메모리 사용량이 표시되므로 메모리 소비가 비정상적으로 높거나 급증하는 포드를 시각적으로 식별할 수 있습니다.

측정항목 탐색기는 보려는 측정항목을 구성하는 데 매우 유연합니다. 고급 측정항목 탐색기 옵션에 대한 자세한 내용은 Cloud 모니터링 문서의 측정항목 탐색기로 차트 만들기를 참고하세요.

사전 문제 감지를 위한 알림 만들기

문제가 발생하거나 측정항목이 특정 기준을 위반할 때 알림을 받으려면 Cloud Monitoring에서 알림 정책을 설정하세요.

예를 들어 컨테이너 CPU 한도가 5분 동안 80% 를 초과할 때 알림을 보내는 알림 정책을 설정하려면 다음을 수행하세요.

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

    알림으로 이동

  2. 정책 만들기를 클릭합니다.

  3. 측정항목 선택 상자에서 CPU limit utilization를 필터링한 다음 kubernetes.io/container/cpu/limit_utilization 측정항목을 선택합니다.

  4. 적용을 클릭합니다.

  5. 필터 추가 필드는 비워둡니다. 이 설정은 클러스터가 기준을 위반할 때 알림을 트리거합니다.

  6. 변환 데이터 섹션에서 다음을 선택합니다.

    1. 순환 기간 목록에서 1분을 선택합니다. 이 설정은 Google Cloud 가 매분 평균값을 계산한다는 의미입니다.

    2. 순환 기간 함수 목록에서 평균을 선택합니다.

      두 설정 모두 매분 각 컨테이너의 CPU 한도 사용률을 평균합니다.

  7. 다음을 클릭합니다.

  8. 알림 구성 섹션에서 다음을 수행합니다.

    1. 조건 유형에서 임곗값을 선택합니다.
    2. 알림 트리거에서 모든 시계열 위반을 선택합니다.
    3. 기준 위치에서 기준 초과를 선택합니다.
    4. 기준 값에 0.8을 입력합니다. 이 값은 모니터링하려는 80% 기준점을 나타냅니다.
    5. 고급 옵션을 클릭합니다.
    6. 재테스트 기간 목록에서 5분을 선택합니다. 이 설정은 CPU 사용률이 5분 동안 연속으로 80%를 초과하는 경우에만 알림이 트리거되므로 짧은 급증으로 인한 잘못된 알림이 줄어듭니다.
    7. 조건 이름 필드에 조건의 이름을 입력합니다.
    8. 다음을 클릭합니다.

  9. 알림 구성 및 알림 완료 섹션에서 다음을 수행합니다.

    1. 알림 채널 목록에서 알림을 받을 채널을 선택합니다. 채널이 없으면 알림 채널 관리를 클릭하여 만듭니다.
    2. 알림 정책 이름 지정 필드에 정책을 명확하게 설명하는 이름을 지정합니다.
    3. 다른 필드는 모두 기본값 그대로 둡니다.
    4. 다음을 클릭합니다.

  10. 정책을 검토하고 모든 것이 올바른 것으로 확인되면 정책 만들기를 클릭합니다.

알림을 만드는 다른 방법을 알아보려면 Cloud Monitoring 문서의 알림 개요를 참고하세요.

Gemini Cloud Assist로 진단 속도 높이기

이전 섹션에서 설명한 도구를 사용한 경우에도 문제의 원인이 바로 명확하지 않은 경우가 있습니다. 복잡한 케이스를 조사하는 데는 시간이 오래 걸릴 수 있으며 깊이 있는 전문 지식이 필요합니다. 이러한 시나리오에서는 Gemini Cloud Assist가 도움이 될 수 있습니다. 숨겨진 패턴을 자동으로 감지하고, 이상치를 표시하고, 요약을 제공하여 원인을 빠르게 파악할 수 있습니다.

Gemini Cloud Assist 액세스

Gemini Cloud Assist에 액세스하려면 다음 단계를 완료하세요.

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

  2. Google Cloud 콘솔 툴바에서 spark Gemini Cloud Assist 채팅 열기 또는 닫기를 클릭합니다.

    Cloud Assist 패널이 열립니다. 프롬프트 예시가 표시되면 이 예시를 클릭하거나 프롬프트 입력 필드에 프롬프트를 입력할 수 있습니다.

프롬프트 예시 살펴보기

Gemini Cloud Assist가 어떻게 도움이 되는지 이해할 수 있도록 몇 가지 프롬프트 예시를 소개합니다.

테마 시나리오 프롬프트 예시 Gemini Cloud Assist의 이점
혼동을 야기하는 오류 메시지 포드의 상태가 CrashLoopBackoff이지만 오류 메시지를 이해하기 어렵습니다. 이 GKE 포드 오류(panic: runtime error: invalid memory address or nil pointer dereference)는 무엇을 의미하며 일반적인 원인은 무엇인가요? Gemini Cloud Assist가 메시지를 분석하고 명확한 용어로 설명합니다. 또한 잠재적 원인과 해결책도 제공합니다.
성능 문제 팀에서 GKE에서 실행되는 앱의 지연 시간이 높다고 알립니다. prod GKE 클러스터의 api-gateway 서비스에 지연 시간이 길게 발생합니다. 먼저 어떤 측정항목을 확인해야 하나요? 이 문제의 일반적인 GKE 관련 원인을 제안해 주실 수 있나요? Gemini Cloud Assist는 검토할 주요 측정항목을 제안하고, 잠재적인 문제 (예: 리소스 제약, 네트워크 혼잡)를 탐색하며, 추가 조사를 위한 도구와 기법을 추천합니다.
노드 문제 GKE 노드가 NotReady 상태로 멈춰 있습니다. GKE 노드 중 하나 (node-xyz)에 NotReady 상태가 표시됩니다. 이 문제를 해결하기 위한 일반적인 단계는 무엇인가요? Gemini Cloud Assist는 노드 자동 복구와 같은 개념을 설명하고 관련 kubectl 명령어를 제안하는 단계별 조사 계획을 제공합니다.
GKE 이해하기 특정 GKE 기능이나 권장사항을 구현하는 방법을 잘 모릅니다. GKE 클러스터를 보호하기 위한 권장사항은 무엇인가요? 자세히 알아볼 수 있는 방법이 있나요? Gemini Cloud Assist는 GKE 권장사항을 명확하게 설명합니다. 관련 콘텐츠 표시를 클릭하여 공식 문서 링크를 확인합니다.

자세한 내용은 다음 리소스를 참조하세요.

Gemini Cloud Assist 조사 사용

Gemini Cloud Assist는 양방향 채팅 외에도 Gemini Cloud Assist 조사를 통해 더 자동화된 심층 분석을 실행할 수 있습니다. 이 기능은 로그 탐색기와 같은 워크플로에 직접 통합되어 있으며 강력한 근본 원인 분석 도구입니다.

오류 또는 특정 리소스에서 조사를 시작하면 Gemini Cloud Assist가 로그, 구성, 측정항목을 분석합니다. 이 데이터를 사용하여 가능한 근본 원인에 관한 순위가 지정된 관찰 결과와 가설을 생성한 다음 권장되는 다음 단계를 제공합니다. 이 결과를 Google Cloud 지원 케이스로 전송하여 문제를 더 빠르게 해결하는 데 도움이 되는 유용한 컨텍스트를 제공할 수도 있습니다.

자세한 내용은 Gemini 문서의 Gemini Cloud Assist 조사를 참고하세요.

총정리: 문제 해결 시나리오 예

이 예에서는 GKE 도구를 조합하여 일반적인 실제 문제인 메모리 부족으로 인해 컨테이너가 반복적으로 다운되는 문제를 진단하고 이해하는 방법을 보여줍니다.

시나리오

GKE에서 실행되는 product-catalog이라는 웹 앱의 당직 엔지니어입니다.

Cloud Monitoring에서 자동 알림을 받으면 조사가 시작됩니다.

Alert: High memory utilization for container 'product-catalog' in 'prod' cluster.

이 알림은 문제가 있음을 알려주고 문제와 product-catalog 워크로드 간에 관련성이 있음을 나타냅니다.

Google Cloud 콘솔에서 문제 확인

워크로드의 개략적인 보기를 통해 문제를 확인합니다.

  1. Google Cloud 콘솔에서 워크로드 페이지로 이동하여 product-catalog 워크로드를 필터링합니다.
  2. 포드 상태 열을 확인합니다. 정상적인 3/3 대신 비정상 상태를 꾸준히 보여주는 값 2/3이 표시됩니다. 이 값은 앱의 포드 중 하나의 상태가 Ready이 아님을 나타냅니다.
  3. 추가로 조사하기 위해 product-catalog 워크로드의 이름을 클릭하여 세부정보 페이지로 이동합니다.
  4. 세부정보 페이지에서 관리 포드 섹션을 확인합니다. 문제가 바로 확인됩니다. 포드의 Restarts 열에 비정상적으로 높은 수치인 14이 표시됩니다.

다시 시작 횟수가 많다는 것은 이 문제로 인해 앱이 불안정해지고 컨테이너가 상태 점검에 실패하거나 비정상 종료된다는 것을 의미합니다.

kubectl 명령어로 이유 찾기

앱이 반복적으로 다시 시작된다는 것을 알았으므로 이제 그 이유를 알아내야 합니다. kubectl describe 명령어가 이 작업에 적합한 도구입니다.

  1. 불안정한 포드의 정확한 이름을 가져옵니다.

    kubectl get pods -n prod

    출력은 다음과 같습니다.

    NAME                             READY  STATUS            RESTARTS  AGE
product-catalog-d84857dcf-g7v2x  0/1    CrashLoopBackOff  14        25m
product-catalog-d84857dcf-lq8m4  1/1    Running           0         2h30m
product-catalog-d84857dcf-wz9p1  1/1    Running           0         2h30m

  2. 불안정한 포드를 설명하여 자세한 이벤트 기록을 가져옵니다.

    kubectl describe pod product-catalog-d84857dcf-g7v2x -n prod

  3. 출력을 검토하고 Last State 및 Events 섹션에서 단서를 찾습니다.

    Containers:
  product-catalog-api:
    ...
    State:          Waiting
      Reason:       CrashLoopBackOff
    Last State:     Terminated
      Reason:       OOMKilled
      Exit Code:    137
      Started:      Mon, 23 Jun 2025 10:50:15 -0700
      Finished:     Mon, 23 Jun 2025 10:54:58 -0700
    Ready:          False
    Restart Count:  14
...
Events:
  Type     Reason     Age                           From                Message
  ----     ------     ----                          ----                -------
  Normal   Scheduled  25m                           default-scheduler   Successfully assigned prod/product-catalog-d84857dcf-g7v2x to gke-cs-cluster-default-pool-8b8a777f-224a
  Normal   Pulled     8m (x14 over 25m)             kubelet             Container image "us-central1-docker.pkg.dev/my-project/product-catalog/api:v1.2" already present on machine
  Normal   Created    8m (x14 over 25m)             kubelet             Created container product-catalog-api
  Normal   Started    8m (x14 over 25m)             kubelet             Started container product-catalog-api
  Warning  BackOff    3m (x68 over 22m)             kubelet             Back-off restarting failed container

    출력에서 두 가지 중요한 단서를 확인할 수 있습니다.

    • 먼저 Last State 섹션은 컨테이너가 Reason: OOMKilled로 종료되었음을 보여주며, 이는 메모리가 부족했음을 나타냅니다. 이 이유는 과도한 메모리 사용으로 인해 종료된 프로세스의 표준 Linux 종료 코드인 Exit Code: 137에 의해 확인됩니다.
    • 두 번째로 Events 섹션에는 Back-off restarting failed container 메시지가 포함된 Warning: BackOff 이벤트가 표시됩니다. 이 메시지는 컨테이너가 실패 루프에 있음을 확인해 주며, 이는 앞서 본 CrashLoopBackOff 상태의 직접적인 원인입니다.

측정항목으로 동작 시각화

kubectl describe 명령어는 발생한 상황을 알려주지만 Cloud Monitoring은 시간 경과에 따른 환경의 동작을 보여줄 수 있습니다.

  1. Google Cloud 콘솔에서 측정항목 탐색기로 이동합니다.
  2. container/memory/used_bytes 측정항목을 선택합니다.
  3. 출력을 특정 클러스터, 네임스페이스, 포드 이름으로 필터링합니다.

차트에는 명확한 패턴이 표시됩니다. 메모리 사용량이 꾸준히 증가하다가 컨테이너가 OOM으로 종료되고 다시 시작되면 갑자기 0으로 떨어집니다. 이 시각적 증거는 메모리 누수 또는 메모리 제한 부족을 확인합니다.

로그에서 근본 원인 찾기

이제 컨테이너의 메모리가 부족하다는 것을 알지만 정확한 이유는 아직 알 수 없습니다. 근본 원인을 파악하려면 로그 탐색기를 사용하세요.

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

  2. 마지막 비정상 종료 시간 (kubectl describe 명령의 출력에 표시됨) 바로 전의 특정 컨테이너 로그를 필터링하는 쿼리를 작성합니다.

    resource.type="k8s_container"
resource.labels.cluster_name="example-cluster"
resource.labels.namespace_name="prod"
resource.labels.pod_name="product-catalog-d84857dcf-g7v2x"
timestamp >= "2025-06-23T17:50:00Z"
timestamp < "2025-06-23T17:55:00Z"

  3. 로그에서 비정상 종료 직전에 반복되는 메시지 패턴을 확인할 수 있습니다.

    {
  "message": "Processing large image file product-image-large.jpg",
  "severity": "INFO"
},
{
  "message": "WARN: Memory cache size now at 248MB, nearing limit.",
  "severity": "WARNING"
}

이 로그 항목은 앱이 큰 이미지 파일을 메모리에 완전히 로드하여 처리하려고 시도하고 있으며, 결국 컨테이너의 메모리 한도가 소진됨을 나타냅니다.

발견 항목

이 두 도구를 함께 사용하면 문제에 대한 완전한 그림을 그릴 수 있습니다.

  • 모니터링 알림을 통해 문제가 있음을 알렸습니다.
  • Google Cloud 콘솔에 문제가 사용자에게 영향을 미치고 있음 (다시 시작)이 표시되었습니다.
  • kubectl 명령어는 다시 시작의 정확한 이유(OOMKilled)를 지적했습니다.
  • 측정항목 탐색기에서 시간 경과에 따른 메모리 누수 패턴을 시각화했습니다.
  • 로그 탐색기를 통해 메모리 문제를 일으키는 구체적인 동작이 밝혀졌습니다.

이제 솔루션을 구현할 준비가 되었습니다. 앱 코드를 최적화하여 큰 파일을 더 효율적으로 처리하거나, 단기 해결책으로 워크로드의 YAML 매니페스트에서 컨테이너의 메모리 제한 (특히 spec.containers.resources.limits.memory 값)을 늘릴 수 있습니다.

다음 단계