[개발환경 설정] 우분투(리눅스) 환경에서 Docker와 Kubernetes 설치

1. Docker 설치

* 도커 기초 개념

2025.09.28 - [도커] - [도커] 도커(Docker) 기초 개념 정리

[도커] 도커(Docker) 기초 개념 정리

 

(1) 도커 설치를 위한 환경 설정

• ca-certificates: 인증서 관련 패키지
• curl: 파일을 다운로드하기 위한 패키지
• gnupg: 디지털 서명을 사용하기 위한 패키지
• lsb-release: 리눅스 배포판 식별을 위해 필요한 패키지

# 도커를 설치하기 위해 필요한 환경 설정
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release

# 도커 공식 GPG 키를 추가
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 레포지토리 설정
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

 

(2) 도커 설치

# apt 패키지 인덱스 업데이트
sudo apt-get update

# 도커가 설치되면 자동 실행된다.
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 도커가 실행되고 있는지 확인한다.
sudo systemctl status docker

# 도커가 실행되지 않는다면 실행시킨다.
sudo systemctl start docker

 

(3) 도커 설치 확인 및 테스트

# 도커 명령어를 사용자 모드에서도 사용하기 (로그아웃 후 재접속)
sudo usermod -aG docker $USER

# 도커 버전 확인
docker version

# 테스트 이미지 실행
docker run hello-world

---

2. Kubernetes설치

* 쿠버네티스 기초 개념

2025.09.29 - [쿠버네티스] - [쿠버네티스] Kubernetes 기초 개념 정리

[쿠버네티스] Kubernetes 기초 개념 정리

 

(1) UFW 방화벽 설정

UFW (Uncomplicated FireWall)는 리눅스 운영체제에서 작동하는 방화벽이다.

쿠버네티스 클러스터를 구성하기 위한 노드는 각 노드별로 포트 통신이 원할해야 하므로, UFW를 비활성화(inactive) 한다.

# UFW 상태 확인
sudo ufw status

# UFW 비활성화(inactive)
sudo ufw disable

 

(2) 네트워크 설정

# root 권한 획득
sudo -i

# IP4를 포워딩하여, iptables가 연결된 트래픽을 볼 수 있게 한다.
cat <<EOF | sudo tee /etc/modules-load.d/k8s.config
overlay
br_netfilter
EOF

# modeprobe: 리눅스 커널 모듈 관리 도구
# overlay: 리눅스 커널의 네트워크 드라이버, 서로 다른 호스트에 존재하는 파드 간의 네트워크 연결을 가능하게 함.
sudo modprobe overlay

# br_netfilter: 네트워크 패킷 처리 관련 모듈
sudo modprobe br_netfilter

# sysctl 설정(브리지 트래픽 iptables로, IPv4 포워딩 허용)
cat <<'EOF' | sudo tee /etc/sysctl.d/99-kubernetes-cri.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

# 적용
sudo sysctl --system

 

(3) containerd 설정

containerd는 도커 설치 과정에서 apt-get install containerd.io를 통해 이미 설치했다.

 

이렇게 설치한 containerd는 도커 관련 작업을 할 때 사용하는데, 이를 쿠버네티스에서 컨테이너 런타임으로 사용할 수 있도록 설정을 변경한다.

# 설정값을 저장할 디렉터리 생성.
sudo mkdir -p /etc/containerd

# containerd config default를 통해 출력된 기본 설정값들을 config.toml 파일로 저장함.
containerd config default | sudo tee /etc/containerd/config.toml > /dev/null

# config.toml을 수정한다. -> SystemdCgroup을 true로 변경.
sudo vim /etc/containerd/config.toml

# containerd를 재가동하고 작동하는지 확인.
sudo systemctl restart containerd
sudo systemctl enable containerd
sudo systemctl status containerd

sudo apt-get update -y
sudo apt-get install -y containerd cri-tools

(참고)
# (중요1) CRI 플러그인 비활성화 제거
sudo sed -ri 's/^\s*disabled_plugins\s*=.*/disabled_plugins = \[\]/' /etc/containerd/config.toml

# (중요2) systemd cgroup 사용
sudo sed -ri 's/SystemdCgroup\s*=\s*false/SystemdCgroup = true/' /etc/containerd/config.toml

SystemCgroup을 true로 변경하기.

 

(4) Swap 메모리 비활성화

스왑(swap)이란 물리 메모리(RAM)의 용량이 부족할 때 하드 디스크의 일부 공간을 메모리처럼 사용하는 것인데,

쿠버네티스의 kubelet이 이러한 상황을 처리하도록 만들어지지 않았기 때문에 원할한 컨테이너 관리를 위해 비활성화한다.

# 메모리 공간 확인 (Swap 영역이 0으로 설정되어 있다면, 비활성화되어 있는 것이다)
free -h

# root로 실행
sudo -i

# 모든 스왑을 끄고, 다음 부팅때도 안 켜지게 fstab에서 swap 항목을 비활성화
swapoff -a && sed -i '/swap/s/^/#/' /etc/fstab

# 시스템 재부팅
shutdown -r now

 

(5) 쿠버네티스 설치

# apt 패키지 목록 업데이트
sudo apt-get update

# apt-transport-https may be a dummy package; if so, you can skip that package
sudo apt-get install -y apt-transport-https ca-certificates curl

# Kubernetes APT 저장소의 서명키 등록
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

 Kubernetes APT 저장소 추가(v1.34 전용)
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# apt 패키지 목록 업데이트
sudo apt-get update

# kubelet, kubeadm, kubectl 설치 및 버전 고정
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

 

(6) 마스터 노드(Control Plane) 설정

* 최소 사양: CPU: 2 Core, RAM: 2GB

 

Control-plane로 사용할 노드에서 아래 명령어를 실행한다.

# 인증 확인
kubeadm certs check-expiration

# kubeadm이 사용할 수 있는 이미지 리스트 출력
kubeadm config images list

# root 권한
sudo -i

# 쿠버네티스 설치에 필요한 이미지 다운로드
kubeadm config images pull

# 이미지 다운로드 중 "Found multiple CRI endpoints on the host." 에러가 나면 아래 명령어 실행
# CRI가 여러 개 발견되었는데, containerd 하나로 고정하는 명령어
kubeadm config images pull --cri-socket /run/containerd/containerd.sock

# 초기화 및 --apiserver-advertise-address 옵션으로 쿠버네티스 마스터 노드의 IP 주소 입력, --pod-network-cidr로 네트워크 대역 설정.
# calico: 192.168.0.0/16, flannel: 10.244.0.0/16
# 해당 명령어 실행 후 "kubeadm join ~ " 이 구문(쿠버네티스 클러스터에 노드를 추가하는 명령어)을 따로 저장해야함
kubeadm init --apiserver-advertise-address=10.0.2.4 --pod-network-cidr=192.168.0.0/16 --cri-socket /run/containerd/containerd.sock

# 만약 토큰의 발행 시간(24시간)이 만료되었다면 마스터 노드에서 아래 명령어로 재발급한다.
kubeadm token create --print-join-command

# 쿠버네티스 인증서 상태 확인
kubeadm certs check-expiration

# root 권한 해제
exit

# 사용자 권한으로도 쿠버네티스 사용할 수 있도록 설정
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config


# calico로 네트워크 설정

# calico를 설치하기 위해 해당 URL이 존재하는 yaml 파일 실행.
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.3/manifests/tigera-operator.yaml

# calico 설치를 위해 필ㄹ요한 커스텀 리소스를 설치.
curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.3/manifests/custom-resources.yaml -O

# 다운로드한 파일 확인
ls

# 해당 yaml을 활용해 calico 설치.
kubectl create -f custom-resources.yaml

# calico에 대한 파드가 실행 중인지 확인. -> "Ctrl + C" 로 watch에서 빠져나올 수 있음.
watch kubectl get pods -n calico-system

# 쿠버네티스 클러스터 노드를 확인.
kubectl get node -o wide

 

(7) 워커 노드(Worker Node) 설정

* 최소 사양: CPU: 1 Core, RAM: 1GB

# kube 관련 디렉토리 생성.
mkdir -p $HOME/.kube

# 아래 SCP 명령어로 마스터 노드의 kube 설정 파일을 워커 노드로 가져온다.
# 참고: scp -p {USERID}@{IP_ADDRESS}:~/.kube/config ~/.kube/config
scp -p joo@10.0.2.4:~/.kube/config ~/.kube/config

# root 권한
sudo -i

# 앞서 저장했던 쿠버네티스 클러스터에 노드를 추가하는 명령어 입력.
# --cri-socket /run/containerd/containerd.sock 추가. -> 컨테이너 런타임 소켓 지정.
kubeadm join ~ --cri-socket /run/containerd/containerd.sock

# 마스터 노드에서 클러스터 확인
kubectl get node

 

(8) 쿠버네티스로 Hello World! 실행

• kubectl run: 단일 파드 실행
• hello-world: 파드의 이름 지정
• --image=hello-world: Docker hub의 hello-world 이미지 사용
• --restart=Never: 파드가 종료되어도 다시 시작하지 않겠다.

# 마스터 노드에서 작업 실행.
kubectl run hello-world --image=hello-world --restart=Never

# 결과: pod/hello-world created -> hello-world 라는 pod 생성됨.

# 확인
kubectl get pod

 

* Kubectl 명령어

pod 조회

• kubectl get pods

파드 내부 접속

• kubectl exec -it [파드명] -- bash

파드 포트 포워딩

• kubectl port-forward pod/[파드명][로컬 port]:[파드 port]

파드 삭제

• kubectl delete pod [파드명]

디플로이먼트 조회

• kubectl get deployment

디플로이먼트 삭제

• kubectl delete deployment

서비스 조회

• kubectl get service

서비스 삭제

• kubectl delete service

매니페스트 리소스 생성

• kubectl apply -f [매니페스트 파일명]

모든 리소스 삭제

• kubectl delete all --all

Pod 상세 조회

• kubectl describe pod [리소스 이름]

 

(9) 쿠버네티스 삭제

# kubeadm, kubectl, kubelet 패키지 삭제
sudo apt-get purge kubeadm kubectl kubelet

---

참고

• 장철원.(2024). [한 권으로 배우는 도커&쿠버네티스]. 한빛미디어.
• https://www.youtube.com/playlist?list=PLApuRlvrZKohaBHvXAOhUD-RxD0uQ3z0c
• https://kubernetes.io/ko/docs/home/
• https://docs.docker.com/
• https://jbground.tistory.com/107
• https://tech.ktcloud.com/entry/Kubernetes-Control-Plane%EA%B3%BC-%EC%B9%9C%ED%95%B4%EC%A7%80%EA%B8%B0-1