> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/system-design/design-problems/technical-design/planned-maintenance-activity.md).

# 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:

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

2. 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.

{% hint style="success" %}
**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).
    {% endhint %}

{% hint style="success" %}
**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.
    {% endhint %}

**Example Istio Rule**

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

2. All API requests during the maintenance window are automatically routed to a **maintenance handler** or static page.
3. 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://www.pranaypourkar.co.in/the-programmers-guide/system-design/design-problems/technical-design/planned-maintenance-activity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.