Back-end

GitOps 기반 Kubernetes 배포 자동화 구축하기 (2): kubeadm 설치와 Kustomize 레포 설계

2026-03-023수정

summary: "GitOps 1편의 개념을 바탕으로, Kubernetes Linux 환경 설치와 Kustomize 기반 GitOps 구성 방법을 다룹니다."

"Git이 운영의 단일 진실(SSOT)이라면, 클러스터와 매니페스트 구조는 그 진실을 정확히 실행할 수 있어야 합니다"

1편에서 GitOps의 핵심 개념(선언형, SSOT, 동기화 루프)을 설명했다면, 2편에서는 kubeadm 기반 Kubernetes Linux 환경을 준비하고 Kustomize base + overlays 구조로 GitOps 저장소를 구성하는 과정을 다룹니다.

#1. 전체 구성

  • Kubernetes Runtime: kubeadm + containerd
  • GitOps 구조: Kustomize base + overlays
  • 배포 동기화: Argo CD Application

핵심 원칙:

  • 공통 정의는 base
  • 환경 차이는 overlays
  • 배포 트리거는 Git 변경

#2. Kubernetes Linux 환경 설치

기준: Ubuntu 24.04 LTS, 모든 노드(Control Plane / Worker) 공통

2-1. OS 기본 설정

sudo apt update
sudo apt upgrade -y
sudo timedatectl set-timezone Asia/Seoul
sudo hostnamectl set-hostname <NODE_HOSTNAME>

# swap 비활성화
sudo swapoff -a
sudo sed -i.bak '/swap/d' /etc/fstab

# 커널 모듈
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

sudo sysctl --system

2-2. containerd 설치

sudo apt install -y ca-certificates curl gnupg apt-transport-https software-properties-common
sudo mkdir -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

sudo apt update
sudo apt install -y containerd.io

sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl enable --now containerd

2-3. kubeadm / kubelet / kubectl 설치

# 설치할 Kubernetes 메이저/마이너 버전 (예: v1.30, v1.31)
# 최신 지원 버전은 공식 문서/릴리즈 노트에서 확인 후 지정
K8S_VERSION="v1.30"

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg
sudo mkdir -p /etc/apt/keyrings

curl -fsSL "https://pkgs.k8s.io/core:/stable:/${K8S_VERSION}/deb/Release.key" \
  | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
https://pkgs.k8s.io/core:/stable:/${K8S_VERSION}/deb/ /" \
  | sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
sudo systemctl enable --now kubelet

2-4. Control Plane 초기화

sudo kubeadm config images pull

sudo kubeadm init \
  --pod-network-cidr=192.168.0.0/16 \
  --control-plane-endpoint=<CONTROL_PLANE_ENDPOINT>

kubeconfig 설정:

mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

초기화 실패 시 containerd 재설정:

sudo rm /etc/containerd/config.toml
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd

2-5. CNI 및 기본 스토리지

# Calico
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

# Local Path Provisioner
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.24/deploy/local-path-storage.yaml
kubectl annotate storageclass local-path storageclass.kubernetes.io/is-default-class="true"

주: 위 CNI/스토리지 매니페스트 버전은 작성 시점 기준 예시입니다. 클러스터 버전 업그레이드 또는 보안 패치가 필요한 경우, 각 프로젝트의 최신 릴리즈 노트/공식 설치 문서를 확인해 최신 안정 버전으로 교체해 사용하세요.

2-6. Worker Node 조인

sudo kubeadm join <CONTROL_PLANE_IP>:6443 \
  --token <TOKEN> \
  --discovery-token-ca-cert-hash sha256:<HASH>

클러스터 상태 확인:

kubectl get nodes -o wide
kubectl get pods -A

#3. Kustomize GitOps 레포지토리 구조

gitops-repo/
├── apps/
│   ├── backend/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev-ko/
│   │       ├── dev-en/
│   │       ├── staging/
│   │       └── prod/
│   ├── front/
│   │   ├── base/
│   │   └── overlays/
│   ├── edge/
│   │   ├── base/
│   │   └── overlays/
│   ├── foundation/
│   │   ├── base/
│   │   └── overlays/
│   └── database/
│       ├── base/
│       └── overlays/
└
  • apps/*/base: 공통 리소스
  • apps/*/overlays/<env>: 환경별 패치

#4. Kustomize 작성 예시

4-1. base

# apps/backend/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
# apps/backend/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-backend
spec:
  selector:
    matchLabels:
      app: app-backend
  template:
    metadata:
      labels:
        app: app-backend
    spec:
      containers:
        - name: backend
          image: registry.example.com/app-backend:latest
          ports:
            - containerPort: 8080

4-2. overlay

# apps/backend/overlays/dev-ko/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app-dev-ko
resources:
  - ../../base
patchesStrategicMerge:
  - patch-deployment.yaml
images:
  - name: registry.example.com/app-backend
    newTag: dev-ko-2026-03-02
# apps/backend/overlays/dev-ko/patch-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-backend
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: backend
          env:
            - name: SPRING_PROFILES_ACTIVE
              value: dev
            - name: LOCALE
              value: ko

#5. Argo CD 구성 파일 구조

k8s/argocd/
├── install/
│   ├── kustomization.yaml
│   ├── configs/
│   │   ├── argocd-cm.yaml
│   │   └── argocd-rbac-cm.yaml
│   └── patches/
│       └── argocd-server-nodeport.yaml
└── apps/
    ├── kustomization.yaml
    ├── values.env
    ├── kustomizeconfig/
    ├── foundation-application.yaml
    ├── database-application.yaml
    ├── backend-application.yaml
    ├── frontend-application.yaml
    └── edge-application.yaml

#6. Argo CD 적용 명령어

사전 리소스 적용:

./scripts/install.sh ENV_FILE=prod.env

Argo CD 앱 변수 설정:

vi k8s/argocd/apps/values.env

Argo CD 설치:

kubectl apply -k k8s/argocd/install
kubectl -n claritrace-argocd rollout status deploy/argocd-server

Application 반영:

kubectl apply -k k8s/argocd/apps

초기 admin 비밀번호 확인:

kubectl -n claritrace-argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d && echo

#7. 참고: HostPath 기반 PVC 초기 디렉터리 준비

# 디렉터리 생성
sudo mkdir -p /data/app/dev-en/db
sudo mkdir -p /data/app/dev-en/storage

# DB 권한
sudo chown -R 1001:1001 /data/app/dev-en/db
sudo chmod -R 775 /data/app/dev-en/db

# Storage 권한
sudo chmod -R 777 /data/app/dev-en/storage

환경마다 /data/app/<env>/... 패턴으로 경로를 분리해 사용합니다.

#8. 정리

  • Kubernetes Linux 설치는 kubeadm + containerd 기준으로 고정
  • GitOps 레포는 Kustomize base + overlays 구조로 분리
  • Argo CD는 install과 apps를 분리해 관리

이 구조를 기준으로 하면 환경별 차이를 오버레이로 통제하면서 선언형 배포 흐름을 유지할 수 있습니다.

#9. 참고 링크