---


title: 클러스터 트러블슈팅
content_type: concept
---

<!-- overview -->

이 문서는 클러스터 트러블슈팅에 대해 설명한다. 사용자가 겪고 있는 문제의 근본 원인으로서 사용자의 애플리케이션을 
이미 배제했다고 가정한다.
애플리케이션 디버깅에 대한 팁은 [애플리케이션 트러블슈팅 가이드](/docs/tasks/debug-application-cluster/debug-application/)를 참조한다.
자세한 내용은 [트러블슈팅 문서](/ko/docs/tasks/debug-application-cluster/troubleshooting/)를 참조한다.

<!-- body -->

## 클러스터 나열하기

클러스터에서 가장 먼저 디버그해야 할 것은 노드가 모두 올바르게 등록되었는지 여부이다.

다음을 실행한다.

```shell
kubectl get nodes
```

그리고 보일 것으로 예상되는 모든 노드가 존재하고 모두 `Ready` 상태인지 확인한다.

클러스터의 전반적인 상태에 대한 자세한 정보를 얻으려면 다음을 실행할 수 있다.

```shell
kubectl cluster-info dump
```
## 로그 보기

현재로서는 클러스터를 더 깊이 파고들려면 관련 머신에서 로그 확인이 필요하다. 관련 로그 파일 
위치는 다음과 같다. (systemd 기반 시스템에서는 `journalctl`을 대신 사용해야 할 수도 있다.)

### 마스터

   * `/var/log/kube-apiserver.log` - API 서버, API 제공을 담당
   * `/var/log/kube-scheduler.log` - 스케줄러, 스케줄 결정을 담당
   * `/var/log/kube-controller-manager.log` - 레플리케이션 컨트롤러를 담당하는 컨트롤러

### 워커 노드

   * `/var/log/kubelet.log` - Kubelet, 노드에서 컨테이너 실행을 담당
   * `/var/log/kube-proxy.log` - Kube Proxy, 서비스 로드밸런싱을 담당

## 클러스터 장애 모드의 일반적인 개요

아래에 일부 오류 상황 예시 및 문제를 완화하기 위해 클러스터 설정을 조정하는 방법을 나열한다.

### 근본 원인

  - VM(들) 종료
  - 클러스터 내 또는 클러스터와 사용자 간의 네트워크 분할
  - 쿠버네티스 소프트웨어의 충돌
  - 데이터 손실 또는 퍼시스턴트 스토리지 사용 불가 (e.g. GCE PD 또는 AWS EBS 볼륨)
  - 운영자 오류, 예를 들면 잘못 구성된 쿠버네티스 소프트웨어 또는 애플리케이션 소프트웨어

### 특정 시나리오

  - API 서버 VM 종료 또는 API 서버 충돌
    - 다음의 현상을 유발함
      - 새로운 파드, 서비스, 레플리케이션 컨트롤러를 중지, 업데이트 또는 시작할 수 없다.
      -  쿠버네티스 API에 의존하지 않는 기존 파드 및 서비스는 계속 정상적으로 작동할 것이다.
  - API 서버 백업 스토리지 손실
    - 다음의 현상을 유발함
      - API 서버가 구동되지 않을 것이다.
      - kubelet에 도달할 수 없게 되지만, kubelet이 여전히 동일한 파드를 계속 실행하고 동일한 서비스 프록시를 제공할 것이다.
      - API 서버를 재시작하기 전에, 수동으로 복구하거나 API서버 상태를 재생성해야 한다.
  - 지원 서비스 (노드 컨트롤러, 레플리케이션 컨트롤러 매니저, 스케쥴러 등) VM 종료 또는 충돌
    - 현재 그것들은 API 서버와 같은 위치에 있기 때문에 API 서버와 비슷한 상황을 겪을 것이다.
    - 미래에는 이들도 복제본을 가질 것이며 API서버와 별도로 배치될 수도 있다.
    - 지원 서비스들은 상태(persistent state)를 자체적으로 유지하지는 않는다.
  - 개별 노드 (VM 또는 물리적 머신) 종료
    - 다음의 현상을 유발함
      - 해당 노드의 파드가 실행을 중지
  - 네트워크 분할
    - 다음의 현상을 유발함
      - 파티션 A는 파티션 B의 노드가 다운되었다고 생각한다. 파티션 B는 API 서버가 다운되었다고 생각한다. (마스터 VM이 파티션 A에 있다고 가정)
  - Kubelet 소프트웨어 오류
    - 다음의 현상을 유발함
      - 충돌한 kubelet은 노드에서 새 파드를 시작할 수 없다.
      - kubelet이 파드를 삭제할 수도 있고 삭제하지 않을 수도 있다.
      - 노드는 비정상으로 표시된다.
      - 레플리케이션 컨트롤러는 다른 곳에서 새 파드를 시작한다.
  - 클러스터 운영자 오류
    - 다음의 현상을 유발함
      - 파드, 서비스 등의 손실
      - API 서버 백업 저장소 분실
      - API를 읽을 수 없는 사용자
      - 기타

### 완화

- 조치: IaaS VM을 위한 IaaS 공급자의 자동 VM 다시 시작 기능을 사용한다.
  - 다음을 완화할 수 있음: API 서버 VM 종료 또는 API 서버 충돌
  - 다음을 완화할 수 있음: 지원 서비스 VM 종료 또는 충돌

- 조치: API 서버+etcd가 있는 VM에 IaaS 제공자의 안정적인 스토리지(예: GCE PD 또는 AWS EBS 볼륨)를 사용한다.
  - 다음을 완화할 수 있음: API 서버 백업 스토리지 손실

- 조치: [고가용성](/docs/setup/production-environment/tools/kubeadm/high-availability/) 구성을 사용한다.
  - 다음을 완화할 수 있음: 컨트롤 플레인 노드 종료 또는 컨트롤 플레인 구성 요소(스케줄러, API 서버, 컨트롤러 매니저) 충돌
    - 동시에 발생하는 하나 이상의 노드 또는 구성 요소 오류를 허용한다.
  - 다음을 완화할 수 있음: API 서버 백업 스토리지(i.e., etcd의 데이터 디렉터리) 손실
    - 고가용성 etcd 구성을 사용하고 있다고 가정

- 조치: API 서버 PD/EBS 볼륨의 주기적인 스냅샷
  - 다음을 완화할 수 있음: API 서버 백업 스토리지 손실
  - 다음을 완화할 수 있음: 일부 운영자 오류 사례
  - 다음을 완화할 수 있음: 일부 쿠버네티스 소프트웨어 오류 사례

- 조치: 파드 앞에 레플리케이션 컨트롤러와 서비스 사용
  - 다음을 완화할 수 있음: 노드 종료
  - 다음을 완화할 수 있음: Kubelet 소프트웨어 오류

- 조치: 예기치 않은 재시작을 허용하도록 설계된 애플리케이션(컨테이너)
  - 다음을 완화할 수 있음: 노드 종료
  - 다음을 완화할 수 있음: Kubelet 소프트웨어 오류