Push Overlays to a Real Cluster and Promote Them

한국어 원문으로 표시합니다.

목표

kustomize base 와 오버레이를 실제 클러스터에 올려 namePrefix, 공통 라벨, configMapGenerator, replicas·이미지 패치가 만들어 내는 결과를 kubectl 로 확인합니다. 그리고 이미지 태그 한 줄을 바꾸는 것만으로 prod 승격이 끝나는 흐름을 손으로 재현합니다.

왜 중요한가

GitOps 에이전트가 하는 일의 절반은 렌더링 입니다. Argo CD 의 repo-server 는 kustomization.yaml 을 보면 kustomize build 를, Chart.yaml 을 보면 helm template 을 돌려 최종 매니페스트를 만듭니다. 즉 여러분이 여기서 kubectl kustomize 로 보는 출력이 곧 에이전트가 계산하는 desired state 입니다. 이걸 직접 만들어 보지 않으면 "Git 에는 replicas 가 없는데 클러스터에는 3 이 들어가 있다" 같은 상황을 설명할 수 없습니다. 특히 configMapGenerator 의 해시 접미어는 실무에서 아주 중요합니다 — 설정이 바뀌면 ConfigMap 이름이 바뀌고, 이름이 바뀌면 디플로이먼트 스펙이 바뀌어 롤링 업데이트가 자동으로 일어납니다. 이름을 고정해 두면 설정만 바뀌었을 때 파드가 재시작되지 않아 조용히 옛 값으로 도는 사고가 납니다.

단계

/root/cgoa-envs/ns.yaml 에 네임스페이스 cgoa-dev 와 cgoa-prod 를 선언하고 클러스터에 적용하세요.
/root/cgoa-envs/base/ 에 Deployment web(replicas 1, 셀렉터·파드 라벨 app: web, 컨테이너 이름 web, 이미지 nginx:1.27-alpine, envFrom 으로 ConfigMap web-config 참조)과 Service web(port 80, targetPort 80)을 작성하고, base/kustomization.yaml 에 두 리소스와 함께 모든 오브젝트에 라벨 app.kubernetes.io/part-of: cgoa-shop 을 붙이는 설정, 그리고 configMapGenerator 로 이름 web-config 에 리터럴 GREETING=hello 를 넣으세요. 아직 적용하지 말고 kubectl kustomize /root/cgoa-envs/base 로 렌더만 확인하세요.
/root/cgoa-envs/overlays/dev/kustomization.yaml 에 resources: [../../base], namespace: cgoa-dev, namePrefix: dev- 를 쓰고 kubectl apply -k 로 클러스터에 적용하세요.
적용 결과에서 디플로이먼트 dev-web 의 envFrom 이 가리키는 ConfigMap 이름을 확인하고, 같은 이름의 ConfigMap 이 cgoa-dev 네임스페이스에 실제로 존재하는지 확인하세요. (이름 뒤에 해시 접미어가 붙어 있어야 합니다.)
/root/cgoa-envs/overlays/prod/kustomization.yaml 을 만드세요 — resources: [../../base], namespace: cgoa-prod, namePrefix: prod-, replicas 로 web 을 3, images 로 nginx 의 newTag 를 1.27-alpine 으로 고정. 그리고 kubectl apply -k 로 적용하세요.
승격을 수행하세요. prod 오버레이의 이미지 태그만 1.28-alpine 으로 바꾸고 다시 적용합니다. 적용 후 cgoa-prod 의 prod-web 은 nginx:1.28-alpine, cgoa-dev 의 dev-web 은 여전히 nginx:1.27-alpine 이어야 합니다.
/root/cgoa-envs/diff-dev-prod.txt 에 dev 오버레이 렌더 결과와 prod 오버레이 렌더 결과의 diff 출력을 저장하세요.

참고

kubectl apply -k <디렉터리> 는 kubectl kustomize 결과를 그대로 적용합니다.
kustomization 의 공통 라벨 필드는 kustomize 버전에 따라 labels: 또는 commonLabels: 입니다. 둘 중 동작하는 쪽을 쓰면 됩니다 — 채점은 결과로 만들어진 오브젝트의 라벨을 봅니다.
diff a b > out.txt 는 차이가 있으면 종료 코드 1 을 돌려줍니다. 셸에서 중단되지 않게 || true 를 붙이세요.
흔한 실수: base 에 namespace: 를 넣어 두면 오버레이의 네임스페이스와 충돌해 헷갈립니다. 네임스페이스는 오버레이에서만 정하세요.

환경 네임스페이스 두 개

/root/cgoa-envs/ns.yaml 에 네임스페이스 cgoa-dev 와 cgoa-prod 를 선언하고 클러스터에 적용하세요.

네임스페이스도 선언형으로 만드는 습관을 들이세요. 파일에 두 문서를 담아 한 번에 적용해도 되고, 파일을 나눠도 됩니다.

base 와 configMapGenerator

/root/cgoa-envs/base/ 에 Deployment web(replicas 1, 셀렉터·파드 라벨 app: web, 컨테이너 이름 web, 이미지 nginx:1.27-alpine, envFrom 으로 ConfigMap web-config 참조)과 Service web(port 80, targetPort 80)을 작성하고, base/kustomization.yaml 에 두 리소스와 함께 모든 오브젝트에 라벨 app.kubernetes.io/part-of: cgoa-shop 을 붙이는 설정, 그리고 configMapGenerator 로 이름 web-config 에 리터럴 GREETING=hello 를 넣으세요. 아직 적용하지 말고 kubectl kustomize /root/cgoa-envs/base 로 렌더만 확인하세요.

configMapGenerator 는 내용의 해시를 이름 뒤에 붙입니다. 아직 클러스터에 올리지 말고 kubectl kustomize 로 렌더 결과만 확인하세요.

dev 오버레이를 클러스터에 적용

/root/cgoa-envs/overlays/dev/kustomization.yaml 에 resources: [../../base], namespace: cgoa-dev, namePrefix: dev- 를 쓰고 kubectl apply -k 로 클러스터에 적용하세요.

kubectl apply -k <디렉터리> 는 렌더와 적용을 한 번에 합니다. namePrefix 가 붙은 이름으로 조회해야 보입니다.

해시 접미어가 워크로드에 연결됐는지

적용 결과에서 디플로이먼트 dev-web 의 envFrom 이 가리키는 ConfigMap 이름을 확인하고, 같은 이름의 ConfigMap 이 cgoa-dev 네임스페이스에 실제로 존재하는지 확인하세요. (이름 뒤에 해시 접미어가 붙어 있어야 합니다.)

kustomize 는 생성된 ConfigMap 이름을 참조하는 곳까지 같이 고쳐 줍니다. 디플로이먼트의 envFrom 이 어떤 이름을 가리키는지 보고, 그 이름의 ConfigMap 이 실제로 있는지 확인하세요.

prod 오버레이 적용

/root/cgoa-envs/overlays/prod/kustomization.yaml 을 만드세요 — resources: [../../base], namespace: cgoa-prod, namePrefix: prod-, replicas 로 web 을 3, images 로 nginx 의 newTag 를 1.27-alpine 으로 고정. 그리고 kubectl apply -k 로 적용하세요.

같은 base 인데 replicas 와 이미지 태그가 달라야 합니다. 오버레이의 kustomization.yaml 만으로 해결하세요.

이미지 태그 한 줄로 승격

승격을 수행하세요. prod 오버레이의 이미지 태그만 1.28-alpine 으로 바꾸고 다시 적용합니다. 적용 후 cgoa-prod 의 prod-web 은 nginx:1.28-alpine, cgoa-dev 의 dev-web 은 여전히 nginx:1.27-alpine 이어야 합니다.

승격은 새 배포가 아닙니다. prod 오버레이에서 태그 값 하나만 바꾸고 다시 적용하면 됩니다. dev 는 건드리지 마세요.

두 환경 렌더 결과의 차이를 파일로

/root/cgoa-envs/diff-dev-prod.txt 에 dev 오버레이 렌더 결과와 prod 오버레이 렌더 결과의 diff 출력을 저장하세요.

kubectl kustomize 결과를 두 개 만들어 diff 로 비교하면 됩니다. diff 는 차이가 있으면 종료 코드가 0 이 아니므로 파이프라인에서 실패로 잡히지 않게 주의하세요.