Automated Switching to Maintenance Page in a Kubernetes-Based System

1. Background
While operating 000 000, both scheduled and unscheduled system maintenance are inevitable. During maintenance periods, there was a requirement to display a notification page to users.
Previously, the process relied solely on operators manually posting announcements whenever maintenance occurred. This approach carried a risk of human error.
To address this issue, we designed and implemented a feature that automates the entire process—from switching to the maintenance page to restoring the original state—triggered solely by registering a maintenance notice.

2. Overall Workflow
The entire process operates as follows:

① Register Maintenance Notice
When an administrator registers a system notice, they set the "Maintenance 여부" (Maintenance Flag) field to Y, along with the maintenance start and end times.
This data serves as the starting point for the automation.

② Scheduler Detection
A batch scheduler using Spring’s @Scheduled periodically queries the notice table and detects when the current time reaches the maintenance start time.

③ Retrieve Target Service Pod Information
Using the Kubernetes Java Client, the system retrieves the current Pod information of the target service.
This information is used as the basis for traffic routing.

④ Generate Temporary Maintenance Page
A static HTML maintenance page is dynamically generated based on the notice content (e.g., maintenance reason, expected completion time).

⑤ Build Docker Image and Push to ECR
The generated maintenance page is packaged using an Nginx-based Dockerfile.
A Docker image is built and pushed to AWS ECR (Elastic Container Registry).

⑥ Create Temporary Pod and Switch Traffic
A temporary maintenance Pod is created using the image stored in ECR.
Then, the Kubernetes Service selector is updated to route traffic from the existing service Pods to the temporary Pod.
Users accessing the service during this time will see the maintenance page.

⑦ End Maintenance and Automatic Rollback
When the scheduler detects that the maintenance end time has been reached, it restores the Service selector to the original Pod labels.
The temporary Pod and related resources are then deleted, and the ECR image is cleaned up.

3. Key Technical Implementation Points

Kubernetes Java Client Usage
To control Kubernetes resources from a Java application, we used the official Kubernetes Java Client library.
Through CoreV1Api, we were able to:
• Retrieve Pod lists
• Modify Service selectors
• Create and delete Pods programmatically

Dynamic Docker Image Build
Since the maintenance page content changes each time, we designed a structure where:
• Notice data is bound to a template to generate an HTML file
• The file is built together with an Nginx-based Dockerfile
Using Java’s ProcessBuilder, we executed Docker CLI commands and automated the entire workflow—from image build to ECR login and push.

Traffic Switching Strategy
Traffic switching was implemented by modifying the label selector of the Kubernetes Service.
By distinguishing labels between existing Pods and temporary Pods:
• Simply changing the selector enables seamless traffic switching
• No need to modify Ingress or proxy configurations
This approach is both simple and stable.

Safety Mechanism Design
Since this is an automated system, handling exceptional scenarios is critical.
We implemented:
• Rollback logic for each step to prevent impact on existing services in case of failure (e.g., image build failure)
• A timeout-based forced rollback mechanism to handle cases where restoration does not occur after the maintenance end time
• Logging of the entire process state in the database for monitoring by administrators

4. Conclusion
Through this implementation, we experienced that Kubernetes is not just a container orchestration tool—it can become a powerful infrastructure automation platform when combined with Java applications.
In particular, the ability to control infrastructure at the application level using the Kubernetes Java Client—without relying on separate scripts or CI/CD pipelines—was especially impressive.
We plan to continue expanding automation capabilities to further improve operational efficiency.

Undefined