[FluxCD] FluxCD란?

https://fluxcd.io/flux/

 

📌 FluxCD 개요

 

Kubernetes를 위한 GitOps 도구

Git 저장소에 저장된 구성 파일을 기반으로 쿠버네티스 클러스터를 자동으로 동기화

• GitOps Toolkit이라 불리는 모듈화된 컨트롤러들을 통해 Git, OCI, S3 버킷 등을 소스로 관찰(source)
• Kustomize·Helm·이미지 자동화(image automation) 컨트롤러로 실제 클러스터에 리소스를 적용(apply)·갱신(reconcile)

 

아키텍처

FluxCD는 GitOps Toolkit 위에 구축된 여러 개의 컨트롤러(controller) 모듈로 이루어짐

• Source Controller: GitRepository, HelmRepository, Bucket(CustomSource) 등 외부 소스 변화를 감
• Kustomize Controller: Kustomization CR을 통해 Kustomize 오버레이를 빌드·적용
• Helm Controller: HelmRelease CR로 Helm 차트를 관리하고, 의존성 차트도 함께 동기화
• Notification Controller: Slack, Email, MS Teams 등으로 배포 이벤트를 알림
• Image Automation Controller: OCI 레지스트리의 최신 이미지 태그를 검사하고, Git 매니페스트의 이미지 태그를 자동으로 업데이트
• Image Reflector Controller: 레지스트리 메타데이터를 Kubernetes CR에 반영하여 다른 컨트롤러가 사용할 수 있도록

위 컨트롤러들은 Kubernetes API 익스텐션(CRD) 및 컨트롤러 런타임을 통해 구현되며, 서로 독립적이면서도 dependsOn으로 의존성을 설정 가능

 

주요 CRD

• GitRepository, HelmRepository, Bucket: 외부 소스 정의
• Kustomization: 선언된 경로(path)에서 매니페스트를 동기화
• HelmRelease: Helm 차트 배포 및 업데이트
• ImagePolicy: 레지스트리 이미지를 필터링·선택하는 정책
• ImageUpdateAutomation: Git 매니페스트 내 이미지 태그를 자동 커밋
• Notification: 알림 및 오토메이션 채널 설정

 

동작 방식

1. 사용자가 Git에 매니페스트(Deployment, Service, ConfigMap 등)를 커밋
2. Source Controller가 변경 사항 감지 → 해당 내용을 Kubernetes CR로 등록
3. Kustomize/Helm Controller가 실제 매니페스트로 변환하여 클러스터에 apply
4. 컨트롤러가 클러스터 리소스 상태를 모니터링하다가, Git 상태와 달라지면 재동기화(reconcile)
5. Notification Controller로 배포 성공·실패 이벤트 전송
6. Image Automation이 새로운 이미지 태그를 발견하면, Git 매니페스트를 자동 수정·커밋하여 파이프라인 시작

 

멀티 클러스터 전략

• Standalone: 각 클러스터에 Flux를 독립 설치 → 보안성 강화, 관리 복잡도 증가
• Hub-and-Spoke: 중앙 클러스터에서 Flux 허브 운영 → 스포크 클러스터에 원격 동기화
• 모노레포: 단일 Git 레포에서 apps/, infrastructure/, clusters/ 등의 폴더를 운영하며 Kustomization.spec.path로 클러스터·환경별 오버레이를 분리 관리

 

 

📌 디렉토리 구조(모노레포)

├── apps
│   ├── base
│   └── overlays
├── infrastructure
│   ├── base
│   ├── staging
│   └── production
└── clusters
    ├── staging
    └── production

• apps/: 실제 애플리케이션 배포 매니페스트 (Kustomize overlays 포함)
  • 📌  base/overlays 구조로 관리할때 사용!
• infrastructure/: 클러스터 애드온(CRD, admission controller 등) 및 공통 인프라 리소스
  • 📌  helm으로 관리할때 사용!
• clusters/: 각 클러스터별로 apps·infrastructure 디렉토리를 조합해서 참조하는 Kustomization 리소스 모음
  • values.yaml 넣어놓고, namespace, 등 클러스터 구성할때 사용!

📍 apps 또는 infrastructure 에서 배포 파일들(or CRD) 가져와서,

clusters에서 flux toolkit으로 한번 감싸는 방식 !!!!!

 

 

📌 적용 방법

1. Git 저장소에 변경사항 커밋 및 푸시

2. FluxCD 동기화 과정 모니터링

• 자동 동기화 확인
  • FluxCD는 기본적으로 설정된 간격으로 Git 저장소의 변경사항을 자동으로 감지하고 적용 

# 클러스터 컨텍스트 전환 (필요시)
kubectl config use-context betacluster

# FluxCD 소스 상태 확인
flux get sources git

# Kustomization 적용 상태 확인
flux get kustomizations -A

• 수동 동기화 트리거 (선택 사항)

flux reconcile source git flux-system

flux reconcile kustomization -A
flux reconcile helmrelease keycloak -n keycloak

3. 설치 과정 확인

4. 로그 및 이벤트 확인

# Flux 컨트롤러 로그 확인
flux logs --all-namespaces --follow

# 특정 Kustomization 로그 확인
flux logs --kind=Kustomization --name=keycloak -n flux-system

 

5. 문제 해결 방법

# 전체 FluxCD 상태 확인
flux check

# 특정 helmrelease 상태 자세히 확인
flux get helmrelease keycloak -n keycloak --verbose