쿠버네티스 kubernetes 정복기(1) 설치하기, 각종 오류 트러블슈팅, 초기화(feat.성공적)

1. 시작하면서

최근에 도커를 공부하다가 갑자기...쿠버네티스에 관심이 생겨서 설치해서 이곳에 제가 지금까지 만들었던 프로젝트들을 올려보기로 했습니다.

사실 쿠버네티스가 정확히 뭔지 도커와 뭔 차이가 있는지, 쿠버네티스에서 사용하는 용어들 파드, 서비스, 데몬셋, 레플리케이션 api-server, proxy 등등 알아야할 것도 정말 많고, 공부해야할게 정말 많았습니다.

 

때문에 이것들을 공부하고 설치하고 알아가야하지만, 제게는 시간도 부족했고 무엇보다 제 프로젝트들을 올리는 용도로 쓰기위해 만드는 것이기 때문에 일단 머리부터 들이밀어 봤습니다. 설치하는건 돈이 안들잖아요...?ㅋㅋㅋ

 

다만 저 때까지는 설치하면서 얼마나 오류가 날지 그리고 설치 후에도 얼마나 오류가 날지 몰랐습니다ㅠㅠㅠ

마치 메일 서버 구축했을 때가 떠오르는 느낌이었습니다ㅠㅠ

 

이전처럼 명령어 하나하나 캡쳐를 못해서 이번 글에서는 어떤 흐름으로 설치를 진행해야하는지 그리고 제게 발생했던 오유들과 그것들을 어떻게 해결했는지 작성하려 합니다.

 

3. 설치 순서

쿠버네티스의 구조는 크게 마스터 master - worker 구조입니다. 쉽게 생각하면 팀장님과 사원을 생각해도 될 것 같습니다. 전체적인 관리나 업무진행, 업무 스케줄 등등 모두 master 에서 관리하고, 실제 '일' 그러니까 컨테이너를 실행시키는 쪽은 worker 입니다.

 

글에서는 master 와 worker 설치 순서에 구분이 크게 없으나 실제로 설치할 때는 master -> worker 순서로 설치하는게 정신건강에 더 좋습니다. 다만 master 와 worker 모두 공통적으로 설치해야하는 부분이 있으니 이 부분 먼저 설치하고 넘어가야 합니다.

 

1) 공통 설치 master & worker

패키지 업데이트

apt-get update

 

필수 패키지 설치

sudo apt-get install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

 

도커 GPG Key 추가

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

 

도커 레파지토리 등록

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

 

도커 엔진 설치 및 확인

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

sudo docker version
sudo systemctl status docker

## 서버 재시작 시 docker 가 자동으로 시작되도록 설정 ##
sudo systemctl enable docker

 

노드간 통신을 위한 iptables 에 브릿지 관련 설정 추가

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
br_netfilter
EOF

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
EOF
sysctl --system

 

sysctl.conf 파일에 브릿지 관련 설정추가(옵션)

이 부분은 처음부터 설정해도 되고, 빼고 진행해도 무방합니다.

다만 저는 이 부분을 설정했을 때는 오류가 없었으나 안했을때는 오류가 발생했었습니다

/etc/sysctl.conf 파일 맨 아래 두 줄 추가

net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1

sysctl -p

 

 

swapoff 설정

swapoff -a

 

 

apt 업데이트 및 ca 관련 패키지 다운로드 및 설정

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg

 

쿠버네티스 gpg 및 소스 리스트 내용 추가 및 apt 업데이트

echo "deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update

 

23.05.29 추가

쿠버네티스 gpg 추가 중 apt-update 시 에러 발생하면 아래 사이트 참고하여 새로 key 다운로드 후 진행할 것

https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/

Installing kubeadm

 

kubeadm, kubelet, kubectl 설치 및 활성화

sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl


systemctl start kubelet && systemctl enable kubelet

 

systemd 와 cgroup 설정 맞추기, 꼭!! 꼭!! 하자

sudo mkdir /etc/docker
cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}
EOF

 

재시작 필수

sudo systemctl enable docker 
sudo systemctl daemon-reload 
sudo systemctl restart docker

 

2) 마스터 설정 : 마스터 노드에서만!! 진행

여기서부터는 정말정말 중요합니다. 조금만 잘못해도 다시해야하는 경우가 많아요ㅠㅠ

 

 

kubeadm init 설정 -> kubeadm 을 통한 네트워크 설정 잡기

• apiserver-advertise-address : 편하게 하려면 내부아이피(privateIP 사용할 것)
• cidr : 이것도 flannel 의 기본인 10.244.0.0/16 을 사용할 것 ⇒ 다른 플러그인 쓰면 상관없음

kubeadm init --apiserver-advertise-address=[privateIP] --pod-network-cidr=10.244.0.0/16

 

그러면 아래와 같이 설정되는 내용들이 나오게 된다.

여기서 아래 mkdir 하는 부분부터 sudo chown 하는 부분까지는 꼭! 진행해줘야한다

또한 맨 마지막에 나오는 kubeadm join 부분을 꼭! 따로 저장해주자

kubeadm init --apiserver-advertise-address=192.168.30.106 \
--pod-network-cidr=10.244.0.0/16 \


Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:


## 아래 부분을 꼭! 수행할 것 ##
## 가능한 root 계정으로 진행하는게 좋다 ##
  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

## 여기까지 ##

Alternatively, if you are the root user, you can run:

  export KUBECONFIG=/etc/kubernetes/admin.conf

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 192.168.30.106:6443 --token sfmykq.03pyki2yq31omogi \
        --discovery-token-ca-cert-hash sha256:2fa93a680887970e08b8a0c05d58bb565f2abfd73488fbbbf2eebaaf067bbfac

 

230529 추가 - cgroup_memory disable 에러 발생 시

해당 에러는 라즈베리파이4B 에서 쿠버 설치 시 발생하는 것을 확인. 아마 라즈베리 기본 설정이 memory 가 disable 이기 때문인듯? 

해결 방법은 아래 파일 수정

sudo vi /boot/firmware/cmdline.txt 
파일 열어서 맨 앞에 추가
cgroup_enable=memory cgroup_memory=1

 

https://truelifer.medium.com/raspberry-pi-4b-%EC%97%90-kubernetes-cluster-%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0-35a1c7be3cbd

Raspberry pi 4B 에 Kubernetes cluster 설치하기

 

마스터 only flannel 설치 - 쿠버네티스 네트워크 플러그인

쿠버네티스에서 노드와 마스터의 통신을 위한 가상 네트워크를 자동으로 잡아주고 설정해주는 플러그인 입니다.

다양한 종류가 있으나 저는 flannel 을 추천합니다.

https://github.com/flannel-io/flannel

GitHub - flannel-io/flannel: flannel is a network fabric for containers, designed for Kubernetes

 

혹시나 자신이 네트워크에 자신이 있으시거나 잘 다루신다면 calico 를 추천합니다. 다만 calico 를 설치하는 경우 앞서 init 에서 사용한 cidr 를 바꾸시던가 calico 에서 이에 맞게 설정해주셔야 합니다

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

 

flannel 설치후 /run/flannel 디렉토리 안 subnet.env 파일이 생성되었는지 꼭! 확인해보자.
만약 없다면 아래의  run/flannel/subnet.env 관련 에러 해결방법을 참고

 

3) worker 노드 설정 : 워커 노드에서만!! 진행

kubeadm join 을 사용하여 워커 노드를 master 에 조인시킵니다. 이때 필요한 네트워크 설정은 flannel 이 잡아주게 됩니다.

kubeadm join 192.168.30.106:6443 --token sfmykq.03pyki2yq31omogi \
        --discovery-token-ca-cert-hash sha256:2fa93a680887970e08b8a0c05d58bb565f2abfd73488fbbbf2eebaaf067bbfac

 

워커 노드 조인 시 [ERROR CRI]: container runtime is not running 에러가 발생하는 경우

/etc/containerd/config.toml 파일에서 
disabled_plugins 항목에서 CRI 제거한 뒤 혹은 주석처리 한 뒤

sudo systemctl restart containerd

 

 

 

containerd 설정 - 정말정말 중요(필수는 아님)

6443 refused, apiserver, proxy, flannel crashbackoff 관련 오류 해결 방법

저는 쿠버네티스를 설치했을 때 아래처럼 6443 was refused 오류에 시달렸습니다. 이 부분 해결을 위해서 정말정말 많이 해맸습니다.

   The connection to the server localhost:8080 was refused - did you specify the right host or port  ?

 

그리고 결국 해결 방법을 찾았는데 이게 containerd 관련 설정이었습니다.

지금으로서는 containerd 가 실행되는동안 docker 와 충돌이 일어나서 문제가 생겼던게 아닌가...하고 생각합니다.

 

혹시나 쿠버네티스 설치 후 master 에서 6443 refused 와 관련된 오류가 발생하거나 apisever, proxy, flannel 의 cashbackoff 오류가 발생한다면 충분히 시도해 볼 만 합니다.

containerd config default | tee /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml  
service containerd restart
service kubelet restart

 

4. 쿠버네티스 설치 확인 및 워커 노드 확인

flannel 까지 설치가 잘 되었다면 아래 명령어 2가지를 통해 워커 노드와의 연결과 각 pod 의 정상 동작을 확인 할 수 있다.

 

1) 각 노드들의 상태 확인

kubectl get node

ready 면 정상이다

2) 노드, 서비스, 네임스페이스, 데몬셋 등등 모든 상태 확인

kubectl get all --all-namespaces

맨 위쪽을 유념해서 보자! 특히 kube-proxy 와 flannel 이 running 상태여야 한다

 

5. 설치하면서 만난 오류 && 해결 방법

1) 마스터 노드에서 pod 를 띄울 경우 포드가 제대로 실행되지 않는 경우 : 0/1 nodes are available

해당 포드의 로그 확인 시 0/1 nodes are available: 1 node(s) had taint {node-role.kubernetes.io/master: }, that the pod didn't tolerate 처럼 에러가 발생하는 경우는 기본적으로 control-plane 노드(master 역할노드) 에서 포드를 스케줄링 할 수 없도록 막아두었기 때문이다. 따라서 아래 명령어를 사용해 스케줄링이 가능하도록 일종의 락을 해제한다.

kubectl taint nodes [마스터노드 호스트명] node-role.kubernetes.io/control-plane-

 

2) kube-proxy 가 crashloopback 상태 일 때 : kube-proxy 실행 오류

이 문제 역시 containerd 관련된 문제로 생각된다. 아래 명령어를 사용해보자

containerd config default | tee /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml  
service containerd restart
service kubelet restart

 

 

3) /run/flannel/subnet.env no such file or directory(마스터, 워커 동일)

해당 에러는 말 그대로 /run/flannel/ 디렉토리 안에 subnet.env 가 생성되어야 하나 모종의 이유로 파일이 생성되지 않은 경우 발생하는 문제이다. 따라서 /run/flannel 로 들어가서 subnet.env 파일을 생성 후 아래 내용을 작성해주자

 

단, init 시 cidr 을 본인과 동일하게 10.244.0.0/16 으로 하지 않고 따로 지정한 경우 알아서 서브넷과 게이트웨이 주소를 넣어주어야한다.

FLANNEL_NETWORK=10.244.0.0/16 // 게이트웨이
FLANNEL_SUBNET=10.244.0.1/24 // 서브넷
FLANNEL_MTU=1450
FLANNEL_IPMASQ=true

 

6. kubernetes cni 관련 초기화

단순히 CIDR 초기화만 필요하다면 1번을 flannel(CNI) 까지 포함한 초기화가 필요하다면 2번을 참고한다.

개인적으로는 flannel 플러그인 까지 깔아 둔 상태에서 에러가 발생한다면 2번을 더 추천한다. 단순히 kubeadm reset 만 하고 다시 하다가 에러가 난다면 솔직히 어디서 에러가 나는지 알기 어렵기 때문이다ㅠㅠ

 

 

 

1) CIDR 만 초기화가 필요한 경우 아주 단순하게 kubeadm reset 과 init , join 을 수행하면 된다

kubeadm reset // master && worker
kubeadm init ~~~~ // master
kubead join ~~~~ // worker

 

2) flannel 설치 후 flannel 설정까지 포함해 완전 초기화가 필요한 경우

이 경우에는 살짝 복잡하다 당연하게도 flannel 의 설정이나 네트워크까지 초기화해야하기 때문이다.

천천히 아래 명령어를 순서대로 수행한다

 

- master

## flannel 삭제
kubectl delete -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml
kubeadm reset

systemctl stop kubelet
systemctl stop docker

## flannel 관련 파일 삭제 ##
rm -rf /var/lib/cni/
rm -rf /etc/cni/
rm -rf /run/flannel

## kube 설정 파일 삭제 ##
rm -rf $HOME/.kube

## 네트워크 설정 삭제 ##
ifconfig cni0 down
ip link delete cni0
ip link delete flannel.1

systemctl start docker

## 가능하다면 서버 reboot 한번 해주자 ##

 

- worker

kubeadm reset

---

Reference

Unable to bring up kubernetes API server

Unable to bring up kubernetes API server

kube-proxy CrashLoopBackOff after kubeadm init

kube-proxy CrashLoopBackOff after kubeadm init

https://github.com/flannel-io/flannel

GitHub - flannel-io/flannel: flannel is a network fabric for containers, designed for Kubernetes

 

https://fliedcat.tistory.com/166

[kubernetes] 설치

https://syhwang.tistory.com/52

[K8S] CNI Weave net dial tcp 127.0.0.1:6784: connect: connection refused, failed to clean up sandbox container

https://sungup.github.io/2019/12/26/Install-K8s-on-Raspberry-Pi-4.html

Install Kubernetes on Raspberry Pi 4

https://truelifer.medium.com/raspberry-pi-4b-%EC%97%90-kubernetes-cluster-%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0-35a1c7be3cbd

Raspberry pi 4B 에 Kubernetes cluster 설치하기