Overview
지난 포스팅에서는 Kustomize를 활용해 Kubernetes 리소스를 효율적으로 관리하는 방법을 정리했었다.
2023.10.12 - [Container Orchestration/Kubernetes] - 1. Kustomize란?
이번 시간에는 Kustomize를 ArgoCD와 함께 연동해 GitOps 기반의 자동 배포 환경을 구성해보려고 한다.
ArgoCD는 Git 저장소에 선언된 매니페스트를 기준으로 쿠버네티스 클러스터 상태를 자동으로 동기화해주는 도구다. 여기에 Kustomize를 결합하면, 환경별 YAML 오버레이를 손쉽게 관리하면서도, GitOps 방식으로 배포를 자동화할 수 있다.
이번 실습에서는 ApplicationSet 리소스를 사용해 dev, qa, prod 환경에 대해 자동으로 여러 애플리케이션을 생성하고, 배포까지 완료하는 전체 흐름을 다뤄본다.
이를 통해 환경별 리소스를 자동 생성하고 유지보수하는 GitOps 전략의 핵심 개념을 체득할 수 있다.
📅 관련 글
2023.05.16 - [IaC/CI CD Tool] - ArgoCD란?
2023.08.09 - [IaC/CI CD Tool] - ArgoCD 설치 AWS & GCP
2023.10.02 - [IaC/CI CD Tool] - ArgoCD ApplicationSet이란? (작성 방법)
2023.10.07 - [Container Orchestration/Kubernetes] - 1. Kustomize란?
2023.10.08 - [Container Orchestration/Kubernetes] - 2. Kustomize + ArgoCD ApplicationSet
2024.02.02 - [IaC/CI CD Tool] - Argo Workflow란?
2024.04.09 - [IaC/CI CD Tool] - ArgoCD SSO 구성 가이드(GCP Oauth)
2025.02.19 - [IaC/CI CD Tool] - ArgoCD SSO 구성 가이드(Gitlab)
Kustomize + ArgoCD ApplicationSet
자세한 내용은 아래의 Github를 참조하면 된다. `argocd-applicationset-nginx-deployment` 를 실습해볼 예정이다.
https://github.com/somaz94/kustomize-study
GitHub - somaz94/kustomize-study: kustomize-study
kustomize-study. Contribute to somaz94/kustomize-study development by creating an account on GitHub.
github.com
argocd-applicationset-nginx-deployment
ArgoCD Applicationset과 Kustomize을 사용해 배포할 것이다. 환경은 `dev, qa, prod` 이다.
디렉토리 구조
- `app/nginx/base` : Nginx 어플리케이션의 기본 리소스가 포함되어 있다.
- `app/nginx/overlays` : 특정 환경에 맞게 조정된 리소스 구성이 포함된 디렉터리이다. 각 환경 `(dev, qa, prod)` 에 대한 리소스 변형을 정의한다.
- `appset` : ArgoCD ApplicationSet에 대한 정의가 포함된다.
- `github-secret` : Github 저장소에 액세스하기 위한 비밀을 정의한다.
.
├── README.md
├── app
│ └── nginx
│ ├── base
│ │ ├── kustomization.yaml
│ │ ├── nginx-deployment.yaml
│ │ ├── nginx-ingress.yaml
│ │ └── nginx-service.yaml
│ └── overlays
│ ├── dev
│ │ ├── ingress.yaml
│ │ ├── kustomization.yaml
│ │ └── replica-count.yaml
│ ├── prod
│ │ ├── ingress.yaml
│ │ ├── kustomization.yaml
│ │ └── replica-count.yaml
│ └── qa
│ ├── ingress.yaml
│ ├── kustomization.yaml
│ └── replica-count.yaml
├── appsets
│ └── nginx-applicationset.yaml
└── github-secret
└── github-secret.yaml
Deployment Workflow
- ArgoCD에 Github Repo용 Secret 및 Project 생성
- 템플릿 작성 및 업로드
- ArgoCD에 ApplicationSet 배포
ArgoCD에 Github Repo용 Secret 및 Project 생성
# github-secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: github-secret
namespace: argocd
labels:
argocd.argoproj.io/secret-type: repository
stringData:
type: git
url: git@github.com:somaz94/kustomize-study.git
sshPrivateKey: |
# sshPrivateKey Example
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAABlwAAAAdzc2gtcn
...
0zbXo5J4Yb6oMAAAAUZ2VuaXVzNTcxMUBnbWFpbC5jb20BAgMEBQYH
-----END OPENSSH PRIVATE KEY-----
# secret 배포
kubectl apply -f github-secret.yaml -n argocd
템플릿 작성 및 업로드
해당 내용은 Github 링크로 대체한다.
ArgoCD에 ApplicationSet 배포
# nginx-applicationset.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: nginx-appicationset
spec:
generators:
- matrix:
generators:
- list:
elements:
- cluster: master-node.somaz.link
url: https:// # ClusterIP or URI or Domain
overlay: dev # This new field specifies the overlay to use
values:
environment: dev
project: nginx
- cluster: master-node.somaz.link
url: https://
overlay: qa
values:
environment: qa
project: nginx
- cluster: master-node.somaz.link
url: https://
overlay: prod
values:
environment: prod
project: nginx
- git:
repoURL: git@github.com:somaz94/kustomize-study.git
revision: HEAD
directories:
- path: argocd-applicationset-nginx-deployment/app/nginx/overlays/{{overlay}} # Use the new overlay field
template:
metadata:
name: '{{values.environment}}-{{values.project}}'
spec:
project: '{{values.project}}'
source:
repoURL: git@github.com:somaz94/kustomize-study.git
targetRevision: HEAD
path: '{{path}}'
kustomize:
namePrefix: '{{values.environment}}-'
destination:
server: '{{url}}'
namespace: '{{values.environment}}-{{values.project}}'
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
- ApplyOutOfSyncOnly=true
# argocd appcliationset 배포
kubectl apply -f nginx-applicationset -n argocd
k get po,svc,ingress -n dev-nginx
NAME READY STATUS RESTARTS AGE
pod/dev-nginx-deployment-8d545c96d-2w7sw 1/1 Running 0 88s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/dev-nginx-service ClusterIP 10.233.21.0 <none> 80/TCP 88s
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/dev-nginx-ingress <none> dev-nginx.fgn.nerdystar.io 10.10.100.22 80 88s
k get po,svc,ingress -n qa-nginx
NAME READY STATUS RESTARTS AGE
pod/qa-nginx-deployment-8d545c96d-4bd8t 1/1 Running 0 93s
pod/qa-nginx-deployment-8d545c96d-mxchm 1/1 Running 0 93s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/qa-nginx-service ClusterIP 10.233.62.87 <none> 80/TCP 94s
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/qa-nginx-ingress <none> qa-nginx.fgn.nerdystar.io 10.10.100.22 80 93s
k get po,svc,ingress -n prod-nginx
NAME READY STATUS RESTARTS AGE
pod/prod-nginx-deployment-8d545c96d-45z4t 1/1 Running 0 96s
pod/prod-nginx-deployment-8d545c96d-jspm5 1/1 Running 0 96s
pod/prod-nginx-deployment-8d545c96d-qf97w 1/1 Running 0 96s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/prod-nginx-service ClusterIP 10.233.17.172 <none> 80/TCP 97s
NAME CLASS HOSTS ADDRESS PORTS AGE
ingress.networking.k8s.io/prod-nginx-ingress <none> prod-nginx.fgn.nerdystar.io 10.10.100.22 80 96s
Helm 기반 응용 실습
실무에서는 Helm Chart를 그대로 쓰기 어려운 경우도 많은데, 이때 Kustomize로 Helm Chart를 감싸 환경별 오버레이를 추가하는 방식이 효과적이다.
예를 들어 base 디렉토리에는 Helm으로 생성한 리소스를 넣고, `overlays/dev` 에는 `values.yaml` 을 `override` 하는 방식이다.
# base/kustomization.yaml
helmCharts:
- name: nginx
repo: https://charts.bitnami.com/bitnami
version: 13.2.18
releaseName: nginx
namespace: default
valuesFile: values.yaml- 환경별 `values.yaml` 은 `overlay` 디렉토리에서 분리 관리한다.
CI/CD 통합 예제
Kustomize + ArgoCD 구조에서 GitOps의 핵심은 "Git 푸시 → 자동 배포" 흐름이다.
아래는 GitHub Actions를 이용해 main 브랜치에 커밋이 발생했을 때, ArgoCD CLI로 app sync 를 트리거하는 예시이다.
name: ArgoCD Sync Trigger
on:
push:
branches:
- main
jobs:
sync:
runs-on: ubuntu-latest
steps:
- name: Sync ArgoCD App
run: |
argocd login $ARGOCD_SERVER --username admin --password $ARGOCD_PASSWORD --insecure
argocd app sync nginx-dev
env:
ARGOCD_SERVER: argocd.example.com
ARGOCD_PASSWORD: ${{ secrets.ARGOCD_PASSWORD }}- 이를 통해 개발자는 Git에 커밋만 해도 배포가 자동화되는 GitOps의 완전한 흐름을 경험할 수 있다.
Sync 정책 정밀 설정
`syncPolicy` 내에는 `automated` 의 `prune, selfHeal` 외에도 `syncOptions` 항목을 통해 다양한 옵션을 적용할 수 있다. 이를 통해 보다 세밀한 동기화 전략을 구성할 수 있다.
예를 들어 다음과 같은 설정들이 자주 활용된다.
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true # 네임스페이스 자동 생성
- ApplyOutOfSyncOnly=true # 실제 변경된 리소스만 Apply
- RespectIgnoreDifferences=true # ignoreDifferences 설정을 존중
- Validate=false # 리소스 유효성 검증 건너뛰기
- PrunePropagationPolicy=foreground # 삭제 전략 설정- 이러한 옵션들을 적절히 조합하면 팀의 배포 전략에 맞는 유연한 GitOps 파이프라인을 설계할 수 있다.
운영 최적화 팁
ArgoCD Ignore Differences 설정
특정 리소스는 운영 중 자동으로 바뀌는 필드 때문에 ArgoCD가 항상 `OutOfSync` 로 표시하는 경우가 있다. 예를 들어 Pod template 내 `metadata.annotations` 등이다.
이럴 때는 아래처럼 `ignoreDifferences` 옵션으로 무시할 수 있다:
spec:
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/template/metadata/annotations
- group: ""
kind: Service
jsonPointers:
- /spec/clusterIP- 이를 통해 불필요한 Sync 표시나 의도치 않은 리소스 업데이트를 방지할 수 있다.
마무리: GitOps 자동화의 실전 첫걸음
ArgoCD와 Kustomize를 연동하면 단순한 수동 배포를 넘어서 "환경별 리소스를 Git으로 선언 → 자동 동기화" 하는 GitOps 전략을 구현할 수 있다.
특히 ApplicationSet 리소스를 사용하면 수많은 애플리케이션을 패턴에 따라 자동 생성할 수 있어 규모가 큰 마이크로서비스 구조나 다중 환경 운영에서도 매우 유리하다.
또한 Kustomize의 `base/overlay` 구조 덕분에 매니페스트 중복을 줄이고, 유지보수가 쉬워지는 효과도 있다.
CI 파이프라인에서 Kustomize를 통해 빌드된 결과물을 ArgoCD가 자동 반영하도록 구성하면, 진정한 GitOps 워크플로우로 발전시킬 수 있다.
이번 실습은 nginx 배포를 중심으로 했지만, 실제 프로젝트 환경에서는 수십~수백 개의 리소스를 효율적으로 운영할 수 있게 되는 핵심 자동화 기반이 될 것이다.
Reference
- GitHub - Kustomize + ArgoCD 실습 코드
https://github.com/somaz94/kustomize-study - ArgoCD 공식 문서
https://argo-cd.readthedocs.io/ - ArgoCD ApplicationSet 공식 문서
https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/ - Kustomize 공식 문서
https://kubectl.docs.kubernetes.io/references/kustomize/ - ArgoCD SyncPolicy 옵션 가이드
https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/ - ArgoCD Ignore Differences 설정 예시
https://argo-cd.readthedocs.io/en/stable/user-guide/health/#ignoring-differences - Bitnami Helm Charts (nginx 예시)
https://github.com/bitnami/charts/tree/main/bitnami/nginx - GitOps란 무엇인가 (Weaveworks 소개)
https://www.weave.works/technologies/gitops/ - CI/CD with GitHub Actions + ArgoCD 예제
https://mrdevops.medium.com/github-action-kustomize-argocd-94e5abfcf6bd
'Container Orchestration > Kubernetes' 카테고리의 다른 글
| K3s & k3sup 이란? (2) | 2024.01.05 |
|---|---|
| Flux란? / Flux + Kustomize (2) | 2023.10.16 |
| 1. Kustomize란? (0) | 2023.10.12 |
| CertManager로 Let's Encrypt 인증서 발급 (2) | 2023.10.03 |
| Kubernetes Autoscaling & Karpenter (0) | 2023.05.24 |