blog

Kubernetes 기반 시스템 점검 페이지 자동 전환 구현

Nextree

07 4월 2026 • 5 min read

1. 배경

시스템 운영 중 정기·비정기 시스템 점검은 불가피하며, 점검 시간 동안 사용자에게 안내 페이지를 노출해야 하는 요구사항이 있었습니다. 기존 방식은 점검 때마다 운영자가 공지를 하는 것이 다였습니다. 이 과정에서 인적 오류(Human Error)의 위험이 있었습니다. 이를 해결하기 위해 공지사항 등록만으로 점검 페이지 전환부터 원복까지 전 과정을 자동화하는 기능을 설계하고 구현했습니다.

2. 전체 동작 흐름

전체 프로세스는 다음과 같이 동작합니다.

① 공지사항 등록 - 관리자가 시스템 공지사항을 등록할 때 "시스템 점검 여부" 필드를 Y로 설정하면서, 점검 시작 시간과 종료 시간이 함께 저장된다. 이 데이터가 전체 자동화의 시작점이 됩니다.

② 스케줄러 감지 - Spring의 @Scheduled를 활용한 배치 스케줄러가 주기적으로 공지사항 테이블을 조회하여, 현재 시각이 점검 시작 시간에 도달한 건을 감지합니다.

③ 대상 서비스 Pod 정보 조회 - Kubernetes Java Client를 통해 대상 서비스의 현재 Pod 정보를 조회합니다. 이 정보는 이후 트래픽 라우팅 전환의 기준이 됩니다.

④ 임시 점검 페이지 생성 - 공지사항에 등록된 점검 안내 내용(점검 사유, 예상 종료 시간 등)을 기반으로 정적 HTML 점검 페이지를 동적으로 생성합니다.

⑤ Docker 이미지 빌드 및 ECR 푸시 - 생성된 점검 페이지를 Nginx 기반 Dockerfile로 패키징한 뒤 Docker 이미지를 빌드하고, AWS ECR(Elastic Container Registry)에 push합니다.

⑥ 임시 Pod 생성 및 트래픽 전환 - ECR에 올린 이미지를 기반으로 임시 점검용 Pod를 생성합니다. 이후 Kubernetes Service의 selector를 변경하여, 기존 서비스 Pod로 향하던 트래픽을 임시 Pod로 라우팅합니다. 사용자는 해당 시간대에 접속하면 점검 안내 페이지를 보게 됩니다.

⑦ 점검 종료 및 자동 원복 - 스케줄러가 점검 종료 시간 도달을 감지하면, Service의 selector를 원래 Pod의 라벨로 복원합니다. 이후 임시 Pod와 관련 리소스를 삭제하고, ECR 이미지도 정리합니다.

3. 핵심 기술 구현 포인트

Kubernetes Java Client 활용

Java 애플리케이션에서 Kubernetes 리소스를 제어하기 위해 공식 Kubernetes Java Client 라이브러리를 사용했습니다. CoreV1Api를 통해 Pod 목록 조회, Service의 selector 수정, 새로운 Pod 생성과 삭제를 프로그래밍 방식으로 처리할 수 있었습니다.

동적 Docker 이미지 빌드

점검 페이지의 내용은 매번 달라지기 때문에, 공지사항 데이터를 템플릿에 바인딩하여 HTML 파일을 생성하고, 이를 Nginx 기반 Dockerfile과 함께 빌드하는 구조를 설계했습니다. Java의 ProcessBuilder를 활용하여 Docker CLI 명령을 실행하고, 빌드 완료 후 ECR 로그인 및 Push까지 일련의 과정을 자동화했습니다

트래픽 전환 전략

트래픽 전환은 Kubernetes Service의 label selector를 변경하는 방식을 택했습니다. 기존 Pod의 라벨과 임시 Pod의 라벨을 구분하여, selector만 교체하면 무중단으로 트래픽이 전환됩니다. Ingress나 별도의 프록시 설정을 변경할 필요가 없어 구현이 간결하면서도 안정적이었습니다.

안전장치 설계

자동화 시스템인 만큼 예외 상황에 대한 안전장치도 중요했습니다. 각 단계별 실패 시 롤백 로직을 구현하여, 이미지 빌드 실패 시 기존 서비스가 영향받지 않도록 했습니다. 또한 점검 종료 시간이 지났는데도 원복이 되지 않는 상황을 방지하기 위해 타임아웃 기반 강제 원복 메커니즘을 추가했고, 전 과정의 상태를 DB에 기록하여 관리자가 모니터링할 수 있도록 했습니다.

4. 마무리

이번 구현을 통해 Kubernetes가 단순히 컨테이너 오케스트레이션 도구가 아니라, Java 애플리케이션과 결합하면 강력한 인프라 자동화 플랫폼이 될 수 있다는 것을 경험했습니다. 특히 Kubernetes Java Client를 활용하면 별도의 스크립트나 CI/CD 파이프라인 없이도 애플리케이션 레벨에서 인프라를 제어할 수 있다는 점이 인상적이었습니다. 앞으로도 운영 효율화를 위한 자동화 영역을 지속적으로 확대해 나갈 계획입니다.

Undefined