kubectl로 클러스터 상태 조사

Google Kubernetes Engine (GKE) 문제의 근본 원인을 진단하려면 Kubernetes 리소스의 실시간 상태, 구성, 이벤트를 자세히 검사해야 하는 경우가 많습니다. 표면적인 증상을 넘어선 문제를 해결하려면 클러스터의 컨트롤 플레인을 직접 쿼리하고 상호작용할 수 있는 도구가 필요합니다.

이 페이지를 사용하여 클러스터의 라이브 상태를 조사하는 데 필요한 kubectl 명령어를 알아보세요. 이러한 명령어를 배우면 Kubernetes 컨트롤 플레인에서 직접 자세한 정보를 수집하여 문제가 발생하는 이유를 파악할 수 있습니다.

이 정보는 세부적인 수준에서 클러스터 상태를 심층적으로 확인하고, 리소스를 관리하고, 인프라 문제를 해결해야 하는 플랫폼 관리자 및 운영자에게 중요합니다. 또한 애플리케이션 개발자가 애플리케이션 동작을 디버깅하고, 포드 로그와 이벤트를 검사하고, Kubernetes 환경 내에서 배포의 정확한 상태를 확인할 때도 필수적입니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 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를 참고하세요.

다음 단계