6. Jenkins와 Argo CD로 이해하는 CI/CD

 

📚 Docker & Kubernetes 시리즈

이전 글에서는 Docker Image를 저장하고 공유하기 위한 Docker Registry에 대해 알아봤다.

Spring Boot 애플리케이션을 빌드해 Docker Image를 생성하고, 생성한 이미지를 Registry에 Push하면 개발·스테이지·운영 환경에서 동일한 이미지를 사용할 수 있다.

 

그렇다면 개발자가 소스를 Git에 Push한 이후 다음 과정은 누가 수행할까?

소스 코드 빌드
Docker Image 생성
Docker Registry 업로드
Kubernetes 배포
Pod 상태 확인

 

이 과정을 매번 개발자가 직접 처리하면 시간이 오래 걸리고, 명령어 누락이나 설정 오류가 발생할 수 있다.

따라서 실무에서는 Jenkins와 Argo CD 같은 도구를 이용해 빌드와 배포 과정을 자동화한다.

이번 글에서는 CI/CD의 개념과 Jenkins, Argo CD가 각각 어떤 역할을 담당하는지 알아보자.

 

 

---

CI/CD란?

CI/CD는 애플리케이션의 빌드, 테스트, 배포 과정을 자동화하는 방법이다.

 

CI는 Continuous Integration의 약자로 지속적 통합을 의미한다.

CD는 Continuous Delivery 또는 Continuous Deployment의 약자로 지속적 제공 또는 지속적 배포를 의미한다.

CI
→ 소스 코드를 빌드하고 테스트하여 배포 가능한 결과물을 만드는 과정

CD
→ 만들어진 결과물을 개발·스테이지·운영 환경에 배포하는 과정

 

 

전체 흐름을 간단하게 표현하면 다음과 같다.

개발자가 Git에 소스 Push
        │
        ▼
CI
        │
        ├─ 소스 Checkout
        ├─ 테스트
        ├─ 애플리케이션 빌드
        ├─ Docker Image 생성
        └─ Registry Push
        │
        ▼
CD
        │
        ├─ 배포 설정 반영
        ├─ Kubernetes 배포
        ├─ 새로운 Pod 생성
        └─ Health Check
        │
        ▼
서비스 반영

 

Jenkins는 주로 CI 영역을 담당하고, Argo CD는 Kubernetes 환경의 CD 영역을 담당한다.

 

 

---

CI가 필요한 이유

여러 개발자가 하나의 프로젝트를 함께 개발한다고 가정해 보자.

 

각 개발자는 자신의 브랜치에서 코드를 수정한 후 Git Repository에 Push하거나 Merge Request를 생성한다.

이때 다음과 같은 문제가 발생할 수 있다.

로컬에서는 실행되지만 서버에서는 빌드되지 않는 문제
필수 테스트가 누락되는 문제
서로 다른 Java 또는 Node.js 버전을 사용하는 문제
Docker Image Tag를 잘못 지정하는 문제
Registry Push 명령을 빠뜨리는 문제

 

CI를 적용하면 소스가 변경될 때마다 동일한 환경에서 정해진 절차를 자동으로 실행할 수 있다.

Git Push
        │
        ▼
자동 빌드
        │
        ▼
자동 테스트
        │
        ▼
빌드 결과 확인

 

모든 개발자가 같은 빌드 절차를 사용하므로 개인의 로컬 환경 차이로 발생하는 문제를 줄일 수 있다.

 

 

---

CD가 필요한 이유

Docker Image를 Registry에 Push했다고 해서 애플리케이션이 자동으로 서비스에 반영되는 것은 아니다.

Kubernetes에서 새로운 이미지를 사용하려면 Deployment 등의 배포 설정을 변경하고, 새로운 Pod가 생성되도록 해야 한다.

 

개발자가 매번 직접 다음 작업을 수행할 수도 있다.

배포할 Image Tag 확인
Kubernetes Manifest 수정
kubectl 명령 실행
새로운 Pod 생성 여부 확인
애플리케이션 Health Check 확인
기존 Pod 종료 여부 확인

 

하지만 환경과 애플리케이션이 많아질수록 수동 배포는 관리하기 어려워진다.

CD 도구를 사용하면 배포 설정 변경부터 Kubernetes 반영까지의 과정을 일관된 방식으로 관리할 수 있다.

 

 

---

Jenkins란?

Jenkins는 빌드, 테스트, 배포 작업을 자동화할 수 있는 오픈소스 자동화 서버이다.

 

실무에서는 주로 다음 작업에 사용한다.

Git Repository에서 소스 가져오기
Gradle 또는 Maven 빌드
단위 테스트 실행
정적 분석 실행
Docker Image 생성
Docker Registry에 Image Push
배포 설정의 Image Tag 변경
다른 배포 시스템 호출

 

Jenkins에서 실행되는 작업의 단위를 일반적으로 Job이라고 한다.

여러 작업을 단계별로 구성한 것을 Pipeline이라고 한다.

 

 

---

Jenkins Pipeline의 기본 흐름

Spring Boot 애플리케이션을 기준으로 Jenkins Pipeline은 다음과 같이 구성할 수 있다.

1. Checkout
2. Test
3. Gradle Build
4. Docker Build
5. Docker Push
6. 배포 설정 변경

 

흐름으로 표현하면 다음과 같다.

Git Repository
        │
        ▼
Jenkins
        │
        ├─ Source Checkout
        ├─ ./gradlew test
        ├─ ./gradlew bootJar
        ├─ docker build
        ├─ docker push
        └─ 배포 Image Tag 변경
        │
        ▼
Docker Registry

 

Jenkins가 모든 단계를 성공적으로 완료하면 배포 가능한 Docker Image가 Registry에 저장된다.

 

 

---

Jenkinsfile이란?

Jenkins Pipeline은 Jenkins 관리 화면에서 직접 설정할 수도 있지만, 일반적으로 Jenkinsfile을 이용해 코드로 관리할 수 있다.

 

프로젝트 구조는 다음과 같을 수 있다.

my-spring-app
├── src
├── build.gradle
├── Dockerfile
├── Jenkinsfile
└── settings.gradle

 

 

간단한 Jenkinsfile 예시는 다음과 같다.

pipeline {
    agent any

    environment {
        IMAGE_NAME = 'registry.example.com/my-spring-app'
        IMAGE_TAG = "${BUILD_NUMBER}"
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Test') {
            steps {
                sh './gradlew test'
            }
        }

        stage('Build') {
            steps {
                sh './gradlew bootJar'
            }
        }

        stage('Docker Build') {
            steps {
                sh "docker build -t ${IMAGE_NAME}:${IMAGE_TAG} ."
            }
        }

        stage('Docker Push') {
            steps {
                sh "docker push ${IMAGE_NAME}:${IMAGE_TAG}"
            }
        }
    }
}

 

 

이 Pipeline이 실행되면 다음 작업이 순서대로 수행된다.

소스 Checkout
→ 테스트
→ JAR 생성
→ Docker Image 생성
→ Registry Push

 

실제 환경에서는 Registry 인증, 빌드 캐시, 보안 검사, 실패 알림 등의 설정이 추가될 수 있다.

 

 

---

Jenkins Build Number를 Image Tag로 사용하기

Docker Image에는 배포 버전을 식별할 수 있는 Tag가 필요하다.

Jenkins에서는 Build Number를 Image Tag로 활용할 수 있다.

 

예를 들어 Jenkins Build Number가 152라면 다음과 같은 이미지가 생성된다.

registry.example.com/my-spring-app:152

 

 

Git Commit Hash를 사용할 수도 있다.

registry.example.com/my-spring-app:a1b2c3d

 

 

날짜와 Build Number를 조합하는 방법도 있다.

registry.example.com/my-spring-app:20260723-152

 

 

고유한 Image Tag를 사용하면 다음 정보를 추적하기 쉽다.

어떤 Jenkins 빌드에서 생성되었는지
어떤 Git Commit을 기준으로 생성되었는지
현재 개발·스테이지·운영 환경에 어떤 버전이 배포되었는지
문제가 발생했을 때 어떤 버전으로 복구해야 하는지

 

운영 환경에서는 동일한 latest Tag를 반복해서 사용하는 것보다 변경되지 않는 고유한 Tag를 사용하는 것이 관리에 유리하다.

 

 

---

Argo CD란?

Argo CD는 Kubernetes 환경에서 애플리케이션 배포를 관리하는 GitOps 기반의 CD 도구이다.

 

Argo CD는 Git Repository에 저장된 Kubernetes 배포 설정을 기준으로 실제 Kubernetes 상태를 관리한다.

여기서 중요한 점은 Argo CD가 단순히 Docker Registry에 새로운 이미지가 등록되었다는 사실만 보고 자동으로 배포하는 도구는 아니라는 것이다.

Argo CD가 기본적으로 확인하는 대상은 Git에 저장된 배포 설정이다.

 

예를 들어 Git에 다음과 같은 Kubernetes Deployment 설정이 있다고 가정해 보자.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-spring-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-spring-app
  template:
    metadata:
      labels:
        app: my-spring-app
    spec:
      containers:
        - name: my-spring-app
          image: registry.example.com/my-spring-app:152
          ports:
            - containerPort: 8080

 

 

image 값이 변경되어 Git에 반영되면 Argo CD가 해당 변경 사항을 확인한다.

image: registry.example.com/my-spring-app:153

 

이후 Argo CD가 Git의 설정을 Kubernetes에 반영하면 새로운 Image를 사용하는 Pod가 생성된다.

 

 

---

GitOps란?

GitOps는 Git Repository를 시스템의 원하는 상태를 관리하는 기준으로 사용하는 방식이다.

Kubernetes 배포 설정을 Git에 저장하고, 실제 Kubernetes 상태가 Git의 설정과 일치하도록 관리한다.

Git Repository
→ 원하는 상태

Kubernetes Cluster
→ 실제 상태

 

 

예를 들어 Git에는 Pod를 2개 실행하도록 설정되어 있다고 가정해 보자.

replicas: 2

 

 

하지만 실제 Kubernetes에는 Pod가 1개만 실행 중이라면 두 상태가 일치하지 않는다.

Git의 원하는 상태
→ Pod 2개

Kubernetes의 실제 상태
→ Pod 1개

 

Argo CD는 이 차이를 확인하고 Kubernetes 상태를 Git의 설정과 맞출 수 있다.

 

 

---

Argo CD의 Sync 상태

Argo CD에서는 Git에 정의된 상태와 Kubernetes의 실제 상태가 일치하는지를 Sync 상태로 확인할 수 있다.

 

대표적인 상태는 다음과 같다.

Synced
→ Git의 배포 설정과 Kubernetes의 실제 상태가 일치함

OutOfSync
→ Git의 배포 설정과 Kubernetes의 실제 상태가 일치하지 않음

 

 

예를 들어 Git의 Image Tag가 153으로 변경되었지만 Kubernetes에서는 아직 152를 사용하고 있다면 OutOfSync 상태가 될 수 있다.

Git
→ my-spring-app:153

Kubernetes
→ my-spring-app:152

Argo CD
→ OutOfSync

 

 

동기화가 완료되면 Kubernetes에서도 153 이미지를 사용하게 되고 상태가 Synced로 변경된다.

Git
→ my-spring-app:153

Kubernetes
→ my-spring-app:153

Argo CD
→ Synced

 

 

---

Argo CD의 Health 상태

Sync 상태는 Git 설정과 Kubernetes 상태가 일치하는지 보여준다.

Health 상태는 Kubernetes Resource가 정상적으로 동작하는지 보여준다.

 

대표적으로 다음과 같은 상태가 표시될 수 있다.

Healthy
→ Resource가 정상적으로 동작 중

Progressing
→ 새로운 Resource가 생성되거나 배포가 진행 중

Degraded
→ Resource에 문제가 발생한 상태

Missing
→ 필요한 Resource가 존재하지 않는 상태

Unknown
→ 정상 상태를 판단하기 어려운 상태

 

 

예를 들어 새로운 버전을 배포하면 처음에는 Progressing 상태가 표시될 수 있다.

새로운 Deployment 반영
        │
        ▼
새로운 Pod 생성
        │
        ▼
Progressing
        │
        ▼
Pod 기동 완료
        │
        ▼
Health Check 성공
        │
        ▼
Healthy

 

 

따라서 Argo CD 화면에서는 단순히 배포가 동기화되었는지만 확인하는 것이 아니라 다음 항목을 함께 확인하는 것이 좋다.

Sync 상태가 Synced인지
Health 상태가 Healthy인지
원하는 개수의 Pod가 실행 중인지
새로운 Image Tag가 적용되었는지
Pod 재시작이 반복되고 있지 않은지

 

---

Sync와 Health는 무엇이 다를까?

처음 Argo CD를 사용할 때 Sync 상태와 Health 상태를 혼동하기 쉽다.

두 상태의 의미는 다르다.

Sync
→ Git 설정과 Kubernetes 상태가 같은지 확인

Health
→ Kubernetes Resource가 정상적으로 동작하는지 확인

 

 

예를 들어 Git 설정이 Kubernetes에 정상적으로 적용되었지만 애플리케이션 실행 과정에서 오류가 발생할 수 있다.

Git 설정 반영 완료
→ Synced

새로운 Pod 실행 실패
→ Degraded

 

즉, Synced라고 해서 애플리케이션이 반드시 정상이라는 의미는 아니다.

배포 확인 시에는 Synced와 Healthy를 모두 확인해야 한다.

 

 

---

Argo CD에서 Pod를 확인하는 이유

Argo CD에서는 애플리케이션과 연결된 Kubernetes Resource 구조를 확인할 수 있다.

Application
        │
        ▼
Deployment
        │
        ▼
ReplicaSet
        │
        ▼
Pod

 

배포 후 Pod 상태를 확인하면 새로운 애플리케이션 버전이 정상적으로 실행되었는지 파악할 수 있다.

 

대표적으로 다음 상태를 확인한다.

Running
→ Pod가 정상 실행 중

Pending
→ Pod가 아직 실행될 Node에 배치되지 않았거나 준비 중

CrashLoopBackOff
→ Container가 실행과 종료를 반복하는 상태

ImagePullBackOff
→ Registry에서 Image를 내려받지 못한 상태

Error
→ Container 실행 중 오류가 발생한 상태

Terminating
→ Pod가 종료되고 있는 상태

 

예를 들어 Registry 인증에 문제가 있거나 Image Tag가 존재하지 않는다면 ImagePullBackOff가 발생할 수 있다.

애플리케이션 실행 중 예외가 발생해 계속 종료된다면 CrashLoopBackOff가 발생할 수 있다.

 

 

---

Health Check란?

Kubernetes는 Container 프로세스가 실행 중이라는 사실만으로 애플리케이션이 정상이라고 판단하지 않는다.

프로세스는 실행 중이지만 데이터베이스 연결에 실패했거나, 애플리케이션 초기화가 완료되지 않았을 수도 있기 때문이다.

이를 확인하기 위해 Probe를 사용한다.

 

대표적인 Probe는 다음과 같다.

Startup Probe
→ 애플리케이션의 최초 기동이 완료되었는지 확인

Readiness Probe
→ 현재 요청을 처리할 준비가 되었는지 확인

Liveness Probe
→ 애플리케이션이 정상적으로 살아 있는지 확인

 

 

---

Startup Probe

Startup Probe는 애플리케이션의 최초 기동 여부를 확인한다.

Spring Boot 애플리케이션은 기동 시 설정 파일 로딩, Bean 생성, 데이터베이스 연결 등의 작업을 수행하기 때문에 시작하는 데 시간이 걸릴 수 있다.

기동 시간이 긴 애플리케이션에 Liveness Probe만 적용하면 정상적으로 시작 중인 애플리케이션을 Kubernetes가 비정상으로 판단해 재시작할 수 있다.

Startup Probe를 사용하면 애플리케이션의 초기 기동이 끝날 때까지 다른 Probe의 판단을 기다리게 할 수 있다.

Pod 생성
        │
        ▼
Spring Boot 기동 중
        │
        ▼
Startup Probe 확인
        │
        ▼
기동 완료

 

 

---

Readiness Probe

Readiness Probe는 해당 Pod가 사용자 요청을 받을 준비가 되었는지 확인한다.

Readiness Probe가 실패하면 Pod 자체가 바로 종료되는 것은 아니다.

대신 Service의 요청 전달 대상에서 제외될 수 있다.

Readiness Probe 성공
→ Service가 해당 Pod로 요청 전달

Readiness Probe 실패
→ Service가 해당 Pod로 요청을 전달하지 않음

 

새로운 Pod가 생성되었더라도 애플리케이션 초기화가 완료되기 전에 요청을 받으면 오류가 발생할 수 있다.

Readiness Probe를 사용하면 준비가 완료된 Pod에만 트래픽을 전달할 수 있다.

 

 

---

Liveness Probe

Liveness Probe는 실행 중인 애플리케이션이 정상적으로 동작하고 있는지 확인한다.

Liveness Probe가 일정 횟수 이상 실패하면 Kubernetes가 Container를 재시작할 수 있다.

Liveness Probe 성공
→ Container 유지

Liveness Probe 반복 실패
→ Container 재시작

 

프로세스는 실행 중이지만 내부적으로 응답할 수 없는 상태에 빠진 경우 복구에 활용할 수 있다.

다만 Liveness Probe 조건을 지나치게 엄격하게 설정하면 일시적인 응답 지연만으로도 애플리케이션이 반복 재시작될 수 있으므로 주의해야 한다.

 

 

---

Spring Boot Actuator와 Health Check

Spring Boot에서는 Actuator를 이용해 애플리케이션 상태를 확인할 수 있다.

의존성은 다음과 같이 추가할 수 있다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

 

 

일반적인 Health Check Endpoint는 다음과 같다.

/actuator/health

 

 

애플리케이션이 정상이라면 다음과 같은 응답을 받을 수 있다.

{
  "status": "UP"
}

 

 

Kubernetes Probe에서 해당 Endpoint를 호출하도록 설정할 수 있다.

containers:
  - name: my-spring-app
    image: registry.example.com/my-spring-app:153
    ports:
      - containerPort: 8080

    startupProbe:
      httpGet:
        path: /actuator/health
        port: 8080
      failureThreshold: 30
      periodSeconds: 10

    readinessProbe:
      httpGet:
        path: /actuator/health
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 5

    livenessProbe:
      httpGet:
        path: /actuator/health
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10

 

실제 설정에서는 애플리케이션의 기동 시간과 장애 판단 기준에 맞게 값을 조정해야 한다.

또한 Readiness와 Liveness가 동일한 조건을 사용하면 장애 상황을 정확하게 구분하기 어려울 수 있으므로 운영 환경에 맞는 Health Endpoint 구성이 필요하다.

 

 

---

Jenkins와 Argo CD의 역할 차이

Jenkins와 Argo CD는 모두 배포 과정에서 사용되지만 담당하는 역할이 다르다.

Jenkins
→ 소스 코드를 빌드하고 Docker Image를 생성하는 역할

Argo CD
→ Git의 Kubernetes 설정을 실제 Cluster에 반영하고 상태를 관리하는 역할

 

조금 더 자세히 비교하면 다음과 같다.

 

구분	Jenkins	Argo CD
주요 역할	빌드 및 자동화	Kubernetes 배포 관리
담당 영역	CI 중심	CD 중심
기준 데이터	애플리케이션 소스	Kubernetes 배포 설정
주요 작업	테스트, JAR 빌드, Docker Build, Push	Sync, 배포 상태 및 Health 관리
결과	배포 가능한 Docker Image	Kubernetes에 실행된 애플리케이션

 

두 도구를 연결하면 애플리케이션 빌드부터 Kubernetes 배포까지 자동화할 수 있다.

 

 

---

Jenkins가 직접 Kubernetes에 배포하는 방식

Jenkins가 반드시 CI 작업만 수행해야 하는 것은 아니다.

Jenkins Pipeline에서 kubectl이나 Helm 명령을 실행해 Kubernetes에 직접 배포할 수도 있다.

Git Push
        │
        ▼
Jenkins
        │
        ├─ Build
        ├─ Docker Push
        └─ kubectl apply
        │
        ▼
Kubernetes

 

이 방식에서는 Jenkins가 빌드와 배포를 모두 담당한다.

구성이 단순할 수 있지만 Kubernetes에 어떤 설정이 배포되었는지 Jenkins 작업 내역을 확인해야 할 수 있다.

 

 

---

Jenkins와 Argo CD를 분리하는 방식

Jenkins와 Argo CD를 함께 사용하면 다음처럼 역할을 분리할 수 있다.

Jenkins
→ Docker Image 생성 및 Registry Push

Argo CD
→ Git에 정의된 Kubernetes 설정을 Cluster에 반영

 

 

전체 흐름은 다음과 같다.

애플리케이션 Git Repository
        │
        ▼
Jenkins
        │
        ├─ Test
        ├─ Gradle Build
        ├─ Docker Build
        └─ Registry Push
        │
        ▼
Docker Registry
        │
        ▼
배포 설정 Git Repository
        │
        ▼
Argo CD
        │
        ▼
Kubernetes

 

 

애플리케이션 소스와 Kubernetes 배포 설정을 서로 다른 Repository에서 관리하기도 한다.

Application Repository
→ Java, Spring Boot, Dockerfile, Jenkinsfile

Deployment Repository
→ Deployment, Service, Ingress, Helm, Kustomize 설정

 

이렇게 분리하면 애플리케이션 코드 변경과 배포 설정 변경의 이력을 각각 관리할 수 있다.

 

 

---

Image Tag는 어떻게 배포 설정에 반영될까?

Jenkins가 새로운 이미지를 생성했다고 가정해 보자.

registry.example.com/my-spring-app:154

 

 

하지만 배포 설정에는 이전 버전이 작성되어 있다.

image: registry.example.com/my-spring-app:153

 

 

Argo CD가 새로운 이미지를 배포하려면 Git의 Image Tag가 변경되어야 한다.

image: registry.example.com/my-spring-app:154

 

 

Image Tag 변경 방식은 환경에 따라 다를 수 있다.

개발자가 직접 배포 설정 변경
Jenkins가 배포 Repository 수정
별도의 Image 업데이트 자동화 도구 사용
Helm values 파일의 Image Tag 수정
Kustomize의 Image 설정 수정

 

중요한 점은 Registry에 새 Image가 존재하는 것과 Kubernetes가 해당 Image를 사용하도록 배포 설정을 변경하는 것은 별개의 작업이라는 것이다.

 

 

---

개발·스테이지·운영 환경 배포

실무에서는 하나의 애플리케이션을 여러 환경에 배포한다.

개발 환경
→ 기능 개발 및 통합 테스트

스테이지 환경
→ 운영 배포 전 검증

운영 환경
→ 실제 사용자 서비스

 

 

각 환경은 서로 다른 Namespace나 Kubernetes Cluster를 사용할 수 있다.

dev Namespace
stg Namespace
prod Namespace

 

또는 환경별로 배포 설정을 구분할 수 있다.

deploy
├── dev
│   └── values.yaml
├── stg
│   └── values.yaml
└── prod
    └── values.yaml

 

 

예를 들어 개발 환경에는 다음 Image가 배포될 수 있다.

image:
  tag: build-154

 

스테이지 환경에서는 검증이 완료된 버전을 사용할 수 있다.

image:
  tag: release-1.2.0

 

운영 환경에는 최종 승인된 버전만 반영할 수 있다.

image:
  tag: release-1.2.0

 

환경별 배포 정책은 조직의 브랜치 전략과 승인 절차에 따라 달라진다.

 

 

---

실제 배포 흐름 살펴보기

Jenkins와 Argo CD를 함께 사용하는 배포 흐름을 단계별로 살펴보자.

 

1. 개발자가 소스를 Push한다

Feature Branch
        │
        ▼
Merge Request
        │
        ▼
main 또는 release Branch 반영

 

2. Jenkins Pipeline이 실행된다

소스 Checkout
        │
        ▼
테스트
        │
        ▼
Gradle Build
        │
        ▼
JAR 생성

 

3. Docker Image를 생성한다

docker build \
  -t registry.example.com/my-spring-app:154 \
  .

 

4. Registry에 Image를 Push한다

docker push registry.example.com/my-spring-app:154

 

5. 배포 설정의 Image Tag를 변경한다

image: registry.example.com/my-spring-app:154

 

6. Argo CD가 변경 사항을 확인한다

기존 Git 설정
→ my-spring-app:153

변경된 Git 설정
→ my-spring-app:154

 

Argo CD에는 OutOfSync 상태가 표시될 수 있다.

 

7. Kubernetes에 배포한다

수동 또는 자동 Sync를 통해 새로운 설정을 Kubernetes에 반영한다.

Argo CD Sync
        │
        ▼
Deployment 변경
        │
        ▼
새로운 ReplicaSet 생성
        │
        ▼
새로운 Pod 생성

 

8. Health Check를 수행한다

Startup Probe
        │
        ▼
Readiness Probe
        │
        ▼
트래픽 연결

 

9. 기존 Pod를 종료한다

새로운 Pod가 정상적으로 준비되면 기존 Pod가 순차적으로 종료된다.

기존 Pod
        │
        ├─ 트래픽 제외
        └─ 종료

새로운 Pod
        │
        ├─ Health Check 성공
        └─ 트래픽 처리

 

 

---

Rolling Update란?

Kubernetes Deployment는 일반적으로 새로운 버전을 배포할 때 모든 기존 Pod를 한 번에 종료하지 않는다.

새로운 Pod를 순차적으로 생성하고, 정상 상태가 확인되면 기존 Pod를 종료한다.

이를 Rolling Update라고 한다.

기존 상태

Pod A - version 1
Pod B - version 1

 

 

새로운 버전 배포를 시작하면 다음과 같이 동작할 수 있다.

Pod A - version 1
Pod B - version 1
Pod C - version 2 생성 중

 

 

새로운 Pod가 정상적으로 준비되면 기존 Pod가 하나씩 종료된다.

Pod B - version 1
Pod C - version 2
Pod D - version 2

 

 

최종적으로 새로운 버전의 Pod만 남는다.

Pod C - version 2
Pod D - version 2

 

 

이 방식은 애플리케이션의 서비스 중단 시간을 줄이는 데 도움이 된다.

하지만 새로운 Pod의 Readiness Probe가 통과하지 못하면 배포가 완료되지 않거나 Progressing 상태가 오래 유지될 수 있다.

 

 

---

배포 후 확인해야 할 항목

Jenkins 빌드가 성공했다고 해서 배포까지 정상적으로 완료된 것은 아니다.

배포 후에는 다음 항목을 확인하는 것이 좋다.

Jenkins 확인

Pipeline이 성공했는지
테스트가 통과했는지
JAR 파일이 정상적으로 생성되었는지
Docker Image Build가 성공했는지
Registry Push가 성공했는지
생성된 Image Tag가 무엇인지

 

Argo CD 확인

대상 환경이 맞는지
적용된 Image Tag가 맞는지
Sync 상태가 Synced인지
Health 상태가 Healthy인지
Deployment와 ReplicaSet이 정상인지
새로운 Pod가 정상 생성되었는지

 

Pod 확인

Pod 상태가 Running인지
Ready 상태인지
재시작 횟수가 증가하고 있지 않은지
CrashLoopBackOff가 발생하지 않았는지
ImagePullBackOff가 발생하지 않았는지
애플리케이션 로그에 오류가 없는지

 

결국 배포 완료는 단순히 Jenkins에 초록색 성공 표시가 뜬 시점이 아니라, 새로운 Pod가 정상적으로 실행되어 요청을 처리할 수 있는 상태가 된 시점이라고 볼 수 있다.

 

 

---

배포 실패는 어느 구간에서 발생할까?

CI/CD 과정은 여러 단계로 구성되므로 실패 원인도 구간별로 다르다.

 

Jenkins 빌드 실패

컴파일 오류
테스트 실패
Gradle 의존성 다운로드 실패
JAR 생성 실패
Dockerfile 오류
Registry 인증 실패

 

Argo CD Sync 실패

잘못된 YAML 문법
존재하지 않는 Kubernetes Resource 설정
권한 부족
Cluster 연결 문제
잘못된 Namespace 설정

 

Pod 실행 실패

존재하지 않는 Image Tag
Registry 인증 실패
환경 변수 누락
Secret 또는 ConfigMap 누락
데이터베이스 연결 실패
애플리케이션 실행 오류
Health Check 실패

 

 

어느 단계에서 실패했는지 먼저 구분하면 문제를 더 빠르게 찾을 수 있다.

Image가 생성되지 않음
→ Jenkins 확인

Git 설정이 Cluster에 반영되지 않음
→ Argo CD Sync 확인

설정은 반영됐지만 애플리케이션이 실행되지 않음
→ Pod 상태 및 로그 확인

 

---

배포 실패 예시

새로운 버전을 배포했는데 Argo CD에서 다음과 같은 상태가 표시된다고 가정해 보자.

Sync Status
→ Synced

Health Status
→ Degraded

 

Git 설정은 Kubernetes에 반영되었으므로 Sync 상태는 정상이다.

 

하지만 새로운 Pod가 정상적으로 실행되지 않았기 때문에 Health 상태가 비정상으로 표시된다.

Pod를 확인했더니 다음 상태일 수 있다.

CrashLoopBackOff

 

이 경우 배포 설정 자체보다 애플리케이션 실행 과정에서 문제가 발생했을 가능성이 있다.

다음 항목을 확인한다.

Pod 로그
환경 변수
Secret
ConfigMap
데이터베이스 연결
Spring Profile
외부 API 연결

 

 

반대로 다음과 같은 상태라면 Registry 또는 Image 설정을 확인해야 한다.

ImagePullBackOff

 

대표적인 원인은 다음과 같다.

Image Tag가 Registry에 존재하지 않음
Image 주소가 잘못됨
Registry 접근 권한이 없음
Image Pull Secret이 누락됨

 

 

---

CI/CD를 사용하면 무엇이 좋아질까?

반복 작업 자동화

개발자가 매번 동일한 빌드와 배포 명령을 직접 실행하지 않아도 된다.

 

실행 절차 표준화

누가 배포하더라도 동일한 Pipeline과 배포 설정을 사용한다.

 

배포 이력 관리

Git Commit, Jenkins Build, Docker Image Tag, Kubernetes 배포 버전을 연결해 추적할 수 있다.

 

빠른 피드백

컴파일 오류나 테스트 실패를 소스 반영 과정에서 빠르게 발견할 수 있다.

 

배포 상태 확인

Argo CD를 통해 Kubernetes Resource의 Sync 상태와 Health 상태를 확인할 수 있다.

 

복구 가능성 향상

이전 배포 설정과 Image Tag가 남아 있다면 이전 버전으로 되돌릴 수 있다.

다만 데이터베이스 스키마 변경이나 외부 시스템 호환성 문제가 있다면 단순히 Image만 이전 버전으로 되돌릴 수 없는 경우도 있으므로 함께 고려해야 한다.

 

 

---

전체 흐름 정리

Jenkins와 Argo CD를 사용하는 전체 CI/CD 흐름은 다음과 같다.

개발자
        │
        │ Git Push
        ▼
Application Git Repository
        │
        ▼
Jenkins
        │
        ├─ Source Checkout
        ├─ Test
        ├─ Gradle Build
        ├─ Docker Build
        └─ Docker Push
        │
        ▼
Docker Registry
        │
        ▼
Deployment Git Repository
        │
        │ Image Tag 변경
        ▼
Argo CD
        │
        ├─ 변경 사항 확인
        ├─ Sync
        └─ Health 상태 확인
        │
        ▼
Kubernetes
        │
        ├─ 새로운 ReplicaSet 생성
        ├─ 새로운 Pod 생성
        ├─ Health Check
        ├─ 트래픽 연결
        └─ 기존 Pod 종료
        │
        ▼
서비스 반영

 

Jenkins는 배포 가능한 Docker Image를 만드는 역할을 담당한다.

Argo CD는 Git에 저장된 Kubernetes 배포 설정을 실제 Cluster에 반영하고, Resource의 상태를 확인하는 역할을 담당한다.

Kubernetes는 새로운 Pod를 생성하고 Health Check를 통해 요청을 처리할 준비가 되었는지 확인한다.

 

 

---

정리

CI/CD는 애플리케이션의 빌드, 테스트, 배포 과정을 자동화하는 방법이다.

 

핵심 내용을 정리하면 다음과 같다.

CI
→ 소스를 빌드하고 테스트하여 배포 가능한 결과물을 생성

CD
→ 생성된 결과물을 대상 환경에 배포

Jenkins
→ 테스트, 애플리케이션 빌드, Docker Image 생성, Registry Push

Argo CD
→ Git의 Kubernetes 설정을 Cluster에 반영하고 배포 상태 관리

Docker Registry
→ Jenkins가 생성한 Docker Image 저장

Kubernetes
→ Registry의 Image를 이용해 새로운 Pod 실행

Health Check
→ 새로운 Pod가 정상적으로 요청을 처리할 수 있는지 확인

 

Jenkins의 빌드가 성공했다고 해서 전체 배포가 완료된 것은 아니다.

Argo CD의 Sync 상태와 Health 상태를 확인하고, 최종적으로 새로운 Pod가 정상적으로 실행되는지 확인해야 한다.

 

결국 전체 흐름은 다음과 같이 이해할 수 있다.

Jenkins가 Image를 만들고
Registry가 Image를 저장하고
Argo CD가 배포 설정을 반영하고
Kubernetes가 Pod를 실행한다

 

 

 

---

다음 글

지금까지 Jenkins와 Argo CD를 이용해 Spring Boot 애플리케이션이 빌드되고 Kubernetes에 배포되는 흐름을 알아봤다.

이 과정에서 Kubernetes는 새로운 Docker Image를 이용해 Pod를 생성하고 관리한다.

그렇다면 Kubernetes는 정확히 무엇이며, Pod와 Node는 어떤 역할을 할까?

 

“Docker Container와 Kubernetes Pod는 무엇이 다를까?”

 

 

다음 글에서는 Kubernetes란? Pod와 Node 이해하기를 주제로, Kubernetes가 Container를 어떻게 실행하고 관리하는지 알아보겠다.