Kubernetes Node Name - 불변(Immutable)

Kubernetes Node Name - 불변(Immutable)

Kubernetes에서 Node는 클러스터의 리소스를 제공하는 단위이며 각 노드는 고유한 이름으로 식별된다. 이 이름은 단순한 레이블이 아니라 API 서버에서 Node 객체를 참조하고 스케줄링 및 상태 관리를 수행하는 핵심 식별자다.

 

본 글에서는 Kubernetes에서 왜 Node 이름이 불변인지 그 배경과 실제 운영 환경에서의 고려사항을 정리한다.

 

공식 문서

Nodes

 

Node Name은 왜 불변인가?

1.  클러스터 내 유일성

“Node name uniqueness” 섹션에서 Kubernetes는 Node 이름이 DNS 서브도메인 규칙을 따라야 하며, 동일 시점에 동일 이름의 두 노드는 존재할 수 없다고 명확히 명시한다. 또한, 동일 이름은 같은 객체로 간주되며, 노드를 교체하거나 업데이트할 필요가 있을 경우 기존 Node 객체를 삭제하고 다시 등록해야 한다고 권장하고 있다.

2. kubelet 등록 방식

kubelet은 기본적으로 호스트명을 Node 이름으로 사용하며, --register-node=true 상태에서 자동 등록된다. --hostname-override 플래그로 이름을 지정할 수 있지만, 일단 등록된 이름은 API 서버에서 변경할 수 없다.

 

공식 문서 중

“Two Nodes cannot have the same name at the same time. Kubernetes also assumes that a resource with the same name is the same object. … If the Node needs to be replaced or updated significantly, the existing Node object needs to be removed from API server first and re-added after the update.” 

 

Node 이름의 유일성, 같은 이름이 동일 객체로 간주된다, 그리고 이름 변경을 위해선 삭제 후 재등록이 필요하다.

 

Node 이름 변경 시 장애 사례

 

장애 현상:

운영 중 특정 노드의 호스트명을 변경한 후 해당 노드가 클러스터에서 NotReady 상태로 고정되거나 새로운 노드로도 정상 등록되지 않음. 스케줄러는 이전 Node 이름을 기준으로 계속 파드를 배치하려고 시도하고, 실제 노드는 그 이름으로 존재하지 않아 파드가 Pending 또는 CrashLoopBackOff 상태를 반복함.

 

원인:

kubelet은 기본적으로 노드 호스트명을 Node 이름으로 사용한다. 이미 등록된 Node 이름은 수정이 불가능하므로, 호스트명을 바꾸면 기존 Node와 불일치가 발생한다. API 서버에는 이전 이름의 Node 객체가 남아 있고, 새로운 이름으로 등록을 시도하면 충돌이 발생하거나 인증 오류가 발생할 수 있다.

 

 

---

정리

• Node 이름은 고유하고 변경 불가능한 식별자로 취급된다.
• 한 번 등록된 Node 이름은 API 서버에서 수정할 수 없으며, 이름 변경을 원할 경우 반드시 기존 Node 객체를 삭제하고 새로운 이름으로 재등록해야 한다.