Zero-Downtime Updates with JSON Configuration Management

Zero-downtime JSON configuration management means changing runtime behavior for new work without restarting the service or dropping traffic. For most applications, the safe pattern is: write the JSON file atomically, reload it into a temporary object, validate it completely, then swap one in-memory reference while keeping the last known good config if anything fails.

That approach works well for feature flags, routing rules, logging levels, rate limits, and other operational settings. It is much less suitable for secrets, startup-only dependencies, or settings that require expensive process reinitialization.

What "Zero Downtime" Actually Means

• The process stays up while configuration changes are applied.
• Bad config does not crash the service; it gets rejected and the old config keeps serving traffic.
• New requests use the new config only after a successful swap.
• In-flight requests or jobs typically finish on the config snapshot they started with.
• In a multi-instance deployment, convergence can be gradual without being user-visible downtime.

That last point matters. Zero downtime does not mean every pod or VM flips at the exact same millisecond. It means the service remains available while instances move safely to the new configuration.

Recommended Runtime Model

1. Writers create a complete new JSON file and replace the old file atomically.
2. Readers detect changes with a watcher, polling loop, or both.
3. The reload path parses and validates the full document before touching live state.
4. The application swaps a single immutable config reference.
5. Failed reloads are logged and ignored so the last valid config stays active.

A Safer Reload Loop in TypeScript/Node.js

This pattern keeps configuration reads centralized and only changes active behavior after a full parse and validation pass.

import { readFileSync, watch } from 'node:fs';
import { basename, dirname } from 'node:path';

type AppConfig = Readonly<{
  version: string;
  routing: { apiBaseUrl: string };
  logLevel: 'debug' | 'info' | 'warn' | 'error';
  featureFlags: Record<string, boolean>;
}>;

const configPath = '/etc/myapp/config.json';
const configDir = dirname(configPath);
const configName = basename(configPath);

let activeConfig: AppConfig;
let reloadTimer: NodeJS.Timeout | undefined;

function parseAndValidateConfig(raw: string): AppConfig {
  const parsed = JSON.parse(raw) as Partial<AppConfig>;

  if (!parsed.version || typeof parsed.version !== 'string') {
    throw new Error('version is required');
  }

  if (!parsed.routing || typeof parsed.routing.apiBaseUrl !== 'string') {
    throw new Error('routing.apiBaseUrl is required');
  }

  if (!['debug', 'info', 'warn', 'error'].includes(String(parsed.logLevel))) {
    throw new Error('invalid logLevel');
  }

  return Object.freeze({
    version: parsed.version,
    routing: { apiBaseUrl: parsed.routing.apiBaseUrl },
    logLevel: parsed.logLevel as AppConfig['logLevel'],
    featureFlags: parsed.featureFlags ?? {},
  });
}

function loadCandidateConfig(): AppConfig {
  return parseAndValidateConfig(readFileSync(configPath, 'utf8'));
}

export function getConfig(): AppConfig {
  return activeConfig;
}

function activateLatestConfig() {
  const candidate = loadCandidateConfig();
  activeConfig = candidate;
  console.info('Activated config version', candidate.version);
}

export function initConfig() {
  activeConfig = loadCandidateConfig();

  watch(configDir, (_eventType, filename) => {
    if (filename?.toString() !== configName) {
      return;
    }

    if (reloadTimer) {
      clearTimeout(reloadTimer);
    }

    reloadTimer = setTimeout(() => {
      try {
        activateLatestConfig();
      } catch (error) {
        console.error(
          'Rejected config update; continuing with last known good config',
          error
        );
      }
    }, 150);
  });
}

For long-running requests or jobs, capture a config snapshot at the start of the unit of work and keep using that snapshot until it completes. That avoids mid-request behavior changes that are hard to reason about.

import { renameSync, writeFileSync } from 'node:fs';

function writeConfigAtomically(path: string, nextConfig: unknown) {
  const tempPath = path + '.next';

  writeFileSync(tempPath, JSON.stringify(nextConfig, null, 2) + '\n', 'utf8');
  renameSync(tempPath, path);
}

Keep the temporary file in the same directory as the final file so the replace step stays on the same file system boundary.

Choosing How to Detect Changes

File watchers are best when you want low-latency updates on local disks. Current Node.js file system documentation still notes that fs.watch() is not fully consistent across platforms and can be unreliable on some network file systems. In practice, that means watcher-driven reloads are fast, but a low-frequency poll or hash check remains a sensible backstop in production.

Polling is usually the most predictable option on shared volumes, NFS/SMB mounts, and conservative VM deployments. The tradeoff is slower pickup time and steady background I/O.

Centralized configuration services are a better fit once multiple instances need coordinated rollout, version history, auditing, or explicit rollback APIs. At that point, JSON often becomes the payload format rather than the storage mechanism.

Containers and Kubernetes Caveats

Current Kubernetes ConfigMap documentation adds a few details that are easy to miss when JSON config is mounted into pods:

• Mounted ConfigMap volumes are refreshed in running pods, but not instantaneously.
• Your app still has to poll or watch the mounted files; a startup-only read will never see later changes.
• ConfigMaps exposed as environment variables do not update automatically and require a pod restart.
• A ConfigMap mounted with subPath does not receive live updates.

If you need near-immediate change propagation across many replicas, reading config via the platform API or a dedicated config service is usually more predictable than relying on file projection alone.

Validation, Rollback, and Observability

• Validate required keys, enum values, numeric ranges, URLs, and mutually exclusive options.
• Stamp each config with a version, checksum, or timestamp and surface it in logs and health output.
• Record reload success and failure metrics so "stale but serving" is visible before users notice.
• Keep previous versions available so rollback is a file swap or pointer change, not a rebuild.
• Apply config changes to new requests first unless a component explicitly supports live mutation.

What Not to Store in Plain JSON

• Secrets should live in a secret manager or secret-specific mount, not a general-purpose JSON file.
• Settings that require process reinitialization, such as some TLS assets or pool sizes, are not truly zero-downtime just because the file changed.
• Cross-service coordination data usually belongs in a configuration control plane, not in a shared JSON file on disk.

Common Failure Modes

• The writer truncates and rewrites the file in place, and readers parse partial JSON.
• The app watches the file path only, but the deploy process replaces the file via rename.
• Reload logic changes global objects in place instead of swapping one immutable config reference.
• A config change silently fails validation and nobody notices because there is no alerting.
• Teams expect env-var updates in containers to behave like file updates, but they do not.

Bottom Line

JSON files can support zero-downtime updates reliably when you combine atomic writes, full-document validation, immutable in-memory swaps, and explicit rollback and monitoring. That is enough for many single services and small clusters. Once you need coordinated cross-instance rollout, secrets-heavy configuration, or stronger audit guarantees, move from raw files to a configuration service or platform API.