ArgoCD 설치하기 — 이 클러스터에, 한 걸음씩

숲 — 지금 설정은 몇 군데에 살고 있나

ArgoCD가 헷갈리는 이유는 명령어가 어려워서가 아닙니다. “설정”이 한 군데가 아니라 네 군데에 산다는 걸 아무도 명시적으로 말해주지 않아서예요. 그 네 개를 먼저 그리고 시작합니다. 이 그림이 이 페이지 전체의 지도입니다.

flowchart LR
  L["💻 내 노트북
git clone"]
  G["☁️ GitHub
origin/main"]
  S["🖥️ 서버 디스크
~/workspace/bit-habit-infra"]
  K["☸️ 클러스터 etcd
실제로 도는 것"]
  L -->|"git push"| G
  G -->|"git pull"| S
  S -.->|"kubectl apply
사람이 칠 때만"| K
  K -.->|"돌아오는 길이 없다"| S
  linkStyle 3 stroke:#e0413a,stroke-width:2px
    

드리프트는 이렇게 생깁니다 (이 클러스터에서 실제로 일어난 일)

sequenceDiagram
  autonumber
  participant F as 저장소의 YAML
  participant K as 클러스터 etcd
  Note over F,K: 116일 전 — 둘이 같음
  F->>K: kubectl apply
  Note over K: 어느 날, 급하게
로컬 레지스트리로 이미지 방식을 바꿈
  K->>K: kubectl edit / set image
  Note over F: 파일은 안 고침
(당장 잘 도니까)
  Note over F,K: 오늘 — 둘이 다름 = 드리프트
  Note over F,K: 여기서 ArgoCD를 켜면?
git이 이기고, 클러스터가 116일 전으로 돌아감
    

실제로 잰 값 — 그리고 그날 안에 8개가 사라졌습니다

추측이 아니라 kubectl diff로 클러스터에 직접 물어본 결과입니다. drift = 저장소를 apply하면 바뀌는 줄 수. 2026-07-26 오전에 잰 값과, 같은 날 오후의 값입니다.

왜 이렇게 됐나 — 매니페스트는 틀린 게 아니라 화석이었습니다

“누가 실수했나”를 찾으려고 서버의 .bash_history를 뒤졌는데, 실수한 사람이 없었습니다. 대신 사라진 워크플로가 그대로 남아 있었어요.

docker build -t sentinel:latest . \
  && docker save sentinel:latest \
  | k3s ctr images import - \
  && kubectl rollout restart deployment/sentinel

레지스트리가 생기기 전에는 이미지를 containerd에 직접 밀어넣었습니다. 그 방식에는 “받아올 곳”이 아예 없습니다 — 그러니 매니페스트가 image: sentinel:latest(레지스트리 호스트 없음) 와 imagePullPolicy: Never라고 적은 건 완벽하게 옳았습니다.

flowchart LR
  subgraph OLD["옛날 — 레지스트리가 없던 시절"]
    O1["docker build
sentinel:latest"] --> O2["docker save"]
    O2 --> O3["k3s ctr images import"] --> O4["containerd
이미지 저장소"]
  end
  subgraph NEW["지금 — 호스트 레지스트리"]
    N1["docker build
localhost:5000/sentinel"] --> N2["docker push"]
    N2 --> N3["registry:2
127.0.0.1:5000"]
    N3 -->|"pull"| N4["containerd
이미지 저장소"]
  end
  OLD ~~~ NEW
    

오늘 아침에 이미 한 일

사실 사본은 네 개가 아니라 다섯 개였습니다. 서버에 푸시 안 된 커밋 3개가 있었고, 그중 하나가 habit.bit-habit.com 장애 수정이었습니다 — git에는 없고 서버에만 있던 수정이죠.

flowchart LR
  subgraph B["오늘 아침 이전 — 진실이 4개"]
    B1["노트북
681ccbe"]:::old
    B2["GitHub
81b52bd"]:::mid
    B3["서버
9b6f0ba"]:::new
    B4["클러스터"]:::k
  end
  subgraph A["push + pull 이후 — 진실이 2개"]
    A1["노트북 · GitHub · 서버
모두 9b6f0ba"]:::new
    A2["클러스터"]:::k
    A1 -.->|"남은 간격
= 드리프트"| A2
  end
  B ==> A
  classDef old fill:#fdeceb,stroke:#e0413a
  classDef mid fill:#fff7e6,stroke:#e36209
  classDef new fill:#eafaf0,stroke:#28a745
  classDef k fill:#eef4ff,stroke:#2d6cdf
    

• 설정이 사는 네 곳(노트북·GitHub·서버·etcd)을 그림으로 그릴 수 있다
• apply가 연결이 아니라 복사라는 걸 설명할 수 있다
• 클러스터 → 파일로 돌아오는 화살표가 없다는 게 드리프트의 원인임을 안다
• 지금 이 클러스터에서 드리프트가 큰 앱이 무엇인지 말할 수 있다

앞으로 할 일 — 설치 전에 끝내야 하는 것

ArgoCD 설치는 30분입니다. 드리프트 정리가 GitOps의 90%예요. 순서를 지키는 게 전부이고, 각 단계 사이에 게이트가 있습니다 — 게이트를 통과 못 하면 다음으로 안 갑니다.

flowchart TD
  S0["0단계 ✅ 완료
진실 합치기
서버 커밋 push → 노트북 pull"]:::done
  S1["1단계 · 관측
kubectl diff를 손에 익힌다
클러스터는 안 건드림 · 위험 0"]:::safe
  S2["2단계 · 흡수
git을 클러스터에 맞춘다
방향이 중요: 클러스터 → git"]:::work
  G{"게이트
모든 앱 drift = 0?"}:::gate
  S3["3단계 · 설치
아래 0번 섹션부터
수동 sync → apps → base"]:::goal
  S0 --> S1 --> S2 --> G
  G -->|"아니오 — 남은 앱 계속"| S2
  G -->|"예"| S3
  classDef done fill:#eafaf0,stroke:#28a745
  classDef safe fill:#eef4ff,stroke:#2d6cdf
  classDef work fill:#fff7e6,stroke:#e36209
  classDef gate fill:#f6f2fd,stroke:#6f42c1
  classDef goal fill:#fdeceb,stroke:#e0413a
    

1단계 — 안전벨트부터: kubectl diff

diff는 서버사이드 dry-run입니다. 진짜 API 서버에 “이거 적용하면 뭐가 바뀌냐”만 물어보고 아무것도 쓰지 않습니다. 프로덕션에서 공짜로 쓸 수 있는 유일한 안전벨트이고, 이 페이지의 위험 경고들도 전부 이 명령 하나로 알아낸 겁니다. 먼저 앱 하나로 감을 잡으세요.

cd ~/workspace/bit-habit-infra
sudo k3s kubectl diff -R -f apps/startpage/

예상: -로 시작하는 줄이 지금 살아있는 값, +가 apply하면 될 값입니다. - image: localhost:5000/startpage:latest / + image: docker.io/library/startpage:latest가 보이면 제대로 읽은 겁니다.

감이 왔으면 전체를 한 장으로 봅니다. 아래를 그대로 붙여넣으면 위의 표를 직접 재현합니다 — 숫자가 저와 다르면, 그 사이에 클러스터가 또 바뀐 겁니다.

cd ~/workspace/bit-habit-infra
for d in apps/*/; do
  n=$(basename "$d")
  [ "$n" = "argocd" ] && continue
  cnt=$(sudo k3s kubectl diff -R -f "$d" 2>&1 | grep -cE '^[+-] ')
  printf '%-18s %s\n' "$n" "$cnt"
done

예상: 7개는 0, 나머지는 6~18, oauth2-proxy는 110. 이 명령이 2단계의 진도표이자 완료 판정기입니다 — 전부 0이 되면 끝입니다.

• kubectl diff가 아무것도 쓰지 않는다는 걸 안다
• -가 현재, +가 될 값이라는 걸 읽을 수 있다
• 종료 코드 1은 에러가 아니다를 안다
• 앱별 드리프트 표를 내 손으로 뽑아봤다

2단계 — 흡수: git을 클러스터에 맞춘다

앱 하나당 3분입니다. startpage로 예를 들면 — 먼저 살아있는 진짜 값을 물어봅니다.

sudo k3s kubectl get deploy startpage \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}{.spec.template.spec.containers[0].imagePullPolicy}{"\n"}'

예상: localhost:5000/startpage:latest 와 IfNotPresent. 이 두 값을 apps/startpage/deployment.yaml에 그대로 받아적습니다.

cd ~/workspace/bit-habit-infra
# apps/startpage/deployment.yaml 을 편집: image / imagePullPolicy 를 위 값으로
git add apps/startpage/deployment.yaml
git commit -m "fix(startpage): record the live image ref (local registry)"
git push

cd ~/workspace/bit-habit-infra && git pull
sudo k3s kubectl diff -R -f apps/startpage/ ; echo "exit=$?"

예상: 출력이 비어 있고 exit=0. 이 순간 startpage는 GitOps 준비가 끝난 앱입니다. 나머지도 똑같이 반복하세요.

git show c544eb6 --stat
git show c544eb6 -- apps/startpage/deployment.yaml

게이트 — 여기를 통과해야 3단계

• 1단계의 for 루프가 전부 0을 출력한다
• base/도 drift 0이다 (www.blog·www.wiki 포함)
• oauth2-proxy를 쓸지 말지 결정했다
• 아래 멈춤 신호를 읽고, 숫자를 내 상황에 맞게 고쳤다

멈춤 신호 — 무엇을 보면 즉시 되돌리나

이 클러스터는 폭발 반경이 세 층으로 나뉩니다. 오늘 실제로 확인한 구조예요 — 층마다 신호도 다르고 대응도 다릅니다.

신호를 실제로 읽는 명령 (검증됨)

sudo k3s kubectl get deploy -A --no-headers |
  awk '{split($3,a,"/"); if (a[1]!=a[2]) print $1"/"$2, $3}'

예상: 아무것도 안 나오면 정상. 한 줄 = 1층, 두 줄 이상 = 2층, 브레이크.

for h in bit-habit.com habit.bit-habit.com blog.bit-habit.com wiki.bit-habit.com status.bit-habit.com; do
  printf '%-26s %s\n' "$h" "$(curl -s -o /dev/null -m 8 -w '%{http_code}' https://$h)"
done

예상: 전부 200. 하나라도 000(연결 실패)이나 5xx면 3층입니다. 000은 TLS 실패도 포함하니 인증서 사고까지 같이 잡힙니다.

비상 브레이크 — 되돌리기 전에 치는 명령

# 자동 동기화(selfHeal 포함)만 떼어낸다. 앱은 그대로 돌아감.
sudo k3s kubectl -n argocd patch application bit-habit-apps \
  --type merge -p '{"spec":{"syncPolicy":null}}'

sudo k3s kubectl rollout undo deploy/<앱이름>      # 1층: 그 앱만
sudo k3s kubectl rollout status deploy/<앱이름>    # 돌아왔는지 확인

• 폭발 반경 세 층과 층별 대응이 다르다는 걸 안다
• 브레이크 먼저, 복구는 그 다음 순서를 안다
• Pod의 Running이 아니라 Deployment의 Ready를 봐야 하는 이유를 안다
• 설치 직후 브레이크를 연습으로 한 번 밟아봤다

3단계 — 그때 아래로 내려가세요

게이트를 통과했다면 git이 진짜로 정답이 된 상태입니다. 그때부터 ArgoCD는 되돌리는 기계가 아니라 지켜주는 기계가 됩니다. 아래 0번부터 시작하세요.

0. 왜 GitOps인가? (설치하기 전에)

지금 이 클러스터에 뭔가를 바꾸는 방법은 하나입니다. 서버에 들어가 kubectl apply -f ...를 치는 것. 이걸 push 모델이라고 합니다 — 변경이 바깥에서 안으로 밀려 들어갑니다.

문제는 클러스터가 git을 절대 보지 않는다는 겁니다. 저장소의 YAML은 “우리가 원한다고 믿는 상태”일 뿐, 실제로 도는 것과 같다는 보장이 없습니다. 누가 급해서 kubectl edit으로 replica를 2로 올려두면, git에는 1이라 적혀 있는데 현실은 2입니다. 이 어긋남이 드리프트(drift)입니다. 드리프트는 조용합니다 — 아무도 모르고, 다음 배포 때 갑자기 되돌아갑니다.

flowchart LR
  subgraph NOW["지금 — push"]
    Y["사람 / CI"] ==>|"kubectl apply"| K1["클러스터
(git을 안 봄)"]
  end
  subgraph GO["ArgoCD — pull"]
    A["ArgoCD
(클러스터 안에 산다)"] -->|"저장소를 계속 읽음"| G["git"]
    A ==>|"클러스터를 git과 같게 만듦"| K2["클러스터"]
  end
    

• push 모델에서 드리프트가 조용히 생긴다는 걸 설명할 수 있다
• GitOps가 바꾸는 건 방향(push→pull) 하나임을 안다
• GitOps에서 “배포 = 커밋”이 되는 이유를 안다

0.5 kubectl 하던 사람을 위한 ArgoCD 용어 (걸리는 것만)

당신은 이미 Pod·Deployment·Service·Ingress·네임스페이스를 압니다. 그래서 ArgoCD에서 “어? 이건 뭐지” 싶은 것만 골라, 이미 아는 것과 나란히 놓습니다. 이 다섯 개를 넘으면 나머지는 그냥 설치입니다.

• Application이 “git 위치 ↔ 클러스터 위치” 매핑임을 안다
• Sync와 Health가 독립된 사실임을 안다
• syncPolicy가 없으면 수동임을 안다
• selfHeal(되돌리기)과 prune(지우기)의 차이를 안다
• TLS secret이 네임스페이스를 못 넘는다는 걸 안다

1. 사전 점검 — 명령 형태부터 고정

아무것도 설치하기 전에, 앞으로 계속 쓸 명령 형태가 이 노드에서 통하는지 확인합니다. 여기서 통하면 이후 모든 단계가 통합니다.

sudo k3s kubectl get nodes

성공: 노드 한 개가 STATUS = Ready로 보입니다.

• 노드가 Ready로 보인다
• 앞으로 모든 명령에 sudo k3s kubectl을 쓴다는 걸 안다

2. ArgoCD 설치

네임스페이스를 만들고 공식 매니페스트 하나로 설치합니다.

sudo k3s kubectl create namespace argocd

sudo k3s kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

... created 줄이 수십 개 지나갑니다. CRD·서비스어카운트·롤·디플로이먼트 — 쿠버네티스에게 Application이라는 새 타입을 가르치고, 자기 파드들을 올리는 중입니다.

sudo k3s kubectl get pods -n argocd

성공: 파드 7개 안팎이 전부 Running / READY 1/1. 다 안정될 때까지 명령을 다시 쳐보세요.

• argocd 네임스페이스를 만들었다
• 공식 매니페스트를 apply했다
• 파드가 전부 Running이 됐다
• CRD가 “새 오브젝트 타입 등록”임을 안다

3. Traefik 뒤에서 돌게 만들기 (--insecure)

argocd-server에게 “평문 HTTP로 서빙해라”라고 시킵니다. 이상하게 들리지만, 여기선 그게 맞습니다.

sudo k3s kubectl -n argocd patch deployment argocd-server --type json \
  -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--insecure"}]'

sudo k3s kubectl -n argocd rollout status deployment argocd-server

성공: deployment "argocd-server" successfully rolled out

• --insecure 패치를 적용했다
• rollout이 성공했다
• TLS 종료를 한 곳(Traefik)에서만 하는 이유를 안다

4. UI를 argocd.bit-habit.com에 노출

와일드카드 TLS secret을 argocd 네임스페이스로 복사한 뒤, 저장소에 이미 있는 ingress를 적용합니다.

sudo k3s kubectl get secret tls-secret -n default -o jsonpath='{.data.tls\.crt}' | base64 -d | sudo tee /tmp/tls.crt >/dev/null
sudo k3s kubectl get secret tls-secret -n default -o jsonpath='{.data.tls\.key}' | base64 -d | sudo tee /tmp/tls.key >/dev/null
sudo k3s kubectl create secret tls tls-secret -n argocd --cert=/tmp/tls.crt --key=/tmp/tls.key
sudo rm -f /tmp/tls.crt /tmp/tls.key

성공: secret/tls-secret created. (YAML을 통째로 복사하는 것보다 원본 인증서+키에서 새로 만드는 편이 깨끗합니다 — 지워야 할 낡은 메타데이터가 안 따라옵니다.)

sudo k3s kubectl apply -f /home/ubuntu/workspace/bit-habit-infra/apps/argocd/ingress.yaml
sudo k3s kubectl get ingress -n argocd

성공: argocd-ingress가 호스트 argocd.bit-habit.com으로 보입니다. 와일드카드 DNS가 이미 이 서버를 가리키므로 이름은 바로 풀립니다.

• TLS secret을 argocd 네임스페이스로 복사했다
• ingress를 적용하고 get ingress로 확인했다
• secret이 네임스페이스를 못 넘는 이유를 안다
• ingress가 80 포트를 보는 이유를 안다

5. 로그인하고 보드 읽기

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

임의의 문자열이 출력됩니다. 아이디는 admin. 브라우저에서 https://argocd.bit-habit.com으로 접속해 로그인하세요.

sudo k3s kubectl -n argocd delete secret argocd-initial-admin-secret

sudo curl -sSL -o /usr/local/bin/argocd \
  https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-arm64
sudo chmod +x /usr/local/bin/argocd
argocd login argocd.bit-habit.com --username admin

• https://argocd.bit-habit.com에 로그인했다
• 빈 Applications 보드를 봤다
• 비밀번호를 바꾸고 초기 secret을 지웠다

6. 첫 Application — 작은 앱 하나, 수동 동기화

이제 핵심 루프를 눈으로 봅니다. 자동은 아직입니다.

sudo k3s kubectl apply -n argocd -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: startpage
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/bookseal/bit-habit-infra.git
    targetRevision: main
    path: apps/startpage
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  # syncPolicy 블록 없음 = 수동. 관찰만 하고 스스로 손대지 않는다.
EOF

성공: application.argoproj.io/startpage created. UI를 새로고침하면 타일이 하나 생깁니다.

sudo k3s kubectl get application -n argocd

startpage의 SYNC STATUS와 HEALTH STATUS가 보입니다 — 타일과 같은 두 사실입니다.

sudo k3s kubectl scale deployment startpage -n default --replicas=2

• startpage Application을 만들었다
• 타일의 Sync / Health 두 값을 읽었다
• kubectl get application으로도 확인했다
• (선택) 드리프트를 만들고 ArgoCD가 잡는 걸 봤다
• ArgoCD가 git을 고치지 않는다는 걸 안다

7. 저장소 전체로 확대 (그리고 base/는 맨 마지막)

루프가 이해됐으면 apps/ 전체를 맡깁니다. 여기서 처음으로 자동을 켭니다.

sudo k3s kubectl apply -n argocd -f - <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: bit-habit-apps
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/bookseal/bit-habit-infra.git
    targetRevision: main
    path: apps
    directory:
      recurse: true
      exclude: "argocd/*"   # ArgoCD가 자기 자신의 Application 파일과 싸우지 않게
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: false
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
EOF

보드가 타일로 채워집니다. 일부는 OutOfSync일 수 있습니다 — 살아 있는 클러스터가 git에서 흘러간 지점입니다. 자동 치유를 믿기 전에 각 diff를 먼저 보세요. (앞의 startpage Application은 중복이니 지워도 됩니다: sudo k3s kubectl delete application startpage -n argocd)

sudo k3s kubectl apply -f /home/ubuntu/workspace/bit-habit-infra/apps/argocd/application.yaml

• bit-habit-apps Application을 만들었다
• OutOfSync 타일의 diff를 먼저 읽어봤다
• exclude: "argocd/*"가 왜 있는지 안다
• base/를 마지막에 두는 이유를 안다
• secret이 아직 GitOps 밖에 있다는 걸 안다

8. 되돌리기 — 안전한 제거

sudo k3s kubectl delete application --all -n argocd

sudo k3s kubectl delete -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
sudo k3s kubectl delete namespace argocd

클러스터는 push 모델로 돌아갑니다 — 앱은 전부 그대로 돕니다. ArgoCD는 워크로드를 소유한 적이 없고, 지켜봤을 뿐이니까요.

• finalizer가 연쇄 삭제를 일으킬 수 있다는 걸 안다
• 제거 순서(Application → ArgoCD)를 안다
• ArgoCD가 앱을 소유하지 않는다는 걸 안다

9. 마무리 · 이해도 체크

명령이 아니라 머릿속에 남았는지를 확인하세요. 다 채우면 이 페이지가 100%가 됩니다. 🎉

• 설정이 여러 사본으로 존재한다는 걸 그림으로 설명할 수 있다
• 설치 전에 드리프트를 0으로 만들어야 하는 이유를 안다
• kubectl diff를 습관처럼 먼저 친다
• push와 pull의 차이를 한 문장으로 설명할 수 있다
• 드리프트가 무엇이고 왜 조용한지 설명할 수 있다
• Application이 매핑이라는 걸 설명할 수 있다
• Sync와 Health가 독립임을 예로 들 수 있다
• selfHeal과 prune을 구분할 수 있다
• prune: false를 고른 이유를 설명할 수 있다
• --insecure가 왜 안전한지 설명할 수 있다
• TLS secret을 왜 복사해야 하는지 안다
• 수동 → apps → base 순서의 이유를 안다
• secret이 아직 GitOps 밖이라는 걸, 그리고 그 다음 과제를 안다