[2화] 파이썬 배포 자동화: 파이썬 코드 구조와 아키텍처

[2화] 파이썬 배포 자동화: 파이썬 코드 구조와 아키텍처

[2화] 파이썬 배포 자동화: 파이썬 코드 구조와 아키텍처

이전 포스팅에서는 파이썬 스크립트로 배포 자동화 환경을 구축하는 전체 흐름을 정리했습니다. 배포 자동화가 왜 필요한지와 함께, 실제 배포가 어떤 단계로 진행되는지도 큰 그림으로 살펴봤고요.
이번 글에서는 그 내용을 바탕으로, 코드를 어떤 구조로 나누고 어떻게 연결하면 관리하기 쉬운지 정리해보겠습니다. 단계별로 모듈을 어떻게 분리할지, 각 모듈이 맡아야 할 역할과 경계도 함께 이야기해보려 합니다.

 

[1화] 파이썬 배포 자동화: 전체 프로세스(내부/외부 형상 기반)

[2화] 파이썬 배포 자동화: 파이썬 코드 구조와 아키텍처

[3화] 파이썬 배포 자동화: Config 설계 & 로더 구현(스키마/검증/기본값/환경변수) 

[4화] 파이썬 배포 자동화: 코어 파이프라인 구현(RepoSync → Select → Copy → Report) (추후 링크 업데이트)

[5화] 파이썬 배포 자동화: CLI/로그/리포트/에러처리 및 마무리 (추후 링크 업데이트)

 

1. 관련 기능 정리

배포 자동화 단계를 다음 4단계 컨셉으로 정했습니다.

1. 배포 대상 파일 선별

2. 내부 형상 최신화

3. 외부 형상 최신화

4. 배포 대상 파일 복사 및 배포

 

이 부분을 프로그래밍 관점에서 두 가지 관점에서 접근을 하였습니다. 설정과 코어 기능으로 분리해봤습니다.

카테고리	세부 항목	비고
설정	인증 파일 리스트 로드	프로젝트/환경에 따라 바뀌는 값(인증정보, 대상 파일 정의)
코어 기능	형상 최신화 파일 복사	어떤 프로젝트든 동일하게 동작해야 하는 로직(RepoSync, Copy)
유틸리티	파일 리스트 생성 로그 생성 경로/패턴 처리	공통 헬퍼(파일 리스트/로그/패턴/경로)

표 1. 설정과 코어, 유틸리티 기능 분리

• 로드(load): 설정에 정의된 파일 목록(또는 파일 목록 파일)을 “읽어오는” 행위
• 생성(build): 외부 형상/패턴 규칙을 이용해 배포 대상 목록을 “계산/가공하는” 행위

 

위에서 설정 카테고리에서는 전체적인 툴에 대한 설정 및 인증, 그리고 파일 리스트 관리 부분이 될 것입니다.

그리고 코어 기능에서는 형상 최신화와 파일 복사 부분이 될 것입니다. 여기에서 저는 추가로 유틸리티 부분을 하나 추가할 예정입니다. 전체적인 툴 구성에 필요한 헬퍼 및 파일 리스트를 생성하는 기능에 대해서 포함할 예정입니다.

 

이와 같은 큰 구조로 접근을 할 예정입니다.

 

2. 설계 원칙

배포 자동화는 한 번 만들고 끝나는 스크립트가 아니라, 프로젝트가 바뀌거나 배포 정책이 바뀔 때마다 지속적으로 손봐야 하는 도구입니다. 그래서 이번 구조에서는 “동작한다”보다 “유지보수가 쉽다”를 우선순위로 두었습니다.

• 단일 책임(SRP): 파일 선별, Git 동기화, 복사/배포, 리포트를 각각 분리합니다.
• I/O 분리: git 명령 실행, 파일 복사 같은 외부 의존은 한 곳에 모으고(core는 정책/흐름을 다룹니다).
• 설정과 로직 분리: 프로젝트마다 바뀌는 값(경로/브랜치/패턴/옵션)은 config로 내리고, 실행 로직은 재사용 가능한 형태로 둡니다.
• 실패 지점 명확화: auth/sync/deploy 단계별로 실패 가능성이 있으므로, 로그와 리포트가 “어느 단계에서 실패했는지”를 남기도록 합니다.

 

3. 파일 구조 잡기

위에서 관련 기능에 대해서 선별을 하였고, 이 부분으로 다음과 같이 접근을 해볼까 합니다.

그림 1. 전체 레이어 구조도

 

main은 오케스트레이션(흐름 제어)만 담당하고, 실제 동작은 Config/Core/Util 모듈이 맡습니다. 그림 1을 바탕으로 다음과 같은 구조를 생성해보겠습니다.

Category	파일 구성	기능설명
Main	main.py	오케스트레이션
Config	auth_git.py	Git 인증
	load_config.py	설정 로드
Core	sync_repo.py	형상 최신화 (외부/내부)
	deployer.py	배포 파일 복사
Util	build_file_list.py	파일 리스트 가공/생성
	log.py	로그 파일 생성
	util_basic.py	경로/패턴처리 등 기본 유틸

표 2. 배포 자동화 도구의 모듈(파일) 구성과 각 역할(설정/코어/유틸 분리 기준)

 

위와 같은 형태로 파일을 구성을 잡아볼까 합니다. 위의 부분을 바탕으로 다시 한번 구성도를 만들어봤습니다.

 

그림 2. 레이어 구조에 따른 파일 구성도

물론, 파일 구조에 대해서는 다음과 같은 형태로 구성을 했습니다. 실제 구현에서도 비슷하게 가져가겠지만, 경우에 따라서는 추가로 파일이 필요할 수 있습니다.

 

위의 표와 그림에서 혼선이 있을 수 있는 부분이 바로 auth_git.py의 역할입니다. 이 부분은 자격증명 즉, 토큰과 계정에 대한 준비 작업만 진행할 것입니다. Git에 대한 명령 실행은 sync_repo.py에 담당합니다.

 

main은 오케스트레이션(흐름 제어)을 담당합니다. 오케스트레이션이라는 용어가 다소 생소할 수 있습니다. 오케스트레이션이란, 여러 모듈, 함수를 어떤 순서로 어떤 조건으로 어떻게 연결해서 실행을 조율하는 역할입니다.

 

4. 폴더 구조 잡기

위의 단계에서는 각 파일의 역할에 대해서 명시하였습니다. 위에서 언급한 파일들을 하나의 폴더에 나열할 수도 있지만, 향후 유지 보수를 위해서 별도의 폴더로 분리하는 것이 유리합니다. 그래서 다음과 같은 형태로 폴더를 분리했습니다.

그림 3. 폴더 구조

 

여기에서 대부분은 앞에서 파일 구조에 대해서 명시하면서 나열했던 이름입니다. 하지만, out이라는 별도의 폴더가 한 개 더 추가된 것을 알 수 있습니다. 이 부분은 바로 로그에 대해서 출력한 부분을 저장하기 위한 공간입니다. 물론, 이러한 부분들에 대해서 설정 부분을 통해서 변경 및 추가 생성이 가능할 것입니다.

 

5. 입력과 출력 정의

이 도구를 재현 가능하게 만들기 위해 입력과 출력을 명확히 정의합니다.

• 입력(Input)
  • config.json: 내부/외부 형상 경로, 브랜치, 파일 선별 규칙(include/exclude), build_file_list 사용 여부, 로그/리포트 경로 등
  • 내부 형상 Repo: 실제 배포 대상 파일이 존재하는 소스
  • 외부 형상 Repo: 배포 결과가 반영되는 대상 저장소
• 출력(Output)
  • out/logs/: 단계별 실행 로그(성공/실패/원인)
  • out/reports/: 결과 요약(SAME/MODIFIED/ONLY_*, 소요시간, 실패 목록, 산출물 경로)
  • 외부 형상 Repo의 변경사항(필요 시 커밋까지)

 

6. 오케스트레이션(main.py)

앞서서 main.py의 역할은 오케스트레이션이라고 이야기를 했습니다. 이 부분에 대해서 명시해보고자 합니다. Plant UML을 활용하여 이 부분을 표현해보고자 합니다. 

@startuml
title Orchestration Activity
start
:load config;
:auth;
:sync internal;
:sync external;
if (build file list?) then (yes)
  :build file list;
else (no)
  :use predefined list or empty;
endif
:deploy copy;
:report;
stop
@enduml

 

그림 4. Plant UML로 작성한 오케스트레이션

 

load config

config.json 파일을 설정 관련된 파일로 사용할 것입니다. 이 파일에 명시된 파일들을 읽어와서 내부에서 사용하는 설정 관련 class에 저장할 것입니다.

 

auth

load config에서 읽어온 token 및 계정정보를 바탕으로 git 명령 실행을 위한 자격증명(토큰/계정)을 준비합니다.

 

sync internal

내부 형상에 대해서 최신화를 할 예정입니다.

 

sync external

외부 형상에 대해서 최신화를 할 예정입니다.

 

build file list

옵션에 따라서 true일 경우에 외부 형상에 있는 정보를 바탕으로 파일 리스트를 생성할 것입니다. 만약 false 일경우에는 설정에 저장된 파일 리스트에 대한 파일 경로에 따라서 읽어올 것입니다.

 

deploy copy

앞선 build file list에서 생성 또는 불러온 파일 리스트에 대한 파일을 바탕으로 내부 형상에서 외부 형상으로 파일을 복사합니다.

 

report

실행 결과 요약(SAME/MODIFIED/ONLY_*, 소요시간, 실패 목록, 산출물 경로)합니다. report는 out/reports/에 요약 파일로 저장하고, 콘솔에는 핵심 요약만 출력합니다.

 

7. 실패 케이스와 리포트의 역할

실제 운영 환경에서는 인증 실패(토큰 만료/권한), 동기화 실패(브랜치 불일치/로컬 변경), 복사 실패(경로 오류/권한/잠금) 같은 문제가 자주 발생합니다. 그래서 main 오케스트레이션은 “성공/실패 여부”만 내는 것이 아니라, 어느 단계에서 실패했는지와 영향 범위를 남겨 재실행 판단이 가능해야 합니다. 이 목적을 위해 로그는 과정 중심으로 남기고, report는 결과 중심(SAME/MODIFIED/ONLY_*, 소요시간, 실패 목록, 산출물 위치)으로 남기도록 역할을 분리했습니다.

단계	실패 시나리오	증상(겉으로 보이는 현상)	로그/리포트에 남길 정보
load config	config 파일 없음/경로 오류	시작 즉시 종료, 파일 못 찾음	config_path, cwd, error_type
load config	JSON 파싱 실패	“JSON decode error”	line/column, raw snippet(일부)
load config	필수 키 누락	validate 실패	missing_keys, default_applied
auth	토큰 만료/권한 부족	git 명령 실패(401/403 등)	auth_mode, user, remote_url(마스킹)
auth	프록시/네트워크 문제	인증 단계에서 timeout	timeout_sec, proxy, retry_count
sync internal	로컬 변경사항 존재	pull/checkout 실패, 충돌	repo_path, branch, dirty_files
sync internal	브랜치/리모트 불일치	“branch not found”	remote, branch, refs
sync external	외부 형상 최신화 실패	fetch/pull 실패	repo_path, branch, last_commit
build file list	include/exclude 규칙 오류	배포 파일 0개 또는 과다	include/exclude, matched_count
build file list	외부 형상 기준 정보 누락	특정 폴더/파일이 목록에서 빠짐	external_commit, scan_root
deploy copy	소스 파일 누락	copy 실패, “not found”	src_path, expected_src
deploy copy	권한/잠금 문제	PermissionError, 파일 잠김	dst_path, exception
deploy copy	overwrite 정책 충돌	덮어쓰기 불가/백업 실패	overwrite, backup_enabled
report	리포트 생성 실패	out/reports에 파일 없음	report_dir, write_error
전체	중간 실패 후 재실행 판단 어려움	“어디까지 됐지?”	run_id, step, elapsed

표 3. 오케스트레이션 단계별 예상 실패 케이스와 로그/리포트에 남길 핵심 정보

 

다음 3화에서는 [3화] 파이썬 배포 자동화: Config 설계 & 로더 구현을 다루며, config.json 스키마 설계부터 검증/기본값 처리, 환경변수 치환까지 구현해보겠습니다.
이어서 4화에서는 *[4화] 파이썬 배포 자동화: 코어 파이프라인 구현(RepoSync → Select → Copy → Report)*을 통해 sync_repo → (build_file_list) → deployer → report 흐름을 end-to-end로 연결해 실제 동작을 완성하겠습니다.

 

[1화] 파이썬 배포 자동화: 전체 프로세스(내부/외부 형상 기반)

 

[3화] 파이썬 배포 자동화: Config 설계 & 로더 구현(스키마/검증/기본값/환경변수)