728x90
반응형
K3s를 이용해 클러스터를 구축 할 예정입니다.
K3s 소개
IoT 및 edge computing 디바이스 위에서도 동작할 수 있도록 만들어진 경량 쿠버네티스로 설치가 쉽고 적은 리소스로도 실행 할 수 있습니다.
K3s의 장점은 다음과 같습니다.
- 설치가 쉽다 - 클러스터를 구축하는건 어렵다. 완전 관리형 서비스가 아니면 많은 시간과 노력이 든다. k8s는 몇 줄의 코드로 쉽게 쿠버네티스 클러스터를 구축할 수 있다.
- 가볍다 - etcd, cloud managert 등 무거운 컴포넌트를 다 가벼운 컴포넌트로 대체하여 적은 리소스로 클러스터 구축 가능하다.
- 대부분의 기능이 다 들어 있다 - 학습, 개발, 테스트 시 필ㅇ한 모든 기능들을 다 탑재하고 있어 학습용으로 안성 맞춤이다.
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 -
위 명령어를 입력 후 마스터 노드에서 확인을 해보면 아래와 같이 잘 연결된 것을 볼 수 있습니다!

진행 과정 중 트러블 슈팅 요약
- 초기 문제 상황
- 워커 노드에서 k3s-agent 실행 시에러가 반복되며 조인 실패.
-
token is not valid: https://127.0.0.1:xxxxx/apis: 401 Unauthorized
- 로그 상 cgroup 관련 경고도 있었음.
- cgroup 확인 및 수정
- grep cgroup /proc/cmdline 로 확인 → 이미 cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 옵션이 추가되어 있었음.
- /sys/fs/cgroup/memory 확인 결과 정상 mount 되어 있어 cgroup 문제는 해결된 상태.
- 환경 변수 방식 문제
- k3s-agent.service.env 파일로 환경 변수 지정했으나, 여전히 401 Unauthorized 발생.
- 이는 토큰 값 전달이 제대로 안되거나 설치 버전 문제로 추정됨.
- 설치 방식 변경 (직접 설치 스크립트)
- 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 가 정상적으로 기동.
- 정상 동작 확인
- 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 상태 확인.
728x90
반응형
'개발 > DevOps' 카테고리의 다른 글
| [Kubernetes] kubectl 기본 명령어 2 (0) | 2025.09.16 |
|---|---|
| [Kubernetes] kubectl 기본 명령어 (1) | 2025.09.16 |
| [Kubernetes] 쿠버네티스란? (0) | 2025.09.09 |
| [Kubernetes] Docker 기초 2 - 기본 명령 (0) | 2025.09.08 |