🛠️ K8S Trouble Shooting : 기타 일반적인 Kubernetes 오류 해결하기

 

Kubernetes를 사용하다 보면 특정 카테고리에 속하지 않는 다양한 오류를 경험할 수 있습니다.

이 글에서는 노드 정보 조회 실패, API 서버 문제, 플래그 오류, 명령어 오류 등과 관련된 대표적인 일반적인 Kubernetes 오류 5가지를 정리하고, 각각의 원인과 해결 방법을 설명합니다. 🚀

 

---

 

1️⃣ “failed to fetch node info…”

 

🔎 오류 설명

 

이 오류는 노드가 정상적으로 동작하지 않거나, kubelet이 노드 정보를 가져오는 데 실패했을 때 발생합니다.

주로 노드 상태가 NotReady이거나, API 서버와 연결이 끊긴 경우입니다.

 

🔧 해결 방법

 

1) 노드 상태 확인

 

노드가 정상적으로 실행되고 있는지 확인합니다.

kubectl get nodes

 

2) 노드의 상세 상태 확인

 

노드의 이벤트 및 상태를 확인하여 문제를 찾습니다.

kubectl describe node <node-name>

 

3) kubelet 로그 확인

 

노드에서 kubelet이 정상적으로 동작하는지 확인합니다.

journalctl -u kubelet --no-pager | tail -20

 

4) 노드 재등록

 

문제가 지속된다면 노드를 클러스터에서 삭제하고 다시 등록할 수 있습니다.

kubectl delete node <node-name>

 

이후, 노드를 다시 추가하거나 kubeadm을 사용하여 재등록할 수 있습니다.

kubeadm reset
kubeadm join <master-node>:6443 --token <token>

 

---

 

2️⃣ “error: the server doesn’t have a resource type…”

 

🔎 오류 설명

 

이 오류는 kubectl이 요청한 리소스를 Kubernetes API에서 찾을 수 없을 때 발생합니다.

잘못된 리소스 이름을 입력했거나, 해당 리소스를 제공하는 API 그룹이 비활성화된 경우입니다.

 

🔧 해결 방법

 

1) 지원되는 리소스 목록 확인

 

현재 클러스터에서 지원하는 리소스를 확인합니다.

kubectl api-resources

 

특정 그룹에서 지원하는 API 버전을 확인하려면 다음 명령을 실행하세요.

kubectl api-versions

 

2) 올바른 리소스 타입 입력 확인

 

잘못된 리소스 타입을 입력했는지 확인합니다.

kubectl get deployment  # 올바른 리소스 타입
kubectl get deproyment  # 잘못된 리소스 타입 (오타)

 

3) CRD(Custom Resource Definition) 확인

 

만약 커스텀 리소스를 사용하고 있다면, 해당 CRD가 적용되었는지 확인합니다.

kubectl get crds

 

만약 CRD가 존재하지 않는다면, 다시 적용해야 합니다.

kubectl apply -f <crd-file>.yaml

 

---

 

3️⃣ “operation not supported for token requests”

 

🔎 오류 설명

 

이 오류는 서비스 계정이 토큰 기반 요청을 수행할 권한이 없을 때 발생합니다.

주로 RBAC 정책이 올바르게 설정되지 않았거나, Kubernetes API 서버에서 제한된 작업을 수행하려 할 때 나타납니다.

 

🔧 해결 방법

 

1) 서비스 계정의 토큰 조회

 

해당 서비스 계정이 올바르게 토큰을 생성할 수 있는지 확인합니다.

kubectl describe serviceaccount <sa-name> -n <namespace>

 

2) 올바른 토큰 권한 부여

 

서비스 계정이 토큰을 요청할 수 있도록 ClusterRoleBinding을 설정합니다.

kubectl create clusterrolebinding token-role-binding \
  --clusterrole=system:service-account-issuer \
  --serviceaccount=<namespace>:<sa-name>

 

3) API 요청 수행 시 토큰 포함

 

서비스 계정을 사용하여 Kubernetes API에 접근할 때 올바른 토큰을 포함해야 합니다.

TOKEN=$(kubectl get secret $(kubectl get serviceaccount <sa-name> -o jsonpath='{.secrets[0].name}') -o jsonpath='{.data.token}' | base64 --decode)
curl -H "Authorization: Bearer $TOKEN" https://<kubernetes-api-server>/api/v1/namespaces

 

---

 

4️⃣ “unknown flag…”

 

🔎 오류 설명

 

이 오류는 kubectl 또는 다른 Kubernetes 명령어에서 지원되지 않는 플래그(옵션)를 사용했을 때 발생합니다.

주로 버전 불일치, 오타, 또는 최신 기능이 포함되지 않은 환경에서 실행했을 때 나타납니다.

 

🔧 해결 방법

 

1) 사용 가능한 플래그 목록 확인

 

지원되는 플래그 목록을 확인하려면 --help 옵션을 추가합니다.

kubectl get pods --help

 

2) kubectl 버전 확인

 

현재 사용 중인 kubectl 버전과 클러스터 버전이 일치하는지 확인하세요.

kubectl version --short

 

3) kubectl 최신 버전으로 업데이트

 

사용 중인 kubectl이 너무 오래된 경우, 최신 버전으로 업데이트합니다.

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

 

---

 

5️⃣ “invalid value: must be no more than X characters”

 

🔎 오류 설명

 

이 오류는 리소스의 특정 필드 값이 Kubernetes의 제한을 초과했을 때 발생합니다.

예를 들어, 네임스페이스, 서비스, 볼륨 이름 등이 너무 길거나 잘못된 형식을 가질 경우 나타납니다.

 

🔧 해결 방법

 

1) 입력 값이 올바른지 확인

 

각 리소스의 이름이 허용된 길이를 초과했는지 확인합니다.

예를 들어, 서비스 이름은 63자를 초과할 수 없습니다.

kubectl get svc

 

2) 네임스페이스, 서비스, 볼륨 등의 이름 변경

 

이름을 짧게 줄이거나 Kubernetes 네이밍 규칙을 준수하도록 수정합니다.

metadata:
  name: my-app-service  # 올바른 예제

 

3) YAML 검증 수행

 

리소스 정의 파일을 적용하기 전에 문법 검사를 수행합니다.

kubectl apply --dry-run=client -f <file.yaml>

 

---

 

🎯 마무리

 

이 글에서는 Kubernetes에서 자주 발생하는 기타 일반적인 오류 5가지와 그 해결 방법을 다뤘습니다.

 

✔️ 노드 정보 조회 실패 오류 (failed to fetch node info)

✔️ 지원되지 않는 리소스 오류 (error: the server doesn’t have a resource type)

✔️ 토큰 요청 지원되지 않음 오류 (operation not supported for token requests)

✔️ 잘못된 플래그 사용 오류 (unknown flag…)

✔️ 제한된 문자 길이 초과 오류 (invalid value: must be no more than X characters)

 

만약 위 해결 방법으로도 문제가 해결되지 않는다면,

kubectl describe node, kubectl api-resources, kubectl get serviceaccount 명령어 등을 활용하여 추가로 분석해보는 것이 좋습니다.