Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
매니페스트와 Application의 차이, 커밋 후 파드가 뜨기까지, replicas를 바꿨을 때 일어나는 일을 화면으로 확인한 기록
로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
- 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
- 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
- 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
- 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
- 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
- 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
- 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
- 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
- 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
- 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
- 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
- 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
- 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
- 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
- 13편Airflow를 쿠버네티스에 올리기: KubernetesExecutor, git-sync DAG 배포, 재시도·catchup부터 스케줄러 장애와 3.4 업그레이드까지 kind 실습
Argo CD로 무언가를 배포하려면 파일이 두 개 필요합니다. 하나는 “무엇을 띄울지”를 적은 쿠버네티스 매니페스트(Deployment, Service)이고, 다른 하나는 Argo CD에게 “Git의 어느 폴더를 어느 네임스페이스에 배포하고 어떻게 관리할지”를 알려 주는 Application입니다. kind 클러스터에서 GitHub 웹 화면으로 이 두 파일을 커밋하자, Argo CD가 Application을 만들고 3초 만에 동기화를 마쳤으며 그로부터 6초 뒤 nginx 파드가 실행됐습니다. 이어서 Git에서 replicas를 1에서 2로 바꾸자, 같은 ReplicaSet이 파드를 하나 더 띄워 7초 만에 두 개 모두 준비됐습니다. ReplicaSet과 파드는 Git에 적지 않아도 Deployment가 만들기 때문에, 바꿀 곳은 항상 Git의 Deployment입니다.
로컬 쿠버네티스 실습 9편에서 만든 환경(kind 클러스터, Argo CD 3.6.1, GitHub 비공개 저장소, App of Apps 루트 Application)을 그대로 씁니다. 루트 Application이 저장소의 apps/ 폴더를 보고 있어서, 그 폴더에 Application 파일을 추가하기만 하면 Argo CD에 등록됩니다. 루트 없이 Argo CD만 설치한 환경이라면 Application 파일을 kubectl apply로 한 번 넣으면 같은 결과가 됩니다. 이미지는 nginx:1.27-alpine을 썼습니다.
이 글에서 하는 것
9편에서 클러스터 전체를 Argo CD로 옮겼지만, 구성 요소가 20개라 “파일 하나를 커밋하면 무슨 일이 일어나는지” 하나씩 보기는 어려웠습니다. 이 글에서는 가장 단순한 예로 nginx 파드 하나를 배포하면서 그 흐름을 처음부터 끝까지 따라갑니다.
작업 순서
| 순서 | 할 일 | 도구 |
|---|---|---|
| 1 | 배포할 매니페스트(Deployment, Service) 커밋 | GitHub 웹 |
| 2 | Argo CD Application 파일 커밋 | GitHub 웹 |
| 3 | Argo CD가 앱을 만들고 파드를 띄우는지 확인 | Argo CD, Headlamp |
| 4 | replicas를 1에서 2로 바꿔 커밋하고 변화 확인 | GitHub 웹, Argo CD |
명령어 없이 GitHub 웹 화면에서 파일을 만들고 커밋했습니다. Argo CD는 내 PC의 폴더가 아니라 GitHub 저장소를 읽기 때문에, 어디서 커밋하든 결과는 같습니다.
파일 두 개의 역할: 무엇을 띄울지와 어떻게 배포할지
처음 Argo CD를 쓸 때 가장 헷갈리는 부분은 “왜 파일이 두 개나 필요한가”입니다. 택배에 비유하면 하나는 상자 안의 물건이고, 다른 하나는 배송장입니다.
매니페스트와 Application 비교
| 구분 | platform/hello/deployment.yaml | apps/06-hello.yaml |
|---|---|---|
| 종류 | 쿠버네티스 리소스(Deployment, Service) | Argo CD 리소스(Application) |
| 읽는 쪽 | 쿠버네티스 | Argo CD |
| 내용 | nginx 파드 1개와 Service를 띄워라 | Git의 platform/hello 폴더를 hello 네임스페이스에 배포하고 계속 맞춰라 |
| 비유 | 택배 상자 안의 물건 | 배송장(어디서 가져와 어디로, 어떤 방식으로) |
| 이것만 있으면 | 아무 일도 안 일어남(Argo CD는 저장소 전체를 뒤지지 않음) | 앱은 생기지만 배포할 내용이 없음 |
먼저 매니페스트입니다. GitHub 저장소에서 Add file → Create new file을 누르고 파일 이름 칸에 platform/hello/deployment.yaml을 입력하면, /를 입력하는 순간 폴더가 함께 만들어집니다. GitHub에는 빈 폴더를 따로 만드는 기능이 없어서, 파일 이름에 경로를 같이 쓰는 것이 폴더를 만드는 방법입니다.
# 파드 1개짜리 nginx. 파드를 직접 만들기보다 Deployment로 두어야 죽어도 다시 뜬다apiVersion: apps/v1kind: Deploymentmetadata: name: hello namespace: hellospec: replicas: 1 selector: matchLabels: { app: hello } template: metadata: labels: { app: hello } spec: containers: - name: nginx image: nginx:1.27-alpine ports: - containerPort: 80 resources: requests: { cpu: 10m, memory: 16Mi } limits: { memory: 64Mi }---apiVersion: v1kind: Servicemetadata: name: hello namespace: hellospec: selector: { app: hello } ports: - port: 80 targetPort: 80
파드를 kind: Pod로 직접 만들지 않고 Deployment로 감쌌습니다. 파드만 만들면 노드가 재시작되거나 파드가 지워졌을 때 다시 뜨지 않지만, Deployment는 “항상 파드 N개”를 유지합니다. 이미지 태그는 latest 대신 버전을 적어야 Git만 보고도 무엇이 배포됐는지 알 수 있습니다.
Application 파일: Argo CD에게 주는 작업 지시서
두 번째 파일은 같은 방법으로 apps/06-hello.yaml에 만들었습니다. 매니페스트를 먼저 커밋하는 것이 좋습니다. Application을 먼저 올리면 hello 앱이 잠깐 빈 폴더를 가리키게 됩니다.
# 연습용 앱: platform/hello 폴더를 hello 네임스페이스에 배포apiVersion: argoproj.io/v1alpha1kind: Applicationmetadata: name: hello namespace: argocd # Application은 Argo CD 네임스페이스에 둔다spec: project: default source: repoURL: <비공개 저장소의 SSH 주소> targetRevision: main path: platform/hello destination: server: https://kubernetes.default.svc namespace: hello syncPolicy: automated: prune: true selfHeal: true syncOptions: - CreateNamespace=true
- source: 어느 저장소의 어느 브랜치(main), 어느 폴더(platform/hello)를 볼지 정합니다.
- destination: 어느 클러스터(Argo CD가 설치된 클러스터 자신), 어느 네임스페이스(hello)에 배포할지 정합니다.
- automated: Git이 바뀌면 사람이 버튼을 누르지 않아도 적용합니다.
- selfHeal: 누가 kubectl로 직접 바꾸면 Git 상태로 되돌립니다.
- prune: Git에서 지운 리소스를 클러스터에서도 지웁니다. 연습용 앱이라 켰고, DB처럼 중요한 데이터가 있는 앱에서는 신중하게 켭니다.
- CreateNamespace=true: hello 네임스페이스가 없으면 만듭니다.
나눠 두는 이유도 있습니다. 파드 수를 바꿀 때는 매니페스트만, 자동 동기화를 끄거나 대상 네임스페이스를 바꿀 때는 Application만 고치면 됩니다. 또 같은 매니페스트 폴더를 두고 Application을 두 개 만들면 dev와 prod 네임스페이스에 각각 배포할 수도 있습니다. Helm 차트를 배포할 때는 매니페스트 자리에 차트와 values.yaml이 들어갈 뿐 구조는 같습니다.
커밋하면 일어나는 일: root → hello → 파드
Application 파일을 커밋했을 뿐인데 어떻게 Argo CD에 등록될까요? 9편에서 만든 루트 Application(root)이 apps/ 폴더를 계속 보고 있기 때문입니다. 이것을 App of Apps 패턴이라고 합니다.
%% 제목: root Application이 apps 폴더에서 hello Application을 만들고, hello가 platform/hello 폴더로 Deployment·Service를, Deployment가 ReplicaSet과 파드를 만드는 순서 flowchart TB root["root Application<br/>(9편에서 한 번만 손으로 적용)"] -- "apps/ 폴더를 봄<br/>06-hello.yaml 발견" --> hello["hello Application"] hello -- "platform/hello 폴더를 봄" --> deploy["Deployment"] hello --> svc["Service"] deploy --> rs["ReplicaSet"] --> pod["파드"]
Argo CD 화면에서 hello Application 자체를 열어 보면, 이것도 결국 쿠버네티스 리소스이고 root가 만들었다는 표시(tracking-id: root:argoproj.io/Application:argocd/hello)가 붙어 있습니다.

커밋 후 시간 순서
| 시각 | 일 |
|---|---|
| 22:55:40 | root가 hello Application 생성 |
| 22:55:43 | hello 동기화 완료(Sync OK) — Deployment, Service 적용 |
| 22:55:49 | nginx 파드 시작 |
Argo CD가 GitHub의 변경을 알아채는 데는 기본 설정으로 최대 3분쯤 걸립니다(2분 주기 + 최대 1분 지연). 로컬 클러스터는 GitHub 웹훅을 받을 수 없기 때문입니다. 바로 반영하고 싶으면 Argo CD 화면에서 root 앱의 REFRESH를 누릅니다.

hello 앱의 트리를 보면 Service와 Deployment, 그 아래 ReplicaSet과 파드가 이어져 있습니다. 자세히 보면 Service와 Deployment에는 하트(상태)와 체크(동기화) 표시가 둘 다 있지만, ReplicaSet과 파드에는 하트만 있습니다. Git에 적은 것은 Service와 Deployment뿐이고, ReplicaSet과 파드는 Deployment가 만든 것이라 Argo CD의 동기화 대상이 아니라는 뜻입니다.
파드 확인
Headlamp에서 hello 네임스페이스를 보면 파드 하나가 Running입니다.


터미널에서는 다음 명령으로 확인합니다. 파드 상세 화면의 포트 포워딩 버튼을 누르면 브라우저에서 nginx 기본 페이지도 열어 볼 수 있습니다.
kubectl -n hello get deploy,rs,pod,svcreplicas를 2로 바꾸면
GitHub에서 deployment.yaml을 열고 연필(Edit) 버튼으로 replicas: 1을 replicas: 2로 바꿔 커밋했습니다. 여기서 바꾼 것은 ReplicaSet이 아니라 Deployment의 replicas 값입니다. Git에는 ReplicaSet이 없습니다.

replicas 변경 타임라인(2초 간격 기록)
| 시각 | 일 | 경과 |
|---|---|---|
| 23:02:26 | GitHub에서 replicas 1 → 2 커밋 | - |
| 23:02:56 | Argo CD 동기화(배포 1초) | +30초 |
| 23:02:58 | 새 파드 생성 중(ContainerCreating), 잠깐 OutOfSync·Progressing | +32초 |
| 23:03:03 | 파드 2개 모두 Ready, Synced·Healthy | +37초 |
이번에는 3분을 기다리지 않고 화면에서 동기화를 눌러 30초 만에 반영됐습니다. 배포 이력의 “Initiated by”가 automated sync policy가 아니라 로그인한 사용자(실습용 계정 alice)로 남은 것이 그 흔적입니다.


트리에서 ReplicaSet 이름(hello-67564d987d, rev:1)은 그대로이고, 그 아래 파드만 두 개로 늘었습니다. 새 파드가 아직 만들어지는 중인 순간이라 파란 원(Progressing)으로 보입니다. 무엇을 바꾸느냐에 따라 ReplicaSet의 움직임이 다릅니다.
Deployment에서 바꾸는 값에 따른 차이
| Git에서 바꾸는 것 | 일어나는 일 | 트리에서 보이는 것 |
|---|---|---|
| replicas(파드 수) | 같은 ReplicaSet이 파드 수만 조정 | rs 1개(rev:1), 파드 2개 |
| image 태그 등 파드 내용 | 새 ReplicaSet이 생기고, 새 파드가 뜬 뒤 옛 파드가 내려감(롤링 업데이트) | rs가 rev:2로 하나 더 생김 |
해 보면서 알게 된 주의할 점
- kubectl로 바꾸면 되돌아갑니다:
kubectl -n hello scale deploy hello --replicas=5처럼 직접 바꾸면 selfHeal이 Git 값(2)으로 되돌립니다. ReplicaSet을 직접 고치면 이번에는 Deployment가 되돌립니다. 바꿀 곳은 항상 Git의 Deployment입니다. - 파드를 지우는 것은 다릅니다:
kubectl delete pod로 파드를 지우면 Argo CD가 아니라 Deployment(ReplicaSet)가 바로 새 파드를 띄웁니다. 설정은 그대로이고 파드만 바뀌기 때문입니다. - GitHub 웹에서 커밋하면 내 PC의 저장소는 뒤처집니다: 이 상태로 PC에서 수정해 push하면 rejected(fetch first) 오류가 납니다. PC에서 작업하기 전에
git pull로 먼저 받아 옵니다. - 반영은 바로 되지 않습니다: 웹훅이 없으면 최대 3분쯤 걸립니다. 급하면 REFRESH나 SYNC를 누르되, 원칙은 Git이 기준이라는 점을 잊지 않습니다.
- 지울 때는 순서가 있습니다: 9편 환경의 root는 prune이 꺼져 있어서, apps/06-hello.yaml을 지우고 커밋해도 hello 앱이 자동으로 지워지지 않습니다. 파일 두 개를 지워 커밋한 뒤 Argo CD 화면에서 hello 앱을 DELETE합니다. 순서를 거꾸로 하면 root가 Git에 남은 파일을 보고 hello 앱을 다시 만듭니다.
자주 묻는 질문
Application을 Argo CD 화면의 NEW APP 버튼으로 만들면 안 되나요?
화면으로 만들어도 배포는 됩니다. 다만 그 Application 설정은 Git에 남지 않아서, 누가 언제 무엇을 바꿨는지 기록이 없고 클러스터를 다시 만들면 사라집니다. 처음 감을 잡을 때는 화면이 편하지만, 계속 쓸 앱은 이 글처럼 Application도 Git 파일로 두는 것이 GitOps의 원칙입니다.
root(App of Apps) 없이도 할 수 있나요?
됩니다. Application 파일을 한 번 `kubectl apply -f apps/06-hello.yaml`로 넣으면, 그다음부터는 hello가 platform/hello 폴더를 보고 똑같이 동작합니다. 다만 Application 파일 자체를 고쳤을 때는 다시 apply해야 하므로, 앱이 늘어나면 root를 두는 편이 관리가 쉽습니다.
파드 수를 Argo CD 화면에서 바로 바꿀 수는 없나요?
화면에서 리소스를 편집할 수는 있지만, selfHeal이 켜져 있으면 곧 Git 값으로 되돌아갑니다. 실제로 유지하고 싶은 값은 Git에 커밋해야 합니다.
작성 방식
이 글의 화면과 시각은 로컬 쿠버네티스 실습 환경에서 직접 실행한 결과이며, 설정은 Argo CD와 Kubernetes 공식 문서를 기준으로 했습니다. 화면의 GitHub 계정 이름, 이메일, IP는 가렸습니다. 실행 기록 정리와 글 작성에 AI 도구를 함께 사용했습니다.