쿠버네티스 taint·toleration으로 파드 배치 제어하기

특정 노드(예: GPU 노드)에 아무 파드나 올라오거나, 반대로 파드가 어디에도 안 뜨고 Pending에 머문다면 taint·toleration 설정을 봐야 합니다.

OUTPUT

0/4 nodes are available: 4 node(s) had untolerated taint
{dedicated: gpu}. preemption: not eligible

이 메시지는 노드가 taint로 "출입 금지" 팻말을 걸었고, 파드에 그걸 통과할 toleration이 없다는 뜻입니다.

개념: taint는 노드가, toleration은 파드가

taint(오염) — 노드에 붙이는 "조건". 이 조건을 견디지 못하는 파드는 배치를 거부.
toleration(용인) — 파드에 붙이는 "통행증". taint를 견딜 수 있다고 선언.

즉 taint만 있고 toleration이 없으면 파드는 그 노드에 못 올라갑니다. toleration은 허가일 뿐 강제 배치가 아닙니다 — 그 노드로 "보내는" 건 nodeSelector/affinity의 역할입니다.

taint의 3가지 effect

effect	동작	언제
`NoSchedule`	toleration 없으면 신규 배치 거부	전용 노드 격리
`PreferNoSchedule`	가능하면 피하지만 강제는 아님	소프트 회피
`NoExecute`	신규 거부 + 기존 파드도 축출	노드 드레인·문제 노드

Kubernetes

# 노드에 taint 추가
kubectl taint nodes node1 dedicated=gpu:NoSchedule

# taint 제거 (끝에 - 붙임)
kubectl taint nodes node1 dedicated=gpu:NoSchedule-

# 현재 taint 확인
kubectl describe node node1 | grep -i taint

파드에 toleration 부여

YAML

spec:
  tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "gpu"
      effect: "NoSchedule"

operator: "Exists"로 쓰면 value 없이 key만 맞아도 통과합니다.

원인별 해결

① toleration이 있는데도 Pending — toleration은 통행증일 뿐입니다. 해당 노드로 보내려면 nodeSelector나 nodeAffinity를 함께 줘야 합니다. 안 그러면 toleration 없는 다른 노드로도 갈 수 있습니다.

② effect 또는 value 불일치 — taint가 NoSchedule인데 toleration의 effect가 비어 있거나 다르면 매칭 실패. key·value·effect가 정확히 일치해야 합니다.

③ NoExecute로 멀쩡한 파드가 쫓겨남 — NoExecute taint를 붙이면 toleration 없는 기존 파드가 즉시 축출됩니다. tolerationSeconds로 유예 시간을 줄 수 있습니다.

④ 컨트롤플레인에 워크로드가 안 뜸 — 마스터 노드에는 기본 taint(node-role.kubernetes.io/control-plane:NoSchedule)가 있습니다. 단일 노드 클러스터라면 이 taint를 제거해야 일반 파드가 뜹니다.

점검 체크리스트

Kubernetes

kubectl describe node <node> | grep -i taint
kubectl get pod <pod> -o jsonpath='{.spec.tolerations}'
kubectl describe pod <pod> | grep -A3 Events   # untolerated taint 메시지

taint로 전용 노드를 만들고 toleration·nodeSelector로 파드를 정확히 배치하는 실습은 쿠버네티스 트랙에서 회원가입 없이 무료로 해볼 수 있습니다.