Planned Maintenance Activity

Problem Statement

In mobile applications backed by microservices, there are scenarios where planned maintenance is required on backend systems. The challenge is to prevent users from accessing services during maintenance windows while:

1. Minimizing disruption to existing active sessions.

2. Providing clear feedback to mobile users about maintenance timing.

3. Ensuring consistent behavior across all backend services accessed through a gateway.

Without a proper mechanism, users may experience failed requests, inconsistent responses, or partial functionality, leading to poor user experience.

Assumptions

• Mobile apps communicate with backend APIs via Spring REST APIs.

• A gateway (API Gateway) routes all mobile requests to respective backend services and will remain up during the maintenance window.

• Maintenance windows are scheduled in advance and communicated through a configuration service or static page.

• Existing sessions may still be active when maintenance begins.

Solution 1 - API-Level Maintenance Check

Flow

1. Mobile app calls a pre-login API to check if maintenance is enabled:

{
  "isMaintenance": true,
  "message": "System maintenance ongoing",
  "fromTime": "2025-10-01T00:00:00Z",
  "toTime": "2025-10-01T02:00:00Z"
}

1. Mobile app uses the response to:

   • Show a maintenance screen before login.

   • Optionally disable certain features.

   • Warn the user about the upcoming maintenance window.

Advantages

• Simple to implement at the backend API level.

• Mobile apps can gracefully handle maintenance.

• Flexible: supports messages, start/end time, optional features.

Disadvantages / Limitations

• Existing sessions already authenticated may still send requests to backend APIs and get errors.

• Requires every mobile request to optionally handle maintenance logic.

Solution 2 - Traffic Redirection via Gateway (Istio or Nginx)

Flow

1. Configure gateway or service mesh (Istio) rules to redirect traffic to a maintenance service or static page during the maintenance window.

Istio

• Istio is a service mesh for microservices that runs alongside your services in Kubernetes. It provides traffic management, security, and observability without requiring changes to application code.

• Relevance for Maintenance

  • Istio can intercept and route HTTP requests at the ingress or service-to-service level.

  • During maintenance windows, Istio rules can redirect traffic from backend services to a maintenance handler or static page.

  • Supports fine-grained routing (specific APIs, paths, or services).

Nginx

• Nginx is a widely used web server and reverse proxy. In microservices, it often serves as an API gateway or ingress controller.

• Relevance for Maintenance

  • Nginx can redirect or serve a static maintenance page during planned downtime.

  • It handles existing connections gracefully without involving backend services.

  • Provides high performance and minimal configuration overhead.

Example Istio Rule

istio:
  enabled: true
  customHttpRoutes:
    edge:
      - match:
          - uri:
              exact: /api/
          - uri:
              exact: /auth/
        route:
          - destination:
              host: custom-maintenance-service
              port:
                number: 8080

1. All API requests during the maintenance window are automatically routed to a maintenance handler or static page.

2. Backend services remain unaffected, and users receive a uniform maintenance response.

Advantages:

• Handles existing sessions automatically, no changes needed in mobile apps.

• Centralized: rules are applied at the gateway level, not per service.

• Can be extended for partial maintenance (specific APIs only).

Disadvantages / Considerations:

• Slightly more complex to configure in Istio/Nginx.

• Requires careful testing to avoid accidentally blocking non-maintenance traffic.

• Maintenance messages may need to be dynamic if static pages are used.

Best Practices

1. Combine both solutions for a robust approach:

   • API-level check for pre-login mobile experience.

   • Gateway-level redirect for active sessions during maintenance.

2. Configuration Management:

   • Centralized maintenance config in a service or ConfigMap.

   • Dynamic updates without redeploying gateways or apps.

3. User Experience:

   • Always provide fromTime / toTime in API responses.

   • Show clear maintenance screens in mobile apps.

   • Log redirected requests for monitoring and auditing.

4. Testing:

   • Test with active mobile sessions to ensure graceful handling.

   • Simulate gateway rules to confirm redirection works under load.