콘텐츠로 이동

배포와 운영

권장 배포 방식

운영 환경은 mago-onprem-infra를 사용하는 중앙 GitOps 방식을 권장합니다. Skill Runtime 저장소는 애플리케이션 코드, Helm chart, 컨테이너 이미지 build와 배포 image tag를 담당하고, 인프라 저장소는 Argo CD Application과 환경별 values를 관리합니다.

배포 흐름은 다음과 같습니다.

  1. develop push 또는 수동 실행으로 CD (on-prem) workflow를 시작합니다.
  2. GitHub Actions가 이미지를 GAR에 <commit SHA 앞 12자리> tag로 push합니다.
  3. Workflow가 같은 서비스 저장소의 deploy/values-onprem-image.yaml을 갱신합니다.
  4. Argo CD에서 변경된 image tag와 manifest diff를 검토합니다.
  5. 관리자가 sohri-skill-runtime-onprem Application을 수동 Sync합니다.

이 구조는 애플리케이션과 운영 권한을 분리하고 변경 승인, 감사 및 rollback을 명확하게 유지합니다.

Docker Compose

프로젝트 루트에서 실행합니다. 외부 포트는 9213, 컨테이너 포트는 59213입니다.

docker compose up --build

Helm 환경 파일

  • deploy/values-dev.yaml: GKE 개발 환경
  • deploy/values-prd.yaml: GKE 운영 환경
  • deploy/values-onprem.yaml: on-premises Kubernetes

렌더링 검증:

helm lint deploy
helm template sohri-skill-runtime deploy -f deploy/values-dev.yaml
helm template sohri-skill-runtime deploy -f deploy/values-prd.yaml
helm template sohri-skill-runtime deploy -f deploy/values-onprem.yaml
helm template sohri-skill-runtime deploy \
  -f deploy/values-onprem.yaml \
  -f deploy/values-onprem-image.yaml

직접 설치는 개발 또는 긴급 복구에만 사용합니다. 운영 배포는 Argo CD를 통합니다.

helm upgrade --install sohri-skill-runtime deploy \
  --namespace mago-prod \
  --create-namespace \
  -f deploy/values-onprem.yaml

CI/CD

GitHub Actions

  • .github/workflows/ci.yml: Python, test, Helm, Docker, secret scan
  • .github/workflows/cd.yml: 수동 GKE fallback 배포
  • .github/workflows/onprem-cd.yml: develop push 시 GAR 이미지 및 서비스 리포 tag 갱신

On-premises 사전 준비

Skill Runtime GitHub 저장소에서 다음 Secret을 사용할 수 있어야 합니다.

  • GCP_ARTIFACT_REGISTRY_WRITER_KEY: GAR image push 권한을 가진 GCP credential

Organization Secret을 사용한다면 각 Secret의 repository access에 holamago/sohri-skill-runtime을 추가합니다. Secret 값을 소스 코드, Helm values, workflow log에 기록하면 안 됩니다.

Kubernetes mago-prod namespace에는 GAR pull Secret이 필요합니다.

kubectl -n mago-prod get secret gcp-artifact-registry

GitOps 저장소에는 다음 구성이 필요합니다.

gitops/apps/sohri-skill-runtime-onprem.yaml
gitops/apps/values/sohri-skill-runtime-onprem/overrides.yaml
gitops/projects/mago-prod.yaml

mago-prod AppProject의 sourceRepos에는 다음 저장소가 허용되어야 합니다.

https://github.com/holamago/sohri-skill-runtime.git

Application은 Skill Runtime의 deploy chart와 인프라 저장소 values를 함께 참조합니다. 초기 on-premises rollout은 1 replica, HPA/PDB 비활성으로 시작하고 부하와 노드 구성을 확인한 후 확장하는 것을 권장합니다.

On-premises 배포 절차

  1. Skill Runtime 변경을 develop에 merge하고 CD (on-prem) workflow를 실행합니다.
  2. Workflow가 deploy/values-onprem-image.yaml을 갱신했는지 확인합니다.
  3. 인프라 저장소의 Application, AppProject, values 변경을 main에 merge합니다.
  4. Argo CD에서 mago-projects, mago-root를 차례로 Refresh하고 수동 Sync합니다.
  5. GAR에 다음 형식의 image tag가 생성되었는지 확인합니다.
asia-northeast3-docker.pkg.dev/mago-services/mago/sohri-skill-runtime:<SHA12>
  1. Workflow가 아래 서비스 저장소 파일을 갱신했는지 확인합니다.
deploy/values-onprem-image.yaml
  1. Argo CD에서 sohri-skill-runtime-onprem을 Hard Refresh합니다.
  2. image tag와 Kubernetes manifest diff를 확인한 후 수동 Sync합니다.
  3. rollout과 API 상태를 확인합니다.
kubectl -n mago-prod rollout status deployment/sohri-skill-runtime
kubectl -n mago-prod get pod,service | grep sohri-skill-runtime
kubectl -n mago-prod port-forward service/sohri-skill-runtime 59213:59213

다른 터미널에서:

curl --fail http://127.0.0.1:59213/health/live
curl --fail http://127.0.0.1:59213/health/ready

장애 확인

  • GAR 인증 실패: GCP_ARTIFACT_REGISTRY_WRITER_KEY의 repository access와 Artifact Registry Writer 권한을 확인합니다.
  • Image tag push 실패: workflow의 contents: write 권한과 서비스 저장소의 branch protection 정책을 확인합니다.
  • Argo CD에 Application이 없음: mago-root를 Refresh하고 인프라 저장소의 Application manifest가 main에 있는지 확인합니다.
  • ComparisonError: AppProject source repository 허용 목록과 Application의 targetRevision, values 경로를 확인합니다.
  • ImagePullBackOff: gcp-artifact-registry Secret과 image tag 존재 여부를 확인합니다.
  • readiness 실패: Pod log와 /health/ready 응답을 확인합니다.

구성 소유권

서비스 저장소는 chart와 image tag를, mago-onprem-infra는 AppProject, Application과 클러스터별 override를 관리합니다. Argo CD는 두 저장소를 함께 렌더링하며 최종 배포는 항상 관리자가 수동 Sync합니다.

GitHub Actions에서 직접 helm upgrade를 실행하는 방식은 온프레미스 클러스터에 접근 가능한 self-hosted runner와 Kubernetes credential이 필요합니다. 운영 credential이 CI runner에 집중되므로 기본 배포 방식으로 권장하지 않습니다.

GKE fallback

GKE fallback repository variable:

  • AR_REPOSITORY_URL
  • GCP_WORKLOAD_IDENTITY_PROVIDER
  • GCP_DEPLOYER_SERVICE_ACCOUNT

Cloud Build

cloudbuild.yaml은 Graph Builder와 같은 이미지 build/push 및 환경 values tag bump 계약을 사용합니다. 인프라 trigger에서 다음 substitution을 주입해야 합니다.

  • _AR_REPOSITORY_URL
  • _IMAGE_NAME=sohri-skill-runtime
  • _VALUES_FILE
  • _ENV_NAME
  • _GITHUB_REPO_SLUG=holamago/sohri-skill-runtime
  • _GITHUB_PUSH_TOKEN_SECRET_VERSION

Probe

  • /health/live: 프로세스가 요청을 처리할 수 있는지 확인
  • /health/ready: Skill Engine 주소 설정 상태 확인

운영 권장값

  • timeout: 5~10초
  • replica: 최소 2개
  • 로그에 요청 body를 남기지 않기

실행 POST는 부작용 중복을 방지하기 위해 Runtime에서 재시도하거나 캐시하지 않습니다.