1. kubeadm 을 이용한 쿠버네티스 설치 - OnPremiss

1. Docker Install

Docker docs를 기준으로 설치하겠습니다. (25년 8월 기준)

Jumpstart your client-side server applications with Docker Engine on Ubuntu. This guide details prerequisites and multiple methods to install Docker Engine on Ubuntu.

https://docs.docker.com/engine/install/ubuntu/

Docker apt저장소를 설정합니다.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
Shell
복사

Docker 패키지를 설치합니다.

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Shell
복사

3. 이미지를 실행하여 설치가 성공적으로 완료되었는지 확인하세요.

sudo docker run hello-world
Shell
복사

2. Kubernetes Install

Kubernetes docs를 기준으로 설치하겠습니다. (25년 8월 기준)

kubeadm 설치하기

이 페이지에서는 kubeadm 툴박스 설치 방법을 보여준다. 이 설치 프로세스를 수행한 후 kubeadm으로 클러스터를 만드는 방법에 대한 자세한 내용은 kubeadm으로 클러스터 생성하기 페이지를 참고한다. 시작하기 전에 호환되는 리눅스 머신. 쿠버네티스 프로젝트는 데비안 기반 배포판, 레드햇 기반 배포판, 그리고 패키지 매니저를 사용하지 않는 경우에 대한 일반적인 가이드를 제공한다. 2 GB 이상의 램을 장착한 머신. (이 보다 작으면 사용자의 앱을 위한 공간이 거의 남지 않음) 2 이상의 CPU. 클러스터의 모든 머신에 걸친 전체 네트워크 연결.

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

1. 설치 전 환경설정

Swap 비활성화

swapoff -a && sed -i '/swap/s/^/#/' /etc/fstab

# 메모리 상태 확인
sudo free -m
Shell
복사

위의 명령어를 실행 시 root 계정의 권한이 없다면 ‘swapoff: Not superuser.’ 와 같은 에러가 발생합니다. 해당 경우 아래와 같이 해결할 수 있습니다.

# root 계정의 비밀번호를 설정합니다.
sudo passwd root

# root 계졍에 로그인합니다.
su - 
Shell
복사

이 후 필수 포트인 6443 포트를 확인해 줍니다.

nc 127.0.0.1 6443 -zv -w 2
Shell
복사

포트가 닫혀있다면 열어주어야하는데 두가지 방법이있습니다.

방화벽 disable

sudo apt-get install -y firewalld
systemctl stop firewalld
systemctl disable firewalld
Shell
복사

특정 포트만 열기

아래의 코드들을 이용해 포트를 개방합니다.

# 방화벽 예외 설정(마스터, 워커)
sudo apt-get install -y firewalld
sudo systemctl start firewalld
sudo systemctl enable firewalld

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https

# 마스터 노드일 경우
sudo firewall-cmd --permanent --add-port=6443/tcp
sudo firewall-cmd --permanent --add-port=2379-2380/tcp
sudo firewall-cmd --permanent --add-port=10250-10252/tcp
sudo firewall-cmd --permanent --add-port=8285/udp
sudo firewall-cmd --permanent --add-port=8472/udp
sudo firewall-cmd --reload

# 워커 노드일 경우
sudo firewall-cmd --permanent --add-port=10250/tcp
sudo firewall-cmd --permanent --add-port=30000-32767/tcp
sudo firewall-cmd --permanent --add-port=8285/udp
sudo firewall-cmd --permanent --add-port=8472/udp
sudo firewall-cmd --permanent --add-port=26443/tcp
sudo firewall-cmd --reload

# 방화벽 활성화 확인
systemctl status firewalld
Shell
복사

포트가 잘열렸는지 확인합니다.

# 열린 포트 확인
sudo firewall-cmd --list-all

# 열린 포트 확인
sudo netstat -tlnp

# 다른 노드의 포트 점검
telnet [ip] [port]
ex) telnet 192.168.100.128 6443

>> 
Trying 192.168.111.128...
telnet: Unable to connect to remote host: Connection refused
# Trying 192.168.111.128... 만 계속 나오면 방화벽 오픈되어 있지 않음
# Connection refuesed가 나오면 방화벽 오픈은 되어 있으나 프로세스가 올라가 있지 않은 상태

# 방법2
curl -v telnet://[ip]:[port]
Shell
복사

IPv4를 포워딩하여 iptables가 브리지된 트래픽을 보게 하기

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

sudo modprobe overlay
sudo modprobe br_netfilter

# 필요한 sysctl 파라미터를 설정하면, 재부팅 후에도 값이 유지된다.
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# 재부팅하지 않고 sysctl 파라미터 적용하기
sudo sysctl --system
Shell
복사

2. kubeadm, kubectl, kubelet 설치

apt 패키지 색인을 업데이트하고, 쿠버네티스 apt 리포지터리를 사용하는 데 필요한 패키지를 설치한다.

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg
Shell
복사

GPG 키 저장 디렉터리 생성

sudo mkdir -p -m 755 /etc/apt/keyrings
Shell
복사

구글 클라우드의 공개 사이닝 키를 다운로드 한다.

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
Shell
복사

• Release 파일이 없음 오류: apt.kubernetes.io 대신 pkgs.k8s.io 사용 • GPG 키 오류: gpg --dearmor로 GPG 키 변환 후 /etc/apt/keyrings에 저장

쿠버네티스 apt 리포지터리를 추가한다

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
Shell
복사

apt 패키지 색인을 업데이트하고, kubelet, kubeadm, kubectl을 설치하고 해당 버전을 고정한다.

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
Shell
복사

버전확인

kubectl version --client
kubeadm version
kubelet --version
Shell
복사

systemctl start kubelet
systemctl enable kubelet
Shell
복사

3. control-plane 구성

control-plane node 초기화

kubeadm init <args>
Shell
복사

아래의 경우는 containerd가 CRI v1 API를 제공하지 않거나 비활성화(구버전이거나 cri 플러그인이 꺼져 있거나, 설정이 기본값이 아님) 된 상태입니다.

[init] Using Kubernetes version: v1.33.4
[preflight] Running pre-flight checks
W0823 12:36:20.768155    1464 checks.go:1065] [preflight] WARNING: Couldn't create the interface used for talking to the container runtime: failed to create new CRI runtime service: validate service connection: validate CRI v1 runtime API for endpoint "unix:///var/run/containerd/containerd.sock": rpc error: code = Unimplemented desc = unknown service runtime.v1.RuntimeService
	[WARNING Firewalld]: firewalld is active, please ensure ports [6443 10250] are open or your cluster may not function correctly
	[WARNING SystemVerification]: cgroups v1 support is in maintenance mode, please migrate to cgroups v2
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action beforehand using 'kubeadm config images pull'
error execution phase preflight: [preflight] Some fatal errors occurred:
failed to create new CRI runtime service: validate service connection: validate CRI v1 runtime API for endpoint "unix:///var/run/containerd/containerd.sock": rpc error: code = Unimplemented desc = unknown service runtime.v1.RuntimeService[preflight] If you know what you are doing, you can make a check non-fatal with `--ignore-preflight-errors=...`
To see the stack trace of this error execute with --v=5 or higher
Shell
복사

위와 같은 에러가 발생한다면 아래와 같이해결할 수 있습니다.

# /etc/containerd/config.toml 파일에서 ["cri"] -> [""]
vi /etc/containerd/config.toml

# containerd 재실행
sudo systemctl restart containerd
sudo systemctl status containerd --no-pager
Shell
복사

init 이 완료되면 아래와 같은 구문과 token이 생성됩니다.

To start using your cluster, you need to run the following as a regular user:
# init이 완료된 후 config 복사 및 권한을 설정
  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

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

You can now join any number of machines by running the following on each node
as root:
# 아래의 코드를 복사 및 저장해둡니다.
  kubeadm join <control-plane-host>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>
Shell
복사

kudeam join 로 시작하는 명령어는 별도로 저장해둡니다.

Installing a Pod network add-on

본 글에서는 Pod 간의 통신을 위해 weave를 사용하였습니다.

weave를 설치하기 위한 내용은 아래의 사이트에서 확인할 수 있습니다.

weave/site/kubernetes/kube-addon.md at master · weaveworks/weave

Simple, resilient multi-host containers networking and more. - weaveworks/weave

https://github.com/weaveworks/weave/blob/master/site/kubernetes/kube-addon.md#install

kubectl apply -f https://github.com/weaveworks/weave/releases/download/v2.8.1/weave-daemonset-k8s.yaml
Shell
복사

설치가 완료되면 아래의 코드를 실행 시 status가 NotReady에서 Ready로 바뀌게됩니다.

kubectl get nodes
Shell
복사

4. worker node 구성 및 설치확인

위에서 저장하였던 명령어를 worker node에서 실행합니다.

kubeadm join <control-plane-host>:<control-plane-port> --token <token> --discovery-token-ca-cert-hash sha256:<hash>
Shell
복사

실행이 완료되면 Master Node에서 아래와 같이 확인할 수 있습니다.