[Kubernetes] 쿠버네티스 설치 과정 및 트러블슈팅 정리

K3s를 이용해 클러스터를 구축 할 예정입니다.

 

K3s 소개

IoT 및 edge computing 디바이스 위에서도 동작할 수 있도록 만들어진 경량 쿠버네티스로 설치가 쉽고 적은 리소스로도 실행 할 수 있습니다.

 

K3s의 장점은 다음과 같습니다.

1. 설치가 쉽다 - 클러스터를 구축하는건 어렵다. 완전 관리형 서비스가 아니면 많은 시간과 노력이 든다. k8s는 몇 줄의 코드로 쉽게 쿠버네티스 클러스터를 구축할 수 있다.
2. 가볍다 - etcd, cloud managert 등 무거운 컴포넌트를 다 가벼운 컴포넌트로 대체하여 적은 리소스로 클러스터 구축 가능하다.
3. 대부분의 기능이 다 들어 있다 - 학습, 개발, 테스트 시 필ㅇ한 모든 기능들을 다 탑재하고 있어 학습용으로 안성 맞춤이다.

K8s 설치하기

본인은 라즈베리파이로 실습 환경을 구성했습니다.

 

마스터 노드 설치

마스터로 사용할 서버에 접속하여 아래 명령어를 실행합니다.

sudo apt update
sudo apt install -y docker.io nfs-common dnsutils curl

# k3s 마스터 설치
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="\
    --disable traefik \
    --disable metrics-server \
    --node-name master --docker" \
    INSTALL_K3S_VERSION="v1.18.6+k3s1" sh -s -

# 마스터 통신을 위한 설정
mkdir ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown -R $(id -u):$(id -g) ~/.kube
echo "export KUBECONFIG=~/.kube/config" >> ~/.bashrc
source ~/.bashrc

# 설치 확인
kubectl cluster-info
# Kubernetes master is running at https://127.0.0.1:6443
# CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces...
# 
# To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

kubectl get node -o wide
# NAME     STATUS   ROLES    AGE   VERSION        INTERNAL-IP    ...
# master   Ready    master   27m   v1.18.6+k3s1   10.0.1.1       ...​

 

 

이제 클러스터에 워커 노드를 추가하기 위한 마스터 노드의 NODE_TOKEN 값과 MASTER_IP를 다음과 같이 확인합니다.

# 마스터 노드 토큰 확인
NODE_TOKEN=$(sudo cat /var/lib/rancher/k3s/server/node-token)
echo $NODE_TOKEN
# K10e6f5a983710a836b9ad21ca4a99fcxx::server:c8ae61726384c19726022879xx

MASTER_IP=$(kubectl get node master -ojsonpath="{.status.addresses[0].address}")
echo $MASTER_IP
# 10.0.1.1

 

워커 노드 설치

아래 과정은 워커 노드에서 진행합니다.

NODE_TOKEN=<마스터에서 확인한 토큰 입력>
MASTER_IP=<마스터에서 얻은 내부IP 입력>

sudo apt update
sudo apt install -y docker.io nfs-common curl

# k3s 워커 노드 설치
curl -sfL https://get.k3s.io | K3S_URL=https://$MASTER_IP:6443 \
    K3S_TOKEN=$NODE_TOKEN \
    INSTALL_K3S_EXEC="--node-name worker --docker" \
    INSTALL_K3S_VERSION="v1.18.6+k3s1" sh -s -

 

위 명령어를 입력 후 마스터 노드에서 확인을 해보면 아래와 같이 잘 연결된 것을 볼 수 있습니다!

 

 

진행 과정 중 트러블 슈팅 요약

1. 초기 문제 상황
   • 워커 노드에서 k3s-agent 실행 시에러가 반복되며 조인 실패.
   • token is not valid: https://127.0.0.1:xxxxx/apis: 401 Unauthorized
   • 로그 상 cgroup 관련 경고도 있었음.
2. cgroup 확인 및 수정
   • grep cgroup /proc/cmdline 로 확인 → 이미 cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 옵션이 추가되어 있었음.
   • /sys/fs/cgroup/memory 확인 결과 정상 mount 되어 있어 cgroup 문제는 해결된 상태.
3. 환경 변수 방식 문제
   • k3s-agent.service.env 파일로 환경 변수 지정했으나, 여전히 401 Unauthorized 발생.
   • 이는 토큰 값 전달이 제대로 안되거나 설치 버전 문제로 추정됨.
4. 설치 방식 변경 (직접 설치 스크립트)
   • systemd 환경변수 방식 대신, 공식 스크립트로 설치 시 환경변수를 직접 넘김:
   • curl -sfL https://get.k3s.io | \ K3S_URL=https://192.168.0.83:6443 \ K3S_TOKEN="<node-token>" \ INSTALL_K3S_EXEC="--node-name worker --docker" \ sh -s -
   • 이 방식으로 설치하니 k3s-agent 가 정상적으로 기동.
5. 정상 동작 확인
   • kubectl get nodes -o wide 에서 worker 노드가 Ready 상태로 등록됨.
   • journalctl -u k3s-agent 로그에도메시지 확인 → 조인 완료.
   • k3s agent is up and running Node controller sync successful

---

핵심 원인: systemd 환경 변수 방식이 정상 반영되지 않아 K3S_TOKEN 전달이 실패 → 직접 설치 스크립트 방식으로 해결.
최종 결과: master(192.168.0.83)와 worker(192.168.0.96)가 정상적으로 연결되고, 클러스터 Ready 상태 확인.