K8s FluxCD GitOps 자동 배포

글쓴이 /

FluxCD란?

FluxCD는 CNCF 졸업 프로젝트로, Git 리포지토리를 단일 소스 오브 트루스(Single Source of Truth)로 사용하여 Kubernetes 클러스터를 자동으로 동기화하는 GitOps 도구입니다. ArgoCD가 웹 UI 중심의 접근이라면, FluxCD는 CLI와 CRD 중심의 쿠버네티스 네이티브 접근 방식을 취합니다.

구분 FluxCD ArgoCD
아키텍처 분산 컨트롤러 (마이크로서비스) 단일 서버 + UI
UI CLI + CRD (Weave GitOps UI 별도) 내장 웹 UI
멀티테넌시 네이티브 지원 AppProject로 구현
Helm 지원 HelmRelease CRD Application CRD
이미지 자동화 내장 (Image Automation) 외부 도구 필요

설치: flux bootstrap

FluxCD는 flux bootstrap 명령으로 클러스터에 설치하면서 동시에 Git 리포지토리를 구성합니다.

# Flux CLI 설치
curl -s https://fluxcd.io/install.sh | sudo bash

# GitHub 리포지토리로 부트스트랩
flux bootstrap github 
  --owner=my-org 
  --repository=k8s-gitops 
  --path=clusters/production 
  --personal 
  --branch=main

# 설치 확인
flux check
kubectl get pods -n flux-system

부트스트랩 후 Git 리포지토리에 Flux 컴포넌트 매니페스트가 자동 생성됩니다. Flux 자체도 GitOps로 관리됩니다.

Git 리포지토리 구조

FluxCD 프로젝트의 권장 디렉토리 구조입니다.

k8s-gitops/
├── clusters/
│   ├── production/
│   │   ├── flux-system/          # Flux 부트스트랩 (자동 생성)
│   │   ├── infrastructure.yaml   # 인프라 Kustomization
│   │   └── apps.yaml             # 앱 Kustomization
│   └── staging/
│       ├── flux-system/
│       ├── infrastructure.yaml
│       └── apps.yaml
├── infrastructure/
│   ├── base/
│   │   ├── cert-manager/
│   │   ├── ingress-nginx/
│   │   └── monitoring/
│   ├── production/
│   │   └── kustomization.yaml
│   └── staging/
│       └── kustomization.yaml
└── apps/
    ├── base/
    │   ├── order-service/
    │   │   ├── deployment.yaml
    │   │   ├── service.yaml
    │   │   ├── hpa.yaml
    │   │   └── kustomization.yaml
    │   └── user-service/
    ├── production/
    │   ├── order-service-patch.yaml
    │   └── kustomization.yaml
    └── staging/
        └── kustomization.yaml

GitRepository와 Kustomization

FluxCD의 핵심 CRD는 GitRepository(소스)와 Kustomization(배포)입니다.

# clusters/production/apps.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: k8s-gitops
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/my-org/k8s-gitops
  ref:
    branch: main
  secretRef:
    name: github-credentials
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/production
  prune: true            # Git에서 삭제하면 클러스터에서도 삭제
  sourceRef:
    kind: GitRepository
    name: k8s-gitops
  dependsOn:
    - name: infrastructure  # 인프라 먼저 배포
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: order-service
      namespace: default
  timeout: 3m

HelmRelease: Helm 차트 GitOps

Helm 차트도 HelmRelease CRD로 선언적으로 관리합니다.

# infrastructure/base/ingress-nginx/helmrelease.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: ingress-nginx
  namespace: flux-system
spec:
  interval: 1h
  url: https://kubernetes.github.io/ingress-nginx
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: ingress-nginx
  namespace: ingress-nginx
spec:
  interval: 10m
  chart:
    spec:
      chart: ingress-nginx
      version: "4.10.x"  # 세미버전 범위
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
        namespace: flux-system
  values:
    controller:
      replicas: 2
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
      metrics:
        enabled: true
  upgrade:
    remediation:
      retries: 3        # 업그레이드 실패 시 3회 재시도
    cleanupOnFail: true
  rollback:
    cleanupOnFail: true

이미지 자동 업데이트

FluxCD의 고유 기능인 Image Automation은 새 컨테이너 이미지가 레지스트리에 푸시되면 자동으로 Git을 업데이트하고 배포합니다.

# 이미지 레지스트리 스캔
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: order-service
  namespace: flux-system
spec:
  image: ghcr.io/my-org/order-service
  interval: 5m
  secretRef:
    name: ghcr-credentials
---
# 이미지 태그 정책: 세미버전 최신
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: order-service
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: order-service
  policy:
    semver:
      range: ">=1.0.0"
---
# Git 자동 업데이트
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: k8s-gitops
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        name: fluxbot
        email: flux@my-org.com
      messageTemplate: "chore: update {{.AutomationObject}} images"
    push:
      branch: main
  update:
    path: ./apps
    strategy: Setters

# apps/base/order-service/deployment.yaml
# 마커 주석으로 자동 업데이트 대상 지정
spec:
  containers:
  - name: order-service
    image: ghcr.io/my-org/order-service:1.2.3 # {"$imagepolicy": "flux-system:order-service"}

알림 설정

배포 상태를 Slack, Discord, Microsoft Teams 등으로 알림을 보낼 수 있습니다.

apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
  name: discord
  namespace: flux-system
spec:
  type: discord
  secretRef:
    name: discord-webhook
---
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
  name: deployment-alerts
  namespace: flux-system
spec:
  providerRef:
    name: discord
  eventSeverity: info
  eventSources:
    - kind: Kustomization
      name: "*"
    - kind: HelmRelease
      name: "*"
  exclusionList:
    - ".*upgrade.*retries.*"

멀티클러스터 관리

FluxCD는 관리 클러스터에서 여러 워크로드 클러스터를 중앙 관리할 수 있습니다.

# 원격 클러스터 등록
flux create secret git remote-cluster-kubeconfig 
  --url=https://remote-cluster-api:6443 
  --kubeconfig=./remote-kubeconfig

# 원격 클러스터용 Kustomization
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: remote-apps
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/remote-cluster
  prune: true
  sourceRef:
    kind: GitRepository
    name: k8s-gitops
  kubeConfig:
    secretRef:
      name: remote-cluster-kubeconfig

의존성과 배포 순서

dependsOn으로 배포 순서를 제어합니다. 인프라 → 미들웨어 → 앱 순으로 배포합니다.

# clusters/production/infrastructure.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: infrastructure
  namespace: flux-system
spec:
  interval: 10m
  path: ./infrastructure/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: k8s-gitops
  wait: true  # 모든 리소스가 Ready될 때까지 대기
---
# clusters/production/apps.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: k8s-gitops
  dependsOn:
    - name: infrastructure  # 인프라 Ready 후 앱 배포

SOPS를 활용한 시크릿 관리

FluxCD는 Mozilla SOPS를 내장 지원하여 암호화된 시크릿을 Git에 안전하게 저장할 수 있습니다.

# SOPS로 시크릿 암호화
sops --encrypt --age age1... 
  --encrypted-regex '^(data|stringData)$' 
  secret.yaml > secret.enc.yaml

# Kustomization에서 SOPS 복호화 활성화
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  decryption:
    provider: sops
    secretRef:
      name: sops-age  # AGE 키가 담긴 Secret
  path: ./apps/production
  sourceRef:
    kind: GitRepository
    name: k8s-gitops

운영 명령어

# 상태 확인
flux get all
flux get kustomizations
flux get helmreleases -A

# 수동 동기화 트리거
flux reconcile kustomization apps --with-source

# 특정 리소스 일시 중지/재개
flux suspend kustomization apps
flux resume kustomization apps

# 로그 확인
flux logs --follow --level=error

# 트리 뷰로 의존성 확인
flux tree kustomization apps

실전 팁

  • prune: true: Git에서 삭제한 리소스가 클러스터에서도 자동 삭제됩니다. 프로덕션에서는 주의해서 사용하세요
  • interval 조정: GitRepository는 1~5분, Kustomization은 5~10분이 적절합니다. 너무 짧으면 API 서버에 부하가 갑니다
  • healthChecks: Kustomization에 헬스체크를 추가하면 배포 실패 시 자동 롤백됩니다
  • Kustomize 오버레이와 결합: base/overlay 패턴으로 환경별 설정을 관리하면 FluxCD와 자연스럽게 통합됩니다
  • PR 기반 배포: staging 브랜치 → main 머지로 프로덕션 배포를 트리거하면 코드 리뷰 기반 배포 승인이 가능합니다

마무리

FluxCD는 쿠버네티스 네이티브한 GitOps 도구로, CRD 기반의 선언적 배포 관리, 내장 이미지 자동 업데이트, SOPS 시크릿 암호화 등 실전에 필요한 기능을 제공합니다. Git을 유일한 진실의 소스로 사용하여 감사 추적, 롤백, 멀티클러스터 관리까지 체계적으로 운영할 수 있습니다.

위로 스크롤
WordPress Appliance - Powered by TurnKey Linux