레거시 노드를 k3s 클러스터에 통합하며 전체 클러스터 구성하기

기존에 운영하던 서버들을 그대로 유지하면서 새로운 k3s 클러스터에 워커 노드로 통합하는 것은 생각보다 복잡한 과정이었습니다. 특히 Traefik과 svclb의 충돌, 그리고 Hostname 변경 후 발생한 여러 문제들을 해결하며 k3s의 내부 동작 방식을 깊이 이해할 수 있었습니다.

학습 주제

• 공부 주제: 레거시 노드를 k3s 클러스터에 워커로 편입시키고 전체 클러스터 구성하기
• 대화 제목: 레거시 노드를 k3s 클러스터에 통합하기 전체 클러스터 구성하기
• 학습 날짜: 2026년 2월 21일 - 2026년 2월 22일

질문과 탐구

새로운 k3s 컨트롤 플레인을 구축하면서 기존에 운영 중이던 서버(레거시 노드)들을 그대로 사용하고 싶었습니다. 이 서버들의 기존 서비스들은 유지한 채, k3s 클러스터의 워커 노드로 등록하는 방법이 주요 질문이었습니다.

이 과정에서 여러 문제에 부딪혔습니다.

• 워커 노드 추가 후 외부 접속이 안 되는 404 오류 발생
• Hostname 변경 후 노드 인식 문제
• k3s agent 재시작 시 연결 지연 및 실패

이러한 문제들을 해결하기 위해 AI와 함께 각 문제의 원인을 분석하고, iptables 규칙, k3s 설정 파일, Pod 목록 등을 상세히 확인하며 해결책을 찾아나갔습니다.

핵심 학습 내용

1. k3s 클러스터 구성 기본

• Control Plane: k3s 클러스터의 제어 영역으로, API 서버, etcd 등 핵심 컴포넌트가 실행됩니다. 새로운 서버나 기존 서버를 Control Plane으로 지정할 수 있습니다.
• Worker Node: Control Plane의 지시를 받아 Pod를 실행하고 관리하는 역할을 합니다. 기존 서비스를 실행 중인 서버를 워커 노드로 등록하여 기존 인프라를 최대한 활용할 수 있습니다.
• k3s Agent: 워커 노드에서 실행되며 Control Plane과 통신하여 Pod를 스케줄링하고 관리합니다. 기존에 실행 중인 서비스에는 영향을 주지 않고 별도 프로세스로 동작합니다.

2. 레거시 노드 통합 시 주요 고려사항

• 포트 충돌: k3s가 사용하는 기본 포트(10250, 8472/udp 등)와 기존 서비스에서 사용하는 포트가 겹치지 않는지 확인해야 합니다.
• CNI 충돌: Flannel과 같은 CNI(Container Network Interface)가 기존 네트워크 설정과 충돌하지 않도록 설정해야 합니다. Flannel의 vxlan 백엔드는 일반적으로 호환성이 높습니다.
• Ingress Controller 충돌: k3s 기본 Ingress Controller인 Traefik이 기존 Nginx와 80/443 포트를 두고 충돌할 수 있습니다. 워커 노드 추가 시 Traefik을 비활성화하거나 제거하는 것이 좋습니다.
• Hostname 변경: Hostname 변경 후 k3s가 이를 제대로 인식하도록 설정 파일을 수정하고 k3s/k3s-agent를 재시작해야 합니다.

3. 문제 해결 과정

• Traefik 및 svclb 충돌: 워커 노드를 추가하면서 k3s의 ServiceLoadBalancer(svclb)가 자동으로 생성되어 Nginx의 80/443 포트를 가로채는 문제가 발생했습니다. 이는 Traefik Helm Chart를 삭제하고 Control Plane 설정에서 Traefik을 명시적으로 비활성화함으로써 해결했습니다.

  # /etc/rancher/k3s/config.yaml (Control Plane에서)
  disable:
    - traefik
  

• Hostname 변경 후 노드 인식 문제: Hostname 변경 후 기존 노드 정보가 남아있거나 새로운 노드 정보가 제대로 등록되지 않는 문제가 발생했습니다. kubectl delete node 명령어로 오래된 노드를 삭제하고 k3s/k3s-agent를 재시작하여 해결했습니다.

이해한 내용

• k3s는 기존 인프라를 최대한 활용하여 클러스터를 확장할 수 있는 유연성을 제공합니다.
• 워커 노드를 추가할 때 발생할 수 있는 잠재적인 충돌(포트, CNI, Ingress)을 미리 파악하고 대비하는 것이 중요합니다.
• k3s의 내부 컴포넌트(svclb, Traefik) 동작 방식을 이해하면 문제 발생 시 근본적인 원인을 파악하는 데 도움이 됩니다.
• Hostname 변경과 같은 시스템 설정 변경 후에는 k3s 서비스를 재시작하여 변경 사항을 반영해야 합니다.
• kubectl 명령어는 Control Plane에서 실행해야 클러스터 전체 노드 및 Pod 상태를 관리할 수 있습니다.

실전 적용

• 기존 서버 활용: 새로운 k3s 클러스터를 구축할 때, 별도의 서버 구매 없이 기존에 사용하던 베어메탈 서버를 워커 노드로 활용하여 비용을 절감할 수 있습니다.
• 점진적 마이그레이션: 기존 서비스들은 유지하면서 점진적으로 애플리케이션을 k3s 클러스터의 Pod로 배포하는 방식으로 전환할 수 있습니다.
• 클러스터 관리 자동화: k3s의 다양한 설정 옵션과 CLI 도구를 활용하여 클러스터 구성 및 관리를 자동화할 수 있습니다.

추가 학습 계획

• k3s의 ServiceLoadBalancer(svclb)와 Ingress Controller(Traefik, Nginx Ingress)의 상세한 역할과 동작 방식에 대해 더 깊이 학습하고 싶습니다.
• 다양한 CNI 플러그인(Calico, Cilium 등)의 특징과 k3s 환경에서의 적용 방법을 알아볼 예정입니다.
• k3s의 아키텍처 및 구성 옵션에 대한 공식 문서를 집중적으로 탐독하여 이해도를 높이고 싶습니다.

참고 자료

• k3s 공식 문서: https://k3s.io/ (대화 중에 언급된 링크들을 바탕으로 일반적인 참고 자료를 기재합니다.)