Applicationマニフェストを組み立てる
한국어 원문으로 표시합니다.
목표
Argo CD Application 매니페스트를 필드 하나씩 쌓아 완성하고, 그 앱이 배포하게 될 네임스페이스와 디플로이먼트를 실제 클러스터에 올려 Argo CD 가 자기 리소스를 알아보는 방식까지 손으로 확인합니다.
왜 중요한가
Application 은 "무엇을(source) 어디에(destination) 어떤 규칙으로(syncPolicy) 맞출 것인가" 를 적은 선언문입니다. 필드 이름을 외우는 것보다 각 필드가 어떤 사고를 막으려고 생겼는지 아는 것이 중요합니다. prune 을 켜지 않으면 Git 에서 지운 리소스가 클러스터에 영원히 남고, selfHeal 을 켜면 손으로 고친 값이 되돌아가며, ignoreDifferences 없이 HPA 를 쓰면 Argo CD 와 HPA 가 replicas 를 두고 끝없이 싸웁니다. 이 실습에서 만드는 파일은 그 사고들을 하나씩 예방하는 순서로 쌓입니다.
단계
/root/capa-app/디렉터리를 만들고 그 안에application.yaml을 만드세요. apiVersion 은argoproj.io/v1alpha1, kind 는Application,metadata.name은guestbook,metadata.namespace는argocd입니다.- 같은 파일에
spec.project를capa-demo로,spec.source.repoURL을https://gitea.homelab.internal/platform/guestbook.git,spec.source.targetRevision을main,spec.source.path를overlays/prod로 채우세요. spec.destination.server를https://kubernetes.default.svc,spec.destination.namespace를capa-guestbook으로 지정하세요.destination.name은 쓰지 마세요.spec.syncPolicy.automated.prune과spec.syncPolicy.automated.selfHeal을 둘 다true로 두고,spec.syncPolicy.syncOptions에CreateNamespace=true와PruneLast=true두 항목을 넣으세요.spec.syncPolicy.retry.limit을5,spec.syncPolicy.retry.backoff.duration을5s,factor를2,maxDuration을3m으로 지정하세요.spec.ignoreDifferences의 첫 항목에group: apps,kind: Deployment,jsonPointers에/spec/replicas를 넣어 HPA 가 관리하는 필드를 비교에서 빼세요.- 클러스터에 네임스페이스
capa-guestbook을 실제로 만들고 라벨app.kubernetes.io/part-of=capa를 붙이세요. - 네임스페이스
capa-guestbook에 디플로이먼트guestbook-ui를 실제로 만드세요.replicas는2, 컨테이너 이미지는nginx:1.27, 그리고 디플로이먼트 자신의 어노테이션으로argocd.argoproj.io/tracking-id를 Argo CD 형식에 맞게 붙이세요. 앱 이름은guestbook입니다.
참고
- 파일 검증은
yq '.spec.syncPolicy' /root/capa-app/application.yaml처럼 부분만 뽑아 보면 빠릅니다. - 실제 리소스는
kubectl create ... --dry-run=client -o yaml로 뼈대를 뽑은 뒤 편집하는 편이 오타가 적습니다. - 흔한 실수 1:
syncOptions를 맵으로 쓰는 것. 문자열 배열입니다. - 흔한 실수 2: 추적 ID 의 코어 그룹 표기. apps 그룹 리소스와 코어 그룹 리소스의 형태가 다릅니다.
작업 디렉터리와 Application 골격
/root/capa-app/ 디렉터리를 만들고 그 안에 application.yaml 을 만드세요. apiVersion 은 argoproj.io/v1alpha1, kind 는 Application, metadata.name 은 guestbook, metadata.namespace 는 argocd 입니다.
Application 은 argoproj.io 그룹의 커스텀 리소스입니다. metadata.namespace 는 배포 대상이 아니라 Application 오브젝트 자신이 사는 곳이며, 보통 Argo CD 가 설치된 네임스페이스입니다.
source — 무엇을 가져올 것인가
같은 파일에 spec.project 를 capa-demo 로, spec.source.repoURL 을 https://gitea.homelab.internal/platform/guestbook.git, spec.source.targetRevision 을 main, spec.source.path 를 overlays/prod 로 채우세요.
spec.source 아래에 저장소 주소, 리비전, 경로 세 가지가 들어갑니다. targetRevision 은 브랜치·태그·커밋 SHA 를 모두 받으며, 운영에서는 HEAD 보다 고정된 이름을 쓰는 편이 안전합니다.
destination — 어디에 놓을 것인가
spec.destination.server 를 https://kubernetes.default.svc, spec.destination.namespace 를 capa-guestbook 으로 지정하세요. destination.name 은 쓰지 마세요.
같은 클러스터 안에 배포할 때 쓰는 주소가 정해져 있습니다. server 와 name 은 같은 것을 가리키는 두 방식이라 동시에 쓰면 안 됩니다.
자동 동기화와 syncOptions
spec.syncPolicy.automated.prune 과 spec.syncPolicy.automated.selfHeal 을 둘 다 true 로 두고, spec.syncPolicy.syncOptions 에 CreateNamespace=true 와 PruneLast=true 두 항목을 넣으세요.
automated 아래의 두 불리언은 각각 'Git 에서 지운 것을 클러스터에서도 지울까' 와 '손으로 바꾼 값을 되돌릴까' 를 정합니다. syncOptions 는 문자열 배열이고 키=값 형태로 씁니다.
재시도 백오프 설계
spec.syncPolicy.retry.limit 을 5, spec.syncPolicy.retry.backoff.duration 을 5s, factor 를 2, maxDuration 을 3m 으로 지정하세요.
backoff 는 duration 에서 시작해 매번 factor 배씩 늘고 maxDuration 에서 멈춥니다. 요구한 값으로 계산하면 5초, 10초, 20초, 40초, 80초가 나오는지 직접 곱해 보세요.
HPA 가 관리하는 필드를 diff 에서 빼기
spec.ignoreDifferences 의 첫 항목에 group: apps, kind: Deployment, jsonPointers 에 /spec/replicas 를 넣어 HPA 가 관리하는 필드를 비교에서 빼세요.
ignoreDifferences 는 배열이고 각 항목은 group/kind 로 대상을 좁힌 뒤 jsonPointers 로 필드를 지목합니다. JSON Pointer 는 점이 아니라 슬래시로 경로를 씁니다.
대상 네임스페이스를 실제로 만들기
클러스터에 네임스페이스 capa-guestbook 을 실제로 만들고 라벨 app.kubernetes.io/part-of=capa 를 붙이세요.
여기서부터는 파일이 아니라 진짜 클러스터입니다. kubectl create namespace 로 만든 뒤 label 을 붙이거나, 매니페스트를 써서 apply 해도 됩니다.
추적 어노테이션까지 붙인 디플로이먼트
네임스페이스 capa-guestbook 에 디플로이먼트 guestbook-ui 를 실제로 만드세요. replicas 는 2, 컨테이너 이미지는 nginx:1.27, 그리고 디플로이먼트 자신의 어노테이션으로 argocd.argoproj.io/tracking-id 를 Argo CD 형식에 맞게 붙이세요. 앱 이름은 guestbook 입니다.
추적 ID 형식은 APP_NAME:GROUP/KIND:NAMESPACE/NAME 입니다. apps 그룹의 Deployment 이므로 GROUP 자리가 비어 있지 않다는 점에 주의하세요.