[Flux] FluxCD란?

📌 FluxCD

Kubernetes를 위한 GitOps 도구

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

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

 

아키텍처

https://fluxcd.io/flux/

 

GitOps Toolkit 위에 구축된 여러 개의 컨트롤러(controller) 모듈과 구성 가능한 API, Go 패키지로 구성되어 있다.

• 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: 알림 및 오토메이션 채널 설정

 

동작 방식

• Source / Kustomize / Helm Controller
  1. 사용자가 Git에 매니페스트(Deployment, Service, ConfigMap 등)를 커밋
  2. Source Controller가 변경 사항 감지 → Artifact 생성 → CR Status에 Artifact 메타데이터 등록
  3. Kustomize/Helm Controller가 CR 변경사항 감지 → Artifact URL로 실제 파일 다운로드 → 실제 매니페스트로 변환하여 클러스터에 apply
  4. 컨트롤러가 클러스터 리소스 상태를 모니터링하다가, Git 상태와 달라지면 재동기화(reconcile)
• Notification Controller
  1. 다른 Controller의 이벤트 수신
  2. Provider(Slack, Discord, ..)로 알림 전송
• Image Automation Controller
  1. image-reflector-controller가 image repository 스캔하고, 이미지 metadata를 kubernetes resource에 반영
  2. image-automation-controller가 최근 스캔된 image 기반으로 yaml 업데이트,하고, Git Repository에 변경사항 commit

 

멀티 클러스터 전략

• 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