Blue-Green Deployment with JSON Configuration Switching

What is Blue-Green Deployment?

Blue-Green deployment is a release strategy where you run two identical production environments, let's call them "Blue" and "Green". At any given time, only one of the environments is live, serving all production traffic (e.g., the "Blue" environment).

When you deploy a new version of your application, you deploy it to the inactive environment (the "Green" environment). This new version includes your latest code changes, dependency updates, and potentially database schema changes. Crucially, the old version (on Blue) remains running and serving traffic while the new version (on Green) is deployed and tested.

Once you are confident that the new version on the Green environment is stable and ready, you switch the traffic router (often a load balancer, DNS, or API gateway) to direct all incoming requests to the Green environment instead of the Blue environment. The Green environment is now live.

The old Blue environment is kept running for a period. This allows for a fast rollback if any issues are discovered in the Green environment — you simply switch traffic back to Blue. If Green remains stable, the Blue environment can eventually be shut down or repurposed for the next deployment cycle.

The Role of Configuration

Applications often rely heavily on configuration settings — database connection strings, API keys, feature flags, service endpoints, logging levels, and more. These settings frequently differ between development, staging, and production environments. More importantly for Blue-Green, they might need to differ slightly *between the Blue and Green production environments themselves* during the transition period, or the *new version* might expect a slightly different configuration structure or values than the old one.

Simply deploying the new code isn't enough; you also need to ensure the application running in the newly active environment picks up the correct configuration for *its* version and the *current* state of the world (e.g., pointing to the correct database replica, using the correct API endpoint for the new feature).

JSON Configuration Switching Explained

Using JSON files for configuration and switching between them provides a simple, readable, and version-controllable method within a Blue-Green strategy. The core idea is:

1. Maintain separate JSON configuration files for each environment, and potentially for each *version* or *state* within an environment.
2. Have a simple mechanism that tells the running application *which* JSON configuration file to load and use.
3. During a Blue-Green switch, update this mechanism to point to the configuration file intended for the newly active environment and application version.

Example File Structure:

/app
├── src
│   └── ... application code ...
├── config
│   ├── config.blue.v1.json      // Config for Blue environment, version 1
│   ├── config.green.v1.json     // Config for Green environment, version 1
│   ├── config.blue.v2.json      // Config for Blue environment, version 2
│   ├── config.green.v2.json     // Config for Green environment, version 2
│   └── active-config.json       // A symbolic link or pointer file
└── package.json
└── ...

In this setup, active-config.json isn't a real file, but rather a symbolic link (symlink) that points to the currently active configuration file (e.g., pointing to config.blue.v1.json when Blue v1 is live). Alternatively, active-config.json could be a tiny JSON file containing just the *name* of the current active config file (e.g., { "active": "config.blue.v1.json" }), or this "active" pointer could live in an environment variable or a simple text file.

Example JSON Configuration Files:

{
  "environment": "blue",
  "version": "1.0",
  "databaseUrl": "jdbc://blue-db-v1/prod",
  "featureFlags": {
    "newFeatureEnabled": false
  },
  "apiEndpoint": "https://api.example.com/v1"
}

{
  "environment": "green",
  "version": "2.0",
  "databaseUrl": "jdbc://green-db-v2/prod", // Might point to a potentially different DB or schema version
  "featureFlags": {
    "newFeatureEnabled": true // New feature enabled in v2
  },
  "apiEndpoint": "https://api.example.com/v2" // New API version
}

Application Code Reads Active Config:

The application code is written to load configuration from the *active* source, not from a hardcoded file name.

import fs from 'fs';
import path from 'path';

let activeConfig = null;

function loadActiveConfig() {
  const configDir = path.join(__dirname, 'config');
  // Example using symlink: Read the target of the symlink
  const activeConfigFile = fs.readlinkSync(path.join(configDir, 'active-config.json'));
  const configPath = path.join(configDir, activeConfigFile);

  const configData = fs.readFileSync(configPath, 'utf8');
  activeConfig = JSON.parse(configData);
  console.log(`Loaded configuration for ${activeConfig.environment} v${activeConfig.version}`);
}

// Load config when the application starts
loadActiveConfig();

// Example of using config
function processRequest(req) {
  if (activeConfig.featureFlags.newFeatureEnabled) {
    // Logic using the new feature
  } else {
    // Old logic
  }
  // Use activeConfig.databaseUrl, activeConfig.apiEndpoint, etc.
}

// ... rest of the application logic ...

The application only cares about the configuration available via the active-config pointer.

The Switching Mechanism:

The "switch" in this configuration strategy is simple: update the active-config pointer to reference the JSON file for the new environment/version.

#!/bin/bash

NEW_CONFIG_FILE="config.green.v2.json"
CONFIG_DIR="/path/to/your/app/config"
ACTIVE_LINK="active-config.json"
BACKUP_LINK="active-config.json.bak"

# Backup the current active link
if [ -L "${CONFIG_DIR}/${ACTIVE_LINK}" ]; then
    echo "Backing up existing active link..."
    mv "${CONFIG_DIR}/${ACTIVE_LINK}" "${CONFIG_DIR}/${BACKUP_LINK}"
fi

# Create the new active link pointing to the new config
echo "Switching active config to ${NEW_CONFIG_FILE}..."
ln -s "${NEW_CONFIG_FILE}" "${CONFIG_DIR}/${ACTIVE_LINK}"

echo "Config switch complete. Application instances should pick up the new config on restart or reload."

# Note: Applications might need a restart or a configuration reload signal
# depending on how they are implemented to pick up the change.

This script, executed as part of your deployment process *after* the new application version is deployed to the Green environment, makes the configuration intended for the new version available. When traffic is then switched, the instances receiving traffic (the Green ones) will be using the correct configuration. If using a reload mechanism instead of restart, the application could theoretically pick up the new config dynamically without a full restart.

Blue-Green Deployment Steps with JSON Config

1. Prepare Green Environment: Ensure the Green environment infrastructure is ready and identical to Blue.
2. Deploy New Version to Green: Deploy the new application code and the corresponding new JSON configuration file(s) (e.g., config.green.v2.json) to the Green environment. The Green environment instances are not yet serving production traffic.
3. Run Tests on Green: Execute automated (and potentially manual) tests against the Green environment directly (e.g., via its internal IP or a separate test domain) to verify the new code and its configuration are working correctly.
4. Update Active Configuration Pointer: Execute the configuration switching step (like the symlink update script). This makes config.green.v2.json the "active" configuration source that Green instances will load. If Green instances are running, they might need a restart or explicit reload signal to pick up this change.
5. Perform Final Checks on Green: After Green instances reload with the new configuration, run smoke tests or basic health checks against the Green environment via its production-facing access point (if available without switching production traffic) to ensure it loaded the config correctly and is healthy.
6. Switch Traffic: Update the load balancer or DNS to direct 100% of production traffic to the Green environment.
7. Monitor Green: Closely monitor the Green environment's performance, error rates, and application logs. The Blue environment remains running and idle.
8. Rollback (If Needed): If significant issues arise in Green, immediately switch traffic back to the Blue environment. Then, diagnose and fix the issues in a non-production environment before attempting another Green deployment.
9. Decommission/Update Blue: If the Green environment is stable for a predetermined period, the old Blue environment can be decommissioned, shut down, or prepared to become the "Green" environment for the *next* deployment cycle (deploying version 3).

Benefits of this Approach

• Zero Downtime for Config Changes: Configuration changes, even those requiring reloads, are applied to the inactive environment before the traffic switch, minimizing impact on users.
• Simple and Transparent: JSON files are human-readable and easily managed in version control. The switching mechanism (like a symlink) is straightforward.
• Atomic Switching: The configuration switch itself is typically a very fast operation.
• Easy Rollback: Rolling back the code (switch traffic back to Blue) is often automatically accompanied by rolling back the configuration, especially if the Blue environment was left untouched. If configuration requires its own rollback step, having the old config file readily available makes this simple.
• Decoupled from Code Build: Configuration files can potentially be updated and managed slightly independently of the main code build process, allowing for quick config-only updates (though care is needed to ensure config compatibility with the deployed code version).

Challenges and Considerations

• Cost: Maintaining two production-sized environments can be expensive.
• Database Changes: Database schema migrations or data migrations are often the trickiest part. They must be handled carefully to be compatible with *both* the old version (Blue) and the new version (Green) during the transition. This might involve forward/backward compatible schema changes.
• State Management: Sessions, caches, queues, and long-running jobs need careful consideration to ensure a smooth transition and prevent data loss or corruption when switching environments.
• Configuration Reload: Applications need to be built to reload their configuration without a full restart, or the deployment process must include a graceful restart of the Green instances after the config switch but before the traffic switch.
• Complexity with Many Services: Coordinating Blue-Green switches and config updates across multiple microservices requires orchestration.
• Secrets Management: Storing sensitive secrets directly in JSON files is not recommended. Integrate with a secure secrets manager, and have your application load secrets based on the active configuration's pointers or identifiers.

Alternative Config Storage

While JSON files are simple for this pattern, the "active config pointer" idea can be applied to other configuration storage methods:

• Environment Variables: Set environment variables differently for the Blue and Green instances. The traffic switch implies that new requests go to instances with the 'Green' variables.
• Configuration Service: Use a dedicated configuration service (like HashiCorp Consul, etcd, or a cloud provider's config store). The application reads keys based on its environment (Blue/Green). The "switch" involves updating the values in the configuration service for the 'Green' keys.
• Database: Configuration could live in a database table. The application queries the table. A switch might involve updating a row, or updating an environment variable that tells the app which set of config rows to use.

The JSON file approach is often favored for its simplicity and ease of integration into existing file-based deployment workflows.

Blue-Green vs. Feature Flags vs. Canary

It's useful to understand how Blue-Green relates to other techniques:

• Feature Flags: Control specific features for subsets of users *within* a single deployed application version. JSON configuration can easily store feature flag states, and Blue-Green deployment helps get the new version (which understands the new flags) into production safely. They complement each other — Blue-Green for the infrastructure/code switch, Feature Flags for gradual rollout of features *post*-deployment.
• Canary Releases: Gradually roll out a new version to a *small percentage* of users first, while the majority still use the old version. This requires routing traffic based on user/request attributes, not just switching 100% of traffic at once. Canary is often considered more complex but allows for testing with real users before a full rollout. Blue-Green config switching could potentially be adapted for Canary by having config files that expose features only to 'canary' traffic, but it's less common than using a dedicated feature flag system for Canary.

Conclusion

Blue-Green deployment is a robust strategy for minimizing downtime and risk during application updates. Integrating a simple JSON configuration switching mechanism aligns well with this pattern, providing a clear, version-controlled way to manage application settings specific to each environment and application version during the deployment lifecycle. While it requires careful planning, especially regarding database changes and state, its benefits in enabling fast, reliable deployments and easy rollbacks make it a popular choice for many production systems.