18. 관리 프로세스 (Admin Processes)

핵심 인사이트 (3줄 요약)

본질: 데이터베이스 마이그레이션, 비정상 데이터 보정 스크립트, REPL 셸 접속 등 일회성 관리(Admin) 프로세스를 일반 장기 실행 애플리케이션과 완전히 동일한 릴리스 환경(코드베이스, 설정, 도커 이미지)에서 실행하라는 12 팩터(Twelve-Factor) 원칙이다.

가치: 관리자가 임의의 환경이나 로컬 PC에서 스크립트를 실행하여 발생하는 예기치 못한 운영망 파괴(장애)를 원천 차단하고, 모든 관리 작업에 대한 감사(Audit)와 재현성을 보장한다.

융합: 지속적 배포(CD) 파이프라인의 배포 전 훅(Pre-sync Hook)이나 쿠버네티스의 잡(K8s Job) 컨트롤러와 융합되어 인프라 오케스트레이션의 자동화를 완성한다.

Ⅰ. 개요 및 필요성 (Context & Necessity)

소프트웨어 시스템을 운영하다 보면, 장기간 백그라운드에서 실행되는 웹 서버나 워커 프로세스 외에도 단발성(일회성)으로 실행해야 하는 '관리 프로세스(Admin Processes)'가 빈번하게 요구된다. 대표적으로 배포 시점의 데이터베이스 스키마 마이그레이션(DDL 반영), 장애 복구를 위한 특정 사용자 데이터의 일괄 보정(Patch 스크립트), 또는 시스템 상태 확인을 위한 인터랙티브 REPL 셸 접속 등이 있다.

전통적인 운영 환경에서는 시스템 관리자나 DBA가 자신의 로컬 PC에서 원격 DB에 직접 접속하여 쿼리를 날리거나, 운영 서버에 SSH로 접속해 알 수 없는 경로에 있는 스크립트를 수동으로 실행했다. 이러한 방식은 '코드베이스와 설정의 불일치'를 초래한다. 로컬 PC의 스크립트 버전이 운영 환경의 앱 버전과 맞지 않아 데이터 무결성이 깨지거나, 관리자의 실수(Human Error)가 시스템 전체 장애로 직결되는 심각한 리스크를 안고 있었다.

12 팩터 앱의 12번째 원칙은 이를 근본적으로 해결하기 위해 "일회성 관리 프로세스도 앱의 장기 실행 프로세스와 동일한 릴리스(Release)를 기반으로 실행되어야 한다"고 명시한다. 즉, 앱을 실행하는 것과 똑같은 컨테이너 이미지 안에서, 똑같은 환경변수를 주입받아 스크립트만 단발성으로 덮어씌워 실행하라는 의미이다.

아래 도식은 과거의 위험한 수동 관리 방식과 현대의 릴리스 일치형 관리 프로세스의 아키텍처적 차이를 보여준다.

이 도식은 관리 프로세스가 실행되는 환경의 일관성을 대조한다. 12 팩터 원칙은 스크립트조차 버전 통제 하에 묶어 두어 편류를 막는다.

[과거: 환경 불일치로 인한 장애 위험 (안티패턴)]
┌─ Admin PC ─────┐        ┌── Prod Server ──────────┐
│ v1.0 스크립트  │ ──SSH──> │ Web App (v2.0 실행 중)  │
│ (수동 실행)    │        │ DB (v2.0 스키마)        │
└────────────────┘        └─────────────────────────┘
  └─ 치명적 결과: v1.0 스크립트가 v2.0 DB 스키마를 덮어써서 장애 발생!

[현대: 12 Factor 기반 릴리스 일치형 관리 프로세스]
┌───────────────── Container Registry ───────────────────┐
│              [ Immutable Image v2.0 ]                │
└───────┬────────────────────────────────────┬─────────┘
        │ (동일한 이미지 배포)                 │ (동일한 이미지 기반 단발성 실행)
        ↓                                    ↓
┌── Prod Environment (K8s) ────────────────────────────┐
│ [ Deployment: Web App ]            [ Job: DB Mig. ]  │
│ - Entrypoint: start_web.sh         - Entrypoint:     │
│ - Env: Prod Config                   db_migrate.sh   │
└──────────────────────────────────────────────────────┘

이 흐름의 핵심은 '동일한 컨테이너 이미지(아티팩트)'와 '동일한 환경변수(Config)'를 사용한다는 점이다. 스크립트 파일은 개발자가 앱 코드를 작성할 때 같은 Git 리포지토리 내에 커밋되며, 배포 시점에 컨테이너 내부로 함께 패키징된다. 따라서 마이그레이션 스크립트를 실행할 때 앱 코드와의 버전 충돌이 일어날 확률은 0%로 수렴한다.

📢 섹션 요약 비유: 우주정거장을 고치는 우주비행사(관리 프로세스)가 지구에서 가져온 임의의 공구를 쓰는 것이 아니라, 우주선과 함께 발사된 표준 수리 키트와 동일한 산소탱크(환경)를 매고 작업해야만 치명적인 사고를 막을 수 있는 것과 같습니다.

Ⅱ. 아키텍처 및 핵심 원리 (Deep Dive)

관리 프로세스를 시스템에 안전하게 통합하기 위해서는, 이를 오케스트레이션(Orchestration) 도구와 배포 파이프라인의 생명주기(Lifecycle)에 맞물리게 설계해야 한다.

핵심 요소	역할	내부 동작 메커니즘	기술 스택 예시	비유
컨테이너 이미지	런타임 통일	웹 앱 코드와 관리 스크립트(Migrate, Console)를 하나의 이미지 레이어에 합쳐서 빌드	Docker, Buildpacks	종합 공구 상자
배포 오케스트레이터	일회성 작업 제어	실패 시 재시도, 완료 시 자원(Pod) 깔끔한 회수 및 실행 로그 보존	Kubernetes Job	일일 고용 작업반장
마이그레이션 도구	멱등성 보장 작업	코드 배포 전 DB 스키마 버전을 체크하고 델타(Delta) 쿼리만 안전하게 반영	Flyway, Liquibase	자동 톱니바퀴 조율기
주기적 스케줄러	반복 관리 작업	백업, 오래된 세션 삭제 등 정기적인 관리 작업을 동일 환경에서 크론(Cron)으로 실행	K8s CronJob, EventBridge	정기 순찰 타이머
엔트리포인트 오버라이드	실행 모드 분기	`docker run` 시 명령어를 `web`에서 `migrate`나 `bash`로 덮어씌워 실행	CMD / Entrypoint	리모컨 모드 스위치

아래의 상태 다이어그램은 CI/CD 파이프라인에서 신규 버전 배포 시, 일반 서비스(Web App)가 뜨기 전에 관리 프로세스(DB 마이그레이션)가 어떻게 선행 제어되는지를 보여준다.

이 도식은 무중단 배포의 안전성을 확보하기 위해, 마이그레이션(Admin Process)이 일반 프로세스(Web App)의 롤아웃을 블로킹(Blocking)하고 제어하는 생명주기를 나타낸다.

[ CD Pipeline: Deploy v2.0 ]
         │
         ↓
  (1) [Pre-Sync Hook] ──> ┌─ K8s Job (Admin Process) ────┐
      트리거 발생         │ Image: myapp:v2.0            │
                          │ CMD: "flyway migrate"        │
                          │ Env: Prod_DB_Config          │
                          └──────────┬───────────────────┘
                                     │ 
                           [Success] │ [Fail]
                  ┌──────────────────┴─────────────┐
                  ↓                                ↓
  (2) [Sync / Rollout]               [Rollback Pipeline]
      ┌─ K8s Deployment ──┐          관리 작업 실패로 인해
      │ Image: myapp:v2.0 │          Web App 배포는 중단되고
      │ CMD: "start web"  │          기존 v1.0 상태 유지
      └───────────────────┘

이 구조의 핵심은 **의존성 순서(Dependency Order)**와 **격리(Isolation)**다. 관리 스크립트가 실행되는 K8s Job은 웹 앱을 띄우는 Deployment와 완전히 동일한 환경(ConfigMap, Secret)을 공유받는다. 하지만 생명주기는 분리되어 있어, 스크립트가 무거운 CPU 연산을 일으켜도 서비스 중인 웹 파드의 자원을 빼앗지 않는다. 또한, 스크립트 실행이 실패하면 파이프라인 전체가 멈추어 불완전한 상태의 앱 코드가 배포되는 것을 막는 방파제(Gate) 역할을 수행한다.

실제로 도커(Docker) 명령어로 표현하면 12 팩터 원칙의 본질이 더욱 명확해진다.

# [실무 코드 스니펫] 동일 릴리스 기반의 실행 분기

# 1. 일반 웹 프로세스 실행 (Background)
docker run -d --env-file .env.prod myapp:v2.0 start_web

# 2. 동일 환경, 동일 이미지에서 DB 마이그레이션 (One-off)
docker run --rm --env-file .env.prod myapp:v2.0 run_db_migration

# 3. 동일 환경에서 트러블슈팅을 위한 REPL 콘솔 진입 (Interactive)
docker run -it --rm --env-file .env.prod myapp:v2.0 python console.py

앱 로직이 바뀌지 않았더라도 환경 파일(.env.prod)이 바뀌면 새로운 릴리스로 간주되며, 세 명령어 모두 예외 없이 그 새로운 릴리스를 기반으로 동작한다.

📢 섹션 요약 비유: 본진(웹 프로세스)이 전진하기 전에, 본진과 똑같은 전투 식량과 지도를 지닌 선발대(관리 프로세스)를 먼저 보내 지뢰(스키마 불일치)를 제거한 뒤 본진을 안전하게 입성시키는 군사 전술과 같습니다.

Ⅲ. 융합 비교 및 다각도 분석 (Comparison & Synergy)

관리 프로세스를 어떻게 실행하고 통제할 것인지에 대한 아키텍처적 선택지를 비교해보자.

비교 항목	SSH 직접 접속 스크립트 실행 (안티패턴)	원격 CI 파이프라인 내 실행	K8s Job / 워크로드 내장 실행 (12 Factor)
환경 일치성	매우 낮음 (로컬 환경 의존)	중간 (CI 서버 환경에 의존)	최상 (실제 런타임 이미지와 완전 동일)
네트워크 보안	취약 (인바운드 방화벽 오픈 필요)	취약 (CI가 Prod DB에 접근해야 함)	우수 (클러스터 내부 통신으로 제한)
감사(Audit) 및 로그	개인 터미널에만 남음 (유실됨)	파이프라인 로그에 보존	중앙 집중식 로그 스택(ELK)에 앱과 함께 보존
자원 격리성	프로덕션 서버의 자원(CPU/Mem) 탈취	독립적 실행	스케줄러가 남는 노드에 배치 (영향 최소화)
적용 권장	긴급 핫픽스 (지양해야 함)	제한된 레거시 환경	모든 클라우드 네이티브 MSA 표준

과거에는 CI/CD 서버(Jenkins 등) 내부에서 파이썬 스크립트나 마이그레이션 도구를 직접 실행하여 운영 DB에 쿼리를 쏘는 방식을 많이 썼다. 그러나 이는 CI 서버가 운영 DB의 비밀번호를 알아야 하고 망을 개방해야 하는 치명적 보안 취약점(Supply Chain Attack의 타겟)을 낳았다. K8s Job 방식은 스크립트 실행을 오직 "클러스터 내부"에서 단발성 파드를 띄워 해결하므로 제로 트러스트(Zero Trust) 보안 관점과 완벽히 융합된다.

아래 다이어그램은 권한 통제(RBAC) 관점에서의 시너지와 보안성을 보여준다.

┌─────────────── 외부 망 ───────────────┐     ┌───────────── 내부 클러스터 망 (K8s) ──────────────┐
│                                       │     │                                                   │
│ [Developer] ─(X SSH/DB 접속 불가)─    │     │  [ K8s Job (Admin) ]  ──> [ Prod Database ]   │
│      │                                │  => │      (SA: db-admin)         (내부 DNS 통신)   │
│      └──────(Git Push)──────┐         │     │                                                   │
└─────────────────────────────┼─────────┘     └───────────────────────────────────────────────────┘
                              ↓
                   [ GitOps (ArgoCD) ] 이 배포 선언(YAML)을 감지하여 K8s API로 Job만 생성함

이 구조에서는 인간 개발자가 프로덕션 데이터베이스나 서버에 직접 접근할 권한이 전혀 필요 없다. 오직 코드를 작성해 Git에 올리면, 인프라 자체가 관리 프로세스 파드를 띄우고 내부 서비스 계정(Service Account)을 통해 작업을 수행한 후 사멸한다. 이는 완벽한 직무 분리(Segregation of Duties)이자 완벽한 감사 추적(Audit Trail)을 제공한다.

📢 섹션 요약 비유: 은행 금고에 돈을 넣을 때, 직원이 직접 열쇠를 들고 들어가는 것(SSH)이 아니라 캡슐(컨테이너)에 돈을 담아 파이프(배포 파이프라인)로 보내면 내부 로봇(K8s Job)이 정해진 규칙대로만 처리하고 기록을 남기는 완벽한 무인 시스템과 같습니다.

Ⅳ. 실무 적용 및 기술사적 판단 (Strategy & Decision)

실무에서 Admin Process 원칙을 적용할 때 발생하는 마찰과 의사결정 시나리오는 다음과 같다.

긴급 장애 시 데이터 핫픽스(Hotfix)
- 상황: 결제 로직 버그로 특정 사용자 1,000명의 잔액이 마이너스가 됨. 당장 DB 값을 UPDATE 해야 하는데, 원격 접속이 막혀 있음.
- 판단: 직접 DB에 붙어 쿼리를 날리는 유혹(안티패턴)을 참아야 한다. 보정 로직을 담은 1회성 스크립트(예: fix_balance_bug.py)를 작성하여 코드로 커밋하고, 이를 일반적인 배포 파이프라인을 태워 K8s Job으로 띄우는 것이 정석이다. 다소 시간이 걸리더라도(10분 내외) 보정 내역이 코드 히스토리에 남고, 다른 부작용(Side Effect)을 로컬에서 미리 테스트해 볼 수 있어 2차 장애를 막는다.
메모리(RAM)를 대량으로 소모하는 배치 작업
- 상황: 매일 자정에 통계 데이터를 집계하는 일회성 스크립트가 있는데, 웹 애플리케이션 파드 안에서 쓰레드로 돌렸더니 OOM(Out Of Memory) 킬러에 의해 서비스 전체가 죽음.
- 판단: 관리 프로세스와 장기 실행 프로세스를 '동일한 이미지'로 묶으라는 것이지, '동일한 컴퓨팅 인스턴스'에서 돌리라는 뜻이 아니다. 코드는 같게 유지하되, 통계 작업은 별도의 K8s CronJob 객체로 분리 선언하여 자원 할당량(Requests/Limits)을 넉넉히 주고 격리된 노드에서 돌려야 한다.
마이그레이션 하위 호환성 위반
- 상황: 스크립트(Admin Process)가 테이블의 특정 컬럼을 삭제(Drop)했는데, 아직 구버전 파드(Web App)가 살아 있어서 에러가 폭주함.
- 판단: 마이그레이션 스크립트는 항상 **하위 호환성(Expand and Contract 패턴)**을 지켜야 한다. 한 번의 배포로 컬럼을 지우는 것이 아니라, 1단계: 새 컬럼 추가 → 2단계: 양쪽 쓰기 앱 배포 → 3단계: 기존 컬럼 삭제 스크립트 실행 등 파이프라인과 결합된 N단계 배포 전략을 수립해야 한다.

다음은 관리 프로세스 설계를 위한 기술적 점검 체크리스트이다.

[실무 도입 및 보안 체크리스트 의사결정 트리]

[일회성 스크립트/배치 실행 요구 접수]
   │
   ├─ Q1. 이 스크립트 파일이 Git 저장소(코드베이스)에 포함되어 있는가?
   │  ├─ No ──> [반려] 개발자 로컬 PC의 임의 스크립트 반입 금지
   │  └─ Yes ──> ↓
   │
   ├─ Q2. 스크립트 실행 시 운영 DB의 접속 정보가 소스코드에 하드코딩 되었는가?
   │  ├─ Yes ──> [반려] 12 Factor 'Config 분리' 위반. 환경변수/Vault 매핑 지시
   │  └─ No ───> ↓
   │
   └─ Q3. 실패 시 롤백(Rollback) 대책이 스크립트에 명시되어 있는가? (트랜잭션 묶음)
      ├─ No ──> [경고] Flyway 같은 멱등성 도구 활용 권고
      └─ Yes ──> [승인] K8s Job 매니페스트 생성 후 배포 파이프라인 연동

이 판단 기준은 운영망의 무결성을 지키는 최후의 보루다. 아무리 코드를 잘 짜도 관리자 권한을 가진 스크립트 하나가 전체 시스템을 삭제할 수 있기 때문에, 이 과정은 철저히 파이프라인에 의해 기계적으로 통제되어야 한다.

📢 섹션 요약 비유: 수술실에 들어갈 때 집도의가 개인적으로 가져온 메스를 쓰는 것을 금지하고, 반드시 병원에서 소독 절차를 마친 규격화된 수술 도구(버전 관리된 스크립트)만 사용하게 하여 감염(장애)을 막는 의료 프로토콜과 같습니다.

Ⅴ. 기대효과 및 결론 (Future & Standard)

12 팩터 앱의 마지막 원칙인 관리 프로세스의 동기화를 통해 조직은 개발과 운영의 경계를 허무는 최종 단계를 달성하게 된다.

정성적 / 정량적 효과	비즈니스 및 운영 관점의 이점 (ROI)
장애율 억제 (Change Failure Rate)	검증되지 않은 수동 스크립트 오작동으로 인한 '인적 장애(Human Error)' 99% 차단
운영 투명성 (Auditability)	누가, 언제, 어떤 코드로 DB 데이터를 조작했는지 Git 히스토리와 K8s 로그에 영구 박제됨
DR (재해 복구) 신속성	시스템 파괴 시, 백업된 DB와 최신 컨테이너 이미지만 띄우면 별도의 스크립트 세팅 없이 즉각 환경 복원 가능 (MTTR 급감)

미래의 클라우드 네이티브 운영 환경은 K8s Operator 패턴이나 GitOps 제어 루프를 통해 사람이 일회성 명령조차 내리지 않는 NoOps (인간 개입 제로) 단계로 진화하고 있다. 관리 프로세스 자체가 AI 기반의 이상 탐지(AIOps)와 결합되어, 문제가 생기면 시스템이 스스로 동일한 릴리스 기반의 복구 스크립트를 생성하고 컨테이너를 띄워 자가 치유(Self-Healing)를 수행하는 자율형 인프라 표준으로 나아갈 것이다.

📢 섹션 요약 비유: 관리 프로세스의 통일은, 건물을 짓는 일(웹 앱)뿐만 아니라 다 지은 후 간판을 달거나 청소하는 일(관리 작업)까지 모두 똑같이 철저한 도면(코드베이스)과 안전 장비(동일 환경) 아래서 통제되는 궁극의 감리 시스템을 완성하는 것입니다.

📌 관련 개념 맵 (Knowledge Graph)

12-Factor App (현대적인 SaaS, 마이크로서비스 아키텍처를 설계하기 위해 지켜야 할 12가지 베스트 프랙티스 선언문)
Kubernetes Job / CronJob (일정 시간이 지나면 종료되어야 하는 일회성 또는 주기적 워크로드를 관리하는 쿠버네티스 리소스)
Infrastructure as Code (IaC) (인프라와 배포 프로세스를 스크립트가 아닌 선언적 코드로 관리하여 멱등성을 보장하는 사상)
Flyway / Liquibase (데이터베이스 스키마와 데이터를 버전 관리하고, 앱 배포 생명주기에 맞춰 안전하게 마이그레이션을 자동화하는 도구)
GitOps (모든 인프라와 관리 작업의 단일 진실 공급원(SSOT)을 오직 Git으로 통일하고 에이전트를 통해 클러스터에 반영하는 사상)

👶 어린이를 위한 3줄 비유 설명

게임기(운영 환경)에서 게임(일반 앱)을 할 때와, 게임 업데이트 패치(관리 프로세스)를 할 때 다른 기계를 쓰면 데이터가 날아갈 수 있어요.
12 팩터 원칙은 게임을 할 때나 패치를 할 때 모두 똑같은 팩(컨테이너 이미지)과 똑같은 세이브 파일(환경 설정)을 쓰라고 가르쳐줘요.
그러면 관리자가 실수로 이상한 명령어를 입력해서 소중한 게임 캐릭터 데이터가 엉망진창이 되는 슬픈 일을 완벽하게 막을 수 있답니다.