배포 파이프라인 하나 만들려고 티켓을 몇 장 쓰시나요? GitLab·Argo CD·Jenkins를 한 번에 잇는 DevOps Code Foundry
새 서비스 하나를 만들기 위해 티켓을 몇 장이나 쓰고 있나요? 저장소 생성 요청, 브랜치 보호 설정, CI/CD 변수 등록, Argo CD Application 생성, Jenkins 잡 실행, 배포 상태 확인까지. 개발을 시작하기도 전에 여러 팀의 답변을 기다리는 일이 익숙해졌다면 문제는 개발자의 속도가 아닙니다.
진짜 병목은 서비스마다 반복되는 배포 파이프라인 준비 작업입니다. 사람이 매번 같은 설정을 옮겨 적으면 리드타임은 길어지고, 누락과 표준 편차가 쌓이며, 실패했을 때 어디까지 만들어졌는지도 알기 어려워집니다.
개발자가 셀프서비스 포털에 앱 이름·팀·템플릿을 입력하면 GitLab 프로젝트부터 GitOps 매니페스트, Jenkins 초기 실행까지 자동으로 프로비저닝하는 플랫폼입니다.
한 줄로 요약하면
devops-code-foundry는 단순한 배포 스크립트가 아닙니다. 플랫폼 팀의 반복 작업을 멱등한 워크플로우로 바꾸고, 개발팀이 기다리지 않고 표준 파이프라인을 만들게 하는 셀프서비스 DevOps 플랫폼입니다.
개발자 요청 ↓ 즉시 request_id 반환 FastAPI — 인증 · 검증 · 정책 적용 ↓ Argo Workflows — 상태 · 재시도 · 보상 제어 ↓ GitLab → Argo CD(GitOps) → Jenkins ↓ 대상 Kubernetes 클러스터에 애플리케이션 배포
왜 ‘자동화 스크립트’가 아니라 플랫폼인가?
스크립트는 실행한 사람에게만 편리할 수 있습니다. 플랫폼은 입력 규칙, 진행 상태, 실패 복구, 권한, 감사 기록까지 조직의 공통 방식으로 만듭니다. 이 프로젝트가 해결하려는 차이는 다음과 같습니다.
| 구분 | 수동 요청 방식 | Code Foundry |
|---|---|---|
| 시작 | 팀별 티켓과 메시지 | 포털 폼 한 번 |
| 표준 | 담당자 경험에 의존 | 템플릿과 정책으로 강제 |
| 실패 | 부분 생성 상태를 수동 조사 | 재시도 후 Saga 보상 |
| 추적 | 메일·메신저를 다시 검색 | 요청·단계별 상태와 감사 로그 |
요청 한 번이 실제 파이프라인이 되기까지
1. FastAPI가 인증·검증·정책을 맡는다
포털 로그인은 GitLab OAuth와 연결됩니다. 사용자가 폼을 제출하면 Backend는 앱 이름과 팀, 선택한 템플릿과 파라미터를 검증하고 요청 레코드를 만든 뒤 202 Accepted와 request_id를 즉시 반환합니다. 외부 시스템 처리가 수 분 걸려도 브라우저 요청을 붙잡아 두지 않습니다.
2. Argo Workflows가 오래 걸리는 일을 책임진다
워크플로우는 GitLab → Argo CD → Jenkins 단계를 순차 실행합니다. 이미 Kubernetes와 Argo CD를 운영하는 환경이라면 별도 메시지 큐나 새로운 워크플로우 엔진을 추가하지 않고도 상태 지속, 재시도, 실행 이력을 얻을 수 있다는 장점이 있습니다.
3. GitLab은 ‘저장소 생성’에서 끝나지 않는다
프로젝트 생성뿐 아니라 브랜치 보호, CI/CD 변수, Webhook, 멤버까지 표준값으로 맞춥니다. 모든 작업은 먼저 현재 상태를 조회하고, 없으면 만들고, 있으면 재사용하거나 갱신하는 방식입니다.
4. Argo CD Application은 Git에 커밋한다
Application을 API로 한 번 생성하고 잊는 대신 매니페스트를 GitOps 저장소에 커밋합니다. 배포 상태의 단일 진실 공급원이 Git에 남고, 사람이 클러스터에서 값을 바꿔도 Argo CD가 선언된 상태로 되돌립니다.
5. Jenkins가 첫 빌드와 배포를 시작한다
초기 파이프라인을 실행하고 완료 여부를 폴링합니다. 포털에서는 빌드를 직접 다시 실행하고 진행 로그를 이어 읽을 수 있어, 사용자가 Jenkins 화면을 찾아다니지 않아도 됩니다.
핵심은 ‘성공’보다 ‘다시 실행해도 안전함’이다
GitLab, GitOps 저장소, Jenkins는 하나의 데이터베이스 트랜잭션으로 묶을 수 없습니다. 두 번째 단계에서 실패하면 첫 번째 단계의 프로젝트만 남는 식의 orphan resource가 생깁니다. 이 프로젝트는 그 문제를 멱등성, retry-forward, Saga 보상 세 가지로 다룹니다.
멱등성: 조회한 뒤 생성하거나 갱신한다
- GitLab 프로젝트가 이미 있으면 재사용합니다.
- 브랜치 보호와 CI/CD 변수는 동일 규칙이면 건너뛰고, 달라졌을 때만 갱신합니다.
- Webhook은 URL, 멤버는 멤버십을 기준으로 중복을 막습니다.
- Jenkins 실행은 요청 식별자를 build parameter에 남겨 중복 실행을 막습니다.
재시도 우선: 네트워크 오류로 리소스를 지우지 않는다
각 단계는 지수 백오프로 최대 세 번 재시도합니다. 이미 성공한 앞 단계를 성급히 되돌리기보다 앞으로 진행하는 retry-forward가 기본입니다. 재시도 한계를 넘었을 때만 onExit 보상 단계로 전환합니다.
보상은 ‘무조건 삭제’가 아니다
각 단계가 만든 리소스 식별자를 external_ref로 남겨, 보상 시 무엇을 되돌릴지 판단합니다. GitOps 커밋은 revert할 수 있지만, 개발자가 이미 사용하기 시작했을 수 있는 GitLab 프로젝트는 기본적으로 삭제하지 않습니다. Jenkins 실행도 되돌리기보다 감사 로그를 남깁니다. 깨끗함보다 데이터 안전성을 우선한 보상 경계입니다.
템플릿 하나를 추가해도 포털을 다시 배포하지 않는다
앱 유형을 포털 코드에 하드코딩하지 않고 각 템플릿의 template.yml이 제목, 설명, 입력 변수를 선언합니다. 포털, API, 스캐폴드 단계가 같은 메타데이터를 공유하므로 새 템플릿 추가는 저장소 커밋 하나로 끝납니다.
| 템플릿 | 워크로드 | 주요 리소스 |
|---|---|---|
| Python | CronJob와 대시보드 | PVC, CronJob, Deployment, Service |
| Static | 정적 웹 서비스 | Deployment, Service, 선택적 Ingress |
| API | FastAPI HTTP 서비스 | Deployment, Service, probe 3종 |
운영 환경에서 진짜로 부딪힌 문제들
설계 문서보다 더 값진 것은 이관 과정에서 깨진 지점입니다. 실제 운영 환경으로 옮기며 다음과 같은 문제를 만났고 코드와 설정으로 보완했습니다.
- 네임스페이스가 달라져 데이터베이스와 Argo Server의 서비스 DNS가 맞지 않는 문제
- HTTP로 열린 내부 서비스에 HTTPS로 연결해 발생한 프로토콜 오류
- Kustomize가 WorkflowTemplate CRD 안의 이미지 경로를 찾지 못한 문제
- 관리 클러스터와 배포 대상 클러스터가 분리된 환경에서 시크릿이 잘못된 곳에 생성된 문제
- 빌드 이미지를
latest로만 푸시해 Argo CD가 변경을 감지하지 못한 문제
해결의 공통점은 “어디에서 실행되는가”를 명확히 하는 것이었습니다. 관리 클러스터에는 포털과 오케스트레이터를 두고, 실제 앱은 별도의 대상 클러스터에 배포합니다. 대상 클러스터 접근 권한도 필요한 리소스 범위로 제한합니다.
비밀은 파라미터와 Git 밖에 둔다
GitLab 토큰, Jenkins 자격증명, 애플리케이션 시크릿이 요청 파라미터나 Git 커밋에 섞이면 자동화가 곧 유출 경로가 됩니다. 앱 시크릿은 일반 요청 값과 분리해 전달하고 암호화 저장하며, 조회 API는 키 이름만 노출하도록 설계했습니다. 빌드 시 내부 인증 경로를 통해 필요한 값을 받아 대상 클러스터 Secret으로 주입합니다.
저장소에 평문 Kubernetes Secret을 남기지 말고 Sealed Secrets 또는 External Secrets와 Vault를 연결해야 합니다. 기본 토큰과 placeholder Webhook도 모두 환경별 보안 값으로 교체해야 합니다.
빠르게 구조를 확인하는 방법
# Step 실행기 이미지 빌드 docker build -t registry.example.com/platform/provisioner:latest . docker push registry.example.com/platform/provisioner:latest # Argo WorkflowTemplate 등록 kubectl apply -f argo/workflowtemplate.yaml # 테스트 요청 argo submit --from workflowtemplate/pipeline-provision -n argo \ -p request_id=$(uuidgen) \ -p app_name=payments-api \ -p team=billing \ -p template=python-fastapi
로컬에서는 환경 변수로 요청 정보와 외부 시스템 연결 정보를 넣고 python -m steps.gitlab처럼 단계별 실행도 가능합니다. 콜백 URL을 생략하면 결과를 로그로만 확인할 수 있어 각 Step의 멱등 로직을 독립적으로 테스트하기 좋습니다.
이 프로젝트가 만드는 변화
- 플랫폼 팀은 반복 티켓 처리 대신 정책과 템플릿 품질에 집중합니다.
- 개발자는 기다리지 않고 표준화된 저장소와 배포 파이프라인을 얻습니다.
- 실패한 요청은 지점과 원인이 기록되고, 안전하게 재시도할 수 있습니다.
- 새 앱 유형은 포털 수정 없이 템플릿 카탈로그로 확장됩니다.
- 누가 무엇을 언제 만들었는지 감사 가능한 기록이 남습니다.
조직의 표준과 실패 복구 전략을 코드로 감추고, 개발자가 서비스에 집중하게 만드는 제품입니다.
마치며
devops-code-foundry가 자동화하는 것은 GitLab 프로젝트 세팅이나 Jenkins 잡 하나가 아닙니다. 팀 사이에 흩어진 기다림, 구두 규칙, 복구 경험을 하나의 재현 가능한 흐름으로 바꾸는 일입니다.
티켓으로 전달하던 배포 노하우를, 누구나 안전하게 사용할 수 있는 셀프서비스 플랫폼으로. 그것이 이 프로젝트가 지향하는 Platform Engineering의 모습입니다.
프로젝트 저장소: github.com/dslee1371/devops-code-foundry
댓글
댓글 쓰기