Raspberry Pi + K3s: 저사양 장비로 만드는쿠버네티스 클러스터 구성하기

이번 글에서는 Raspberry Pi에 경량 Kubernetes 배포판인 K3s를 설치하고, 발생 가능한 오류를 해결한 뒤, 로컬 PC에서 kubectl로 클러스터를 제어하는 전체 과정을 정리합니다.

 

✅ 사전 준비 사항
- Raspberry Pi OS 설치 완료
- SSH 접속 가능
- root 권한 사용 가능

 

 

 

k3s는 Rancher에서 만든 가벼운 Kubernetes 배포판으로, Raspberry Pi 같은 저사양 장비에서도 쉽게 Kubernetes 클러스터를 구축할 수 있도록 도와줍니다.

 

Raspberry Pi에 가벼운 os를 설치하는 방법은 이 블로그 포스트에서 확인할 수 있습니다.

 

Raspberry Pi에 k3s를 설치하려면 먼저 Raspberry Pi OS가 설치되어 있고, SSH 접속이 가능해야 하며 root 권한을 사용할 수 있어야 합니다.

---

k3s 설치하기

sudo apt update && sudo apt upgrade -y

curl -sfL <https://get.k3s.io> | sh -

 

설치가 완료되면 k3s는 자동으로 실행되며, sudo kubectl get nodes 명령어를 통해 노드가 정상적으로 클러스터에 등록되었는지 확인할 수 있습니다.

 

위처럼 실행하니 에러로 인해 설치가 실패했습니다.

---

설치 에러 디버깅 하기

에러 로그를 확인해 보면 다음과 같은 내용이 포함되어 있습니다.

 

[INFO]  Failed to find memory cgroup, you may need to add "cgroup_memory=1 cgroup_enable=memory" to your linux cmdline (/boot/cmdline.txt on a Raspberry Pi)

 

위 내용은 메모리 관리 기능이 커널에 활성화되어있지 않은 것으로 해당 설정을 활성화해주어야 합니다.

 

또한 아래와 같은 에러 메시지가 존재합니다.

[INFO]  Host iptables-save/iptables-restore tools not found
[INFO]  Host ip6tables-save/ip6tables-restore tools not found

 

위 내용은 iptables 명령어가 존재하지 않기 때문에 네트워크 구성에 실패한 에러를 표시합니다.

 

먼저 메모리 관리 기능을 활성화한 후 iptables 명령어를 설치해서 iptable을 구성할 수 있도록 하겠습니다.

sudo vi /boot/cmdline.txt

 

해당 명령어를 실행 해보면 다음과 같은 문구를 확인해 볼 수 있습니다.

 

해당 파일을 수정하지 마세요.
당신이 찾는 파일은 /boot/firmware/cmdline.txt 로 이동되었습니다.

 

 

Raspberry Pi OS 최신 버전에서는 로그에서 나온 경로의 파일인 /boot/cmdline.txt 대신 /boot/firmware/cmdline.txt를 수정해줘야 합니다.

sudo vi /boot/firmware/cmdline.txt

 

기존에 존재하는 내용 뒤에 한칸을 띄고 아래 내용을 추가해 줍니다.

{...기존 내용...} cgroup_enable=memory cgroup_memory=1

 

수정 후 재부팅을 위해 다음 명령어를 실행합니다.

sudo reboot

 

재부팅을 수행한 후 iptables 커맨드를 설치합니다.

sudo apt install -y iptables

 

재부팅 후 k3s 재설치를 진행합니다.

sudo /usr/local/bin/k3s-uninstall.sh
curl -sfL <https://get.k3s.io> | sh -

 

재설치가 진행된 후 node의 상태를 확인해 볼 수 있습니다.

sudo kubectl get nodes

 

성공적으로 Raspberry Pi에 kubernetes 클러스터가 설치되고 node로 등록이 된 걸 확인할 수 있습니다.

 

---

KubeConfig Permission 확인하기

현재 ssh를 접속한 사용자로 kubectl 명령어를 수행하는 경우 권한 에러가 발생합니다.

 

 

이는 k3s의 기본 설정 때문입니다.

k3s는 설치될 때 kubectl 명령이 사용할 kubeconfig 파일을 root 전용 경로인 다음 경로에 생성합니다.

/etc/rancher/k3s/k3s.yaml

 

해당 파일에는 클러스터 접속 정보(서버 주소, 인증 토큰 등)가 담겨 있으며, 기본적으로 root만 읽을 수 있는 권한을 가지고 있습니다.

그래서 일반 사용자가 kubectl을 실행하면 거부됩니다.

 

다음 명령어를 통해서 해당 파일의 내용을 확인할 수 있습니다.

sudo su -

cat /etc/rancher/k3s/k3s.yaml

 

일반 사용자가 kubectl 을 사용할 수 있게 하려면 해당 파일을 사용자의 홈 디렉터리 하위로 복사하고 권한을 변경하면 됩니다.

아래 커맨드는 일반 사용자(raspberry pi에 로그인 한 사용자)의 터미널 세션에서 실행합니다.

mkdir -p ~/.kube

sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config

sudo chown $USER:$USER ~/.kube/config

 

이제 일반 사용자에서 실행하는 kubectl의 경우 ~/. kube/config를 참조하여 sudo 없이도 정상 동작이 가능합니다.

여전히 root에서만 접근가능한 /etc/rancher/k3s/k3s.yaml을 참조하고 있습니다.

 

이 경우 600으로 설정된 k3s.yaml 파일의 권한을 직접 수정할 수 있습니다.

sudo chmod 644 /etc/rancher/k3s/k3s.yaml

 

해당 설정은 k3s를 설치하는 당시에 인자값으로 넘겨서 실행할 수 있습니다.

curl -sfL <https://get.k3s.io> | INSTALL_K3S_EXEC="--write-kubeconfig-mode 644" sh -

 

이제 일반 사용자 계정에서도 kubectl을 사용해 클러스터 리소스를 확인할 수 있습니다.

---

로컬에서 Raspberry Pi의 k3s 클러스터에 kubectl 연결하기

K3s를 설치하면 kubeconfig 파일(k3s.yaml)이 마스터(서버) 노드에 생성됩니다.

 

현재는 kubeconfig가 서버 노드 안에만 있어서 kubectl을 마스터에서 실행하게 되면 마치 “마스터에 붙어서 마스터를 제어”하는 이상한 상황처럼 느껴집니다.

 

마스터 노드에서 /etc/rancher/k3s/k3s.yaml을 로컬 PC로 복사하여 구성을 진행합니다.

 

1단계: kubeconfig 파일을 클러스터에서 로컬로 복사하기

먼저 마스터 노드 (라즈베리 파이)에서 다음 명령어를 실행하여 k3s를 설치하면서 생성된 kubeconfig 파일을 임시로 복사하고 소유권을 라즈베리 파이의 사용자 명으로 변경하여 줍니다.

 

sudo cp /etc/rancher/k3s/k3s.yaml /home/<라즈베리파이 사용자명>/k3s.yaml
sudo chown <라즈베리파이 사용자명>:<라즈베리파이 사용자명> /home/<라즈베리파이 사용자명>/k3s.yaml

 

로컬 pc에서 다음 명령어를 입력합니다.

scp <라즈베리파이 사용자명>@<라즈베리파이 아이피>:/home/<라즈베리파이 사용자명>/k3s.yaml ~/k3s-remote.yaml

 

공유기의 관리자 페이지 혹은 Raspberry Pi에서 다음 명령어를 수행해 라즈베리파이의 ip를 알 수 있습니다.

hostname -I # 여러 아이피 중 첫번쨰가 로컬 IP 입니다.

 

2단계: kubeconfig 파일에서 API 서버 주소 수정

로컬로 복사된 kubeconfig 파일에는 기본적으로 server: https://127.0.0.1:6443처럼 로컬 호스트 주소가 적혀있기 때문에, 이를 Raspberry Pi의 실제 IP 주소로 수정해줘야 합니다.

vim ~/k3s-remote.yaml

 

파일을 열고 다음 항목을 찾아 아래처럼 수정합니다:

clusters:
- cluster:
    server: https://<RaspberryPi_IP>:6443

 

위 IP는 Raspberry Pi의 실제 주소로 교체해 주세요.

hostname -I

 

명령어를 Pi에서 입력하면 확인 가능합니다.

 

3단계: 로컬 kubectl이 사용할 kubeconfig 경로 설정

kubeconfig 파일을 로컬 ~/. kube 디렉터리에 복사하고 이름을 지정합니다

mkdir -p ~/.kube
cp ~/k3s-remote.yaml ~/.kube/config-raspberry

 

4단계: context 등록 및 환경변수로 연결 고정

마지막으로 등록한 kubeconfig를 context로 등록하여 줍니다.

kubectl config --kubeconfig=~/.kube/config-raspberry get-contexts

kubectl config --kubeconfig=~/.kube/config-raspberry set-context config-raspberry \\
  --cluster=default --user=default

kubectl config --kubeconfig=~/.kube/config-raspberry use-context config-raspberry

kubectl config --kubeconfig=~/.kube/config-raspberry get-contexts

 

context가 잘 설정되었으면, 환경변수를 추가하여 매번 --kubeconfig 옵션을 쓰지 않도록 설정합니다:

# 사용하는 쉘이 bash일 경우에는 .bashrc에 추가하면 됩니다.
echo 'export KUBECONFIG=~/.kube/config-raspberry' >> ~/.zshrc

source ~/.zshrc

 

이제 로컬에서 다음처럼 사용하면 됩니다:

kubectl get nodes
kubectl get pods -A

 

잘 연결되었다면, Raspberry Pi에서 실행 중인 k3s 클러스터의 정보가 출력됩니다.