자동화된 기업용 태그 기반 배포 설정하기

자동화된 기업용 태그 기반 배포 설정하기

버전 태그가 게시될 때마다 새 이미지를 자동으로 배포해요.

출처: 문서

본문

개요

Confident AI는 각 릴리스를 semver 태그가 붙은 컨테이너 이미지(vX.Y.Z)로 출시하고, 셀프호스팅 배포는 Helm values(image.tag)에서 그 태그를 고정해요. 태그 기반 배포는 그 사이 단계를 자동화해요: 새 태그가 게시되면 툴링이 image.tag를 올리고 릴리스를 롤아웃해서, 버전을 배포하려고 values 파일을 손으로 편집할 일이 없어요.

이 가이드는 이미 셀프호스팅 Helm chart를 운영하는 Enterprise 고객을 위한 것이에요. 단일 CI 작업부터 완전한 GitOps까지 이걸 연결하는 세 가지 방법과, 자동화된 롤아웃을 안전하게 유지하는 가드레일을 다룹니다.

모든 설치와 업그레이드는 데이터베이스 마이그레이션 작업을 실행하므로, 태그 올림은 핫 이미지 교체가 아니라 실제 릴리스예요. 먼저 스테이징에서 롤아웃하고, 프로덕션이 스스로 업데이트하게 하기 전에 재해 복구를 읽어 보세요.

버전 관리가 어떻게 동작하나요

퍼스트파티 이미지는 <registry>/confidentai/confident-<service>:<tag>로 주소가 붙고, 릴리스의 모든 서비스가 같은 태그를 공유해요. chart는 단일 손잡이에서 그것들을 풀어요:

image:
  tag: "v2.0.18"   # pin explicitly; defaults to the chart's appVersion when empty

자동화하는 것은 그 한 값뿐이에요. 변경 가능한 태그에 떠다니지 말고 명시적으로 고정해서, 롤아웃이 항상 신중하고 검토 가능한 변경이 되게 해요.

접근 방식 고르기

이 세 가지는 처방이 아니라 설명적인 시작점이에요. 가장 좋은 설정은 여러분 팀이 이미 돌리고 신뢰하는 배포 파이프라인이에요. 검증된 CI나 GitOps 워크플로가 있다면 이 가이드의 새 툴링을 채택하기보다 image.tag를 그것에 접어 넣으세요.

Approach What triggers the update Best for
CI pipeline on tag push You push a vX.Y.Z git tag in your ops repo, and CI runs helm upgrade Teams with existing CI and no GitOps
GitOps image automation A controller watches the registry and commits the new tag to git Teams already running Argo CD or Flux
In-cluster poller (Keel) Keel watches the registry and patches the workloads directly The quickest path, when git-backed history is not required

감사 가능하고 선언적인 설정에는 GitOps가 엔터프라이즈에 가장 적합해요. CI 파이프라인은 git을 통한 검토와 롤백을 여전히 제공하면서 가장 단순한 경로예요.

옵션 A: 태그 푸시 시 CI 파이프라인

Helm values를 ops 저장소에 유지해요. 릴리스를 자르는 것은 그다음 실시간으로 두고 싶은 이미지 태그의 이름인 git 태그를 푸시하는 것이에요. 아래 예시는 GitHub Actions를 씁니다:

name: deploy-confident-ai
on:
  push:
    tags: ["v*.*.*"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # federate into your cloud, no long-lived keys
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Get cluster credentials
        run: |
          # AWS:   aws eks update-kubeconfig --name <cluster> --region <region>
          # GCP:   gcloud container clusters get-credentials <cluster> --region <region>
          # Azure: az aks get-credentials --resource-group <rg> --name <cluster>

      - name: Deploy the tag
        run: |
          helm upgrade confident-ai \
            oci://ghcr.io/confident-ai/charts/confident-ai --version 0.1.0 \
            -n confident-ai -f values.yaml \
            --set image.tag=${GITHUB_REF_NAME} \
            --wait --timeout 15m

이미지 태그는 git 태그(GITHUB_REF_NAME)에서 오고, --wait는 롤아웃이 정상이 될 때까지 작업을 붙잡아 두어 잘못된 릴리스가 파이프라인을 실패시키게 해요. 러너가 저장된 kubeconfig가 아니라 클라우드의 OIDC 페더레이션으로 클러스터 접근을 얻게 하고, 애플리케이션 시크릿은 배포가 이미 쓰는 클라우드 시크릿 저장소에, 결코 저장소에 두지 마세요.

안전하게 승격하려면 태그 푸시를 먼저 스테이징에 대고, 프로덕션은 같은 태그를 배포하는 수동 승인(GitHub Environment) 뒤에 게이트해요.

옵션 B: GitOps 이미지 자동화

GitOps를 운영한다면 릴리스를 git에 선언하고 컨트롤러가 태그를 올리게 해요.

Argo CD

Argo CD Image Updater가 레지스트리를 보고 새 태그를 git 매니페스트에 써 주고, Argo CD가 변경을 동기화해요. Application에 어노테이션을 답니다:

metadata:
  annotations:
    argocd-image-updater.argoproj.io/image-list: confident=<registry>/confidentai/confident-backend
    argocd-image-updater.argoproj.io/confident.update-strategy: semver
    argocd-image-updater.argoproj.io/confident.allow-tags: regexp:^v\d+\.\d+\.\d+$
    argocd-image-updater.argoproj.io/confident.helm.image-tag: image.tag
    argocd-image-updater.argoproj.io/write-back-method: git

confident-backend는 모든 서비스가 태그를 공유하므로 전체 릴리스의 버전 참조예요. Image Updater는 레지스트리에 대한 pull과 list 접근이 필요하므로, 배포가 쓰는 것과 같은 자격 증명을 주세요.

Flux

Flux는 ImagePolicy로 태그를 스캔하고, ImageUpdateAutomation이 새 태그를 HelmRelease에 커밋해요:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: confident
spec:
  image: <registry>/confidentai/confident-backend
  interval: 5m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: confident
spec:
  imageRepositoryRef:
    name: confident
  policy:
    semver:
      range: ">=2.0.0"

HelmRelease에서 태그를 # {"$imagepolicy": "flux-system:confident:tag"} 주석으로 표시해서 자동화가 어디에 쓸지 알게 해요.

태그가 git에 들어가므로 모든 롤아웃은 검토할 수 있는 커밋이고, 롤백은 git revert예요.

옵션 C: 인클러스터 폴러

Keel이 레지스트리를 보고 워크로드를 직접 업데이트해요. 루프에 git이 없어요. 릴리스에 정책을 설정해서 원하는 태그만 추적하게 해요:

# in your Helm values, applied to the app workloads
podAnnotations:
  keel.sh/policy: patch          # patch | minor | major, or a semver range
  keel.sh/trigger: poll
  keel.sh/pollSchedule: "@every 5m"

이것은 세우기 가장 빠르고, 항상 최신 릴리스를 돌려야 하는 스테이징 클러스터에 잘 맞아요. 프로덕션에서는 변경이 기록되고 되돌릴 수 있는 옵션 A나 B를 선호해요.

가드레일

메커니즘은 쉬워요. 자동화된 롤아웃이 자동화된 장애가 되지 않게 하는 습관들이에요:

  • 고정하고, 정책을 제한하세요. 변경 가능한 태그에 떠다니지 마세요. 패치 릴리스(~> 2.0.x)는 낮은 리스크로 자동 업데이트되게 두고, 마이너·메이저 범프는 수동 승인 뒤로 미뤄요.
  • 모든 업그레이드에서 마이그레이션이 돌아요. 태그 올림이 데이터베이스 마이그레이션 작업을 실행해요. 프로덕션에서 미리 스냅샷을 떠두고, 항상 스테이징이 먼저 업데이트하게 해요.
  • 이중 배포가 아니라 승격하세요. 태그를 스테이징에 배포한 뒤 정확히 같은 태그를 프로덕션으로 승격해요. 두 환경이 변경 가능한 태그를 각자 독립적으로 풀게 두지 마세요.
  • 헬스가 롤아웃을 게이트하게 해요. chart의 readiness probe가 새 파드가 정상이 될 때까지 롤링 업데이트를 붙잡아 둬요. --wait(CI)나 동기화 헬스 체크(GitOps)를 켜 두어, 실패한 릴리스가 작동 중인 것을 대체하지 않고 멈추게 해요.
  • 롤백을 알아 두세요. helm rollback confident-ai로 이전 릴리스로 돌아가고, GitOps에서는 커밋을 되돌려요. 한 번 연습해서 몸에 익혀 두세요.
  • 자동화에 레지스트리 접근을 주세요. 새 태그를 보는 무엇이든 레지스트리에 list와 pull 접근이 필요하므로, 배포가 이미 가진 자격 증명을 재사용해요.

검증하기

스테이징 경로에 태그를 게시하고 그것이 반영되는 걸 지켜보세요:

kubectl rollout status deployment/confident-backend -n confident-ai
kubectl get pods -n confident-ai -o jsonpath='{.items[*].spec.containers[*].image}' | tr ' ' '\n' | sort -u

이미지 줄이 새 태그를 보여야 하고, 롤아웃이 성공을 보고해야 해요. Argo CD나 Flux에서는 태그가 git에 커밋됐는지, 애플리케이션이 Synced와 Healthy인지 확인해요.

다음 단계

Helm으로 배포하기

이 배포들이 기반으로 삼는 기본 설치예요.

재해 복구

프로덕션에서 마이그레이션을 자동화하기 전에 백업하세요.

더 알아보기