Spring Boot + PostgreSQL Todo API를 직접 컨테이너화하고, Docker Compose → Kubernetes → GitOps(CI/CD) 순서로 배포 경험을 쌓는 실무 중심 3일 과정.

1. 과정 개요
2. 학습 대상 및 선수 지식
3. 환경 요구사항 및 버전 명세
4. 3일 커리큘럼 전체 구성표
5. 1일차 상세 기획 — Docker / Docker Compose
6. 2일차 상세 기획 — Kubernetes 배포
7. 3일차 상세 기획 — GitHub Actions + Helm + Argo CD GitOps
8. 실습 앱 소개
9. 프로젝트 파일 구조
10. 강의 운영 총괄 원칙
11. 사전 설치 점검 방법

1일차                         2일차                         3일차
─────────────────────         ─────────────────────         ─────────────────────
Dockerfile 작성          →    K8s Deployment/Service   →    GitHub Actions CI
docker build                  ConfigMap / Secret             이미지 태깅
docker compose up             kubectl 진단 명령               Helm 차트 구조 이해
Spring + PostgreSQL 연동       운영 관점 문제 진단              Argo CD GitOps / 롤백
Kubernetes 활성화 준비          → 3일차 배포 소스 확보           빌드-패키징-배포-롤백 한 사이클

• 운영/배포 담당 개발자
• DevOps 엔지니어 지망자
• SRE 지망자

Java / Gradle 별도 설치 불필요 제공되는 Dockerfile에 멀티스테이지 빌드가 포함되어 있어, docker build 한 번으로 JAR 빌드부터 이미지 생성까지 자동 처리된다.

기본 실습 설명은 Antigravity IDE 기준이며, VS Code 또는 IntelliJ IDEA를 사용해도 된다. 아래 확장은 VS Code를 사용할 때의 권장 항목이다.

핵심 메시지: 1일차는 컨테이너를 "설명"하는 날이 아니라, Spring 애플리케이션과 PostgreSQL을 직접 컨테이너화하고 실행해보며 이후 Kubernetes 실습의 기반을 만드는 날이다.

• Docker Desktop 기반의 로컬 컨테이너 실습 환경을 준비할 수 있다.
• Dockerfile을 이용해 Spring 애플리케이션 이미지를 생성할 수 있다.
• Docker Compose로 Spring 애플리케이션과 PostgreSQL을 함께 실행할 수 있다.
• Docker Desktop의 Kubernetes 기능을 활성화해 2일차 쿠버네티스 배포 실습 준비를 완료할 수 있다.

• 이론 비중을 낮추고, 실습 성공 경험을 누적시키는 방향으로 운영한다.
• Spring 코드는 신규 작성보다 템플릿 프로젝트를 제공하는 편이 학습 집중도와 시간 운영 측면에서 유리하다.
• PostgreSQL은 DBA 관점 심화보다 애플리케이션 연동과 설정 분리 경험에 초점을 둔다.
• Kubernetes는 1일차에 "배포"까지 밀어 넣기보다, 활성화와 준비 상태 확인까지만 다루는 편이 전체 커리큘럼 흐름에 안정적이다.

• Docker Desktop
• Antigravity IDE 권장 (VS Code 또는 IntelliJ IDEA 대체 가능)
• 예제 Spring Boot 프로젝트 (제공)
• kubectl

• Docker Desktop이 정상 동작한다.
• Spring 애플리케이션 이미지를 직접 빌드할 수 있다.
• Docker Compose로 Spring + PostgreSQL 통합 실행이 가능하다.
• Docker Desktop Kubernetes가 활성화되어 있고 kubectl로 상태 확인이 가능하다.

핵심 메시지: 2일차는 컨테이너 실행에서 끝나지 않고, 쿠버네티스 리소스로 애플리케이션을 배포하고 설정을 분리하며 서비스 상태를 점검하는 날이다.

• Docker Desktop Kubernetes 환경에서 기본 리소스를 조회하고 배포 흐름을 이해할 수 있다.
• Spring 애플리케이션과 PostgreSQL을 Deployment와 Service로 배포할 수 있다.
• ConfigMap과 Secret을 이용해 설정값과 민감정보를 분리할 수 있다.
• 배포 후 Pod, Service, 로그 상태를 점검하고 기본적인 문제를 진단할 수 있다.

• 초점은 "쿠버네티스 명령 암기"가 아니라 "배포 단위가 어떻게 달라지는지 이해"에 둔다.
• PostgreSQL까지 쿠버네티스에 올리더라도 운영 심화보다 애플리케이션 연동과 서비스 확인에 집중한다.
• kubectl apply만 반복하지 말고 get, describe, logs를 반드시 함께 사용하게 해야 운영 관점이 형성된다.
• 매니페스트는 처음부터 길게 주기보다 Deployment → Service → ConfigMap → Secret을 단계적으로 추가하는 방식이 학습 부담을 줄인다.

• Docker Desktop Kubernetes 활성화 완료 환경
• 1일차에 사용한 Spring Boot 이미지 또는 예제 프로젝트
• PostgreSQL용 기본 매니페스트 (제공)
• Antigravity IDE 권장 (VS Code 또는 IntelliJ IDEA 대체 가능)
• kubectl
• 실습용 namespace 및 YAML 파일 템플릿 (제공)

• 로컬 Kubernetes 환경에서 Spring 애플리케이션과 PostgreSQL을 각각 배포할 수 있다.
• Deployment, Service, ConfigMap, Secret의 역할을 구분 설명할 수 있다.
• 배포 후 상태 확인 명령으로 기본적인 문제를 진단할 수 있다.
• 3일차의 GitHub Actions + Argo CD 기반 자동화 실습으로 이어질 수 있는 매니페스트 구조를 확보한다.

핵심 메시지: 3일차는 코드 변경이 빌드되고, 이미지가 만들어지고, Git 상태를 기준으로 Kubernetes에 반영되는 전체 흐름을 경험하는 날이다.

• GitHub Actions로 빌드와 테스트를 자동화할 수 있다.
• Docker 이미지 버전을 확인하고, 배포 매니페스트 또는 Helm values에 수동으로 반영하는 GitOps 기본 흐름을 수행할 수 있다.
• Helm chart의 기본 구성(Chart.yaml, values.yaml, templates/)과 values 기반 배포 설정 변경 방식을 설명할 수 있다.
• Argo CD로 로컬 Kubernetes 클러스터에 선언형 배포를 적용할 수 있다.
• 배포 상태를 확인하고 롤백 또는 재동기화로 복구할 수 있다.

3일차 Argo CD 실습은 2일차에서 만든 todo-app 네임스페이스와 Service, ConfigMap, Secret, PostgreSQL 리소스가 클러스터에 남아 있다는 전제로 진행한다. 3일차는 workspace/k8s-day3-gitops의 애플리케이션 Deployment로 GitOps 흐름을 먼저 잡은 뒤, Helm을 별도 학습 주제로 다룬다. Helm 파트에서는 같은 앱 배포를 Chart.yaml, values.yaml, templates/ 구조로 재구성하고, 이미지 태그 변경 지점을 values로 분리하는 방식을 학습한다. 2일차 기반 리소스(todo-app Service, postgres Service/Deployment/PVC, app-config, db-secret)는 다시 생성하지 않는다.

코드 push (GitHub main 브랜치)
        │
        ▼
GitHub Actions (CI)
  ├─ 1. Gradle 빌드 & 테스트
  ├─ 2. Docker 이미지 빌드
  └─ 3. GHCR push (태그: 7자리 short SHA / latest)
                │
                ▼
  수강생이 GHCR 이미지 태그 확인
                │
                ▼
  workspace/k8s-day3-gitops/app-deployment.yml 이미지 태그 수동 변경
                │
                ▼
  Helm chart/values로 같은 변경 지점 구조화
                │
                ▼
  Git commit & push
                │
                ▼
  Argo CD OutOfSync 감지
                │
                ▼
  Argo CD Sync → 클러스터 반영
                │
                ▼
  kubectl rollout status 확인

# 1. argocd 네임스페이스 생성
kubectl create namespace argocd

# 2. Argo CD 설치 (stable 버전)
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 3. Pod 기동 완료 대기 (전체 Running까지 수 분 소요)
kubectl get pods -n argocd -w

# 4. UI 접근을 위한 포트 포워딩 (별도 터미널)
kubectl port-forward svc/argocd-server -n argocd 8443:443

# 5. 초기 admin 비밀번호 확인
kubectl get secret argocd-initial-admin-secret -n argocd `
  -o jsonpath="{.data.password}" | `
  [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_))

# 브라우저에서 https://localhost:8443 접속 (ID: admin)

# CLI로 등록
argocd login localhost:8443 --insecure

argocd app create todo-app `
  --repo https://github.com/[계정명]/docker_k8s_tutorial.git `
  --path workspace/k8s-day3-gitops/helm `
  --dest-server https://kubernetes.default.svc `
  --dest-namespace todo-app

Argo CD가 workspace/k8s-day3-gitops/helm 경로에서 Chart.yaml을 감지하면 자동으로 Helm source로 인식한다. 이미지 태그 변경은 values.yaml의 image.tag에서 수행한다.

• 도구 소개보다 빌드-패키징-배포-롤백이 한 흐름으로 이어진다는 경험을 주는 데 집중한다.
• GitHub Actions는 CI, Helm은 배포 패키징, Argo CD는 CD/GitOps로 역할을 명확히 분리하면 수강생 이해도가 높다.
• 자동 동기화만 강조하면 롤백 개념이 흐려질 수 있으므로, 처음에는 수동 Sync와 롤백을 보여준 뒤 자동화로 넘어가는 편이 좋다.
• 로컬 Kubernetes 환경이므로 외부 클라우드 연결 이슈 없이 GitOps 개념 자체를 학습하는 데 집중한다.

• Docker Desktop Kubernetes 활성화 완료 환경
• GitHub 저장소 (앱 소스 + 배포 매니페스트)
• GitHub Actions Workflow 파일 (제공)
• 수강생 개인 GitHub fork 저장소
• Argo CD 설치 YAML 또는 manifest
• kubectl, argocd CLI (선택)
• 1일차/2일차에서 사용한 Spring Boot + PostgreSQL 예제

• GitHub Actions로 CI가 자동 실행된다.
• Argo CD가 Git 저장소를 기준으로 로컬 Kubernetes에 동기화된다.
• 버전 태그와 배포 이력이 연결되어 추적 가능하다.
• 장애 또는 잘못된 배포 상황에서 롤백 절차를 수행할 수 있다.

Spring Boot 3.2 + PostgreSQL 16 기반의 Todo 목록 API. 동일한 이미지에서 환경변수만 교체해 로컬·Compose·Kubernetes·GitOps 환경 모두 동작한다.

docker_k8s_tutorial/
│
├── README.md                          ← 이 강의기획서
│
├── 01_design/                         ← 과정 기획 및 설계 가이드
│   ├── course-design-detail.md
│   ├── instructor-runbook.md
│   └── slide-theme.md
│
├── 02_lectures/                       ← 이론 강의 슬라이드
│   ├── day1/
│   ├── day2/
│   └── day3/
│
├── 03_practices/                      ← 실습 자료 모음
│   ├── day1/                          ← 1일차 가이드 문서
│   ├── day2/                          ← 2일차 가이드 문서
│   ├── day3/                          ← 3일차 가이드 문서
│   │
│   └── workspace/                     ← 통합 실습 작업 공간
│       ├── spring-app/                ← 공통 실습 앱 소스
│       │   ├── Dockerfile
│       │   ├── build.gradle
│       │   └── src/main/java/com/tutorial/app/
│       │
│       ├── compose.yml                ← Spring + PostgreSQL Compose
│       ├── .env                       ← 환경변수 분리 예제
│       │
│       ├── k8s-day2/                  ← 2일차 Kubernetes 매니페스트
│       │   ├── namespace.yml
│       │   ├── postgres-pvc.yml
│       │   ├── postgres-deployment.yml
│       │   ├── postgres-service.yml
│       │   ├── app-configmap.yml      ← DB 호스트/포트/이름
│       │   ├── app-secret.yml         ← DB 계정/비밀번호 (base64)
│       │   ├── app-deployment.yml
│       │   └── app-service.yml        ← NodePort (localhost:30080)
│       │
│       └── k8s-day3-gitops/           ← 3일차 GitOps 매니페스트 및 Helm
│           ├── app-deployment.yml     ← raw manifest (수동 변경 대상)
│           └── helm/                  ← Helm chart
│               ├── Chart.yaml
│               ├── values.yaml
│               └── templates/
│
└── .github/
    └── workflows/
        └── ci.yml                     ← GitHub Actions CI (GHCR push)

수강 전 아래 명령을 모두 실행해 오류가 없는지 확인한다.

# Docker 버전 확인
docker version

# Compose 플러그인 확인
docker compose version

# Docker 정상 동작 확인 (hello-world 컨테이너 실행)
docker run --rm hello-world

# Git 버전 확인
git --version

# Kubernetes (Docker Desktop에서 활성화 후)
kubectl version --client
kubectl get nodes

Client: Docker Engine - Community
 Version: 26.x.x

Docker Compose version v2.x.x

git version 2.4x.x

kubectl version: v1.29.x

NAME             STATUS   ROLES           AGE
docker-desktop   Ready    control-plane   Xd