Use Case 020: Multi-Environment Configuration Deployment

Overview

Description

This use case describes how Application Manager enables administrators and DevOps teams to manage configuration files across multiple environments (development, staging, beta, production) with clear separation, environment-specific overrides, and controlled promotion workflows. Users can create environment-specific configurations, promote validated configurations from lower to higher environments, compare configuration differences across environments, and deploy changes without container rebuilds—all while maintaining strict access controls and comprehensive audit trails.

Actors

Preconditions

1. Application Manager is running and accessible
2. User authenticated with appropriate environment permissions
3. At least one application registered with environment support
4. Environment structure defined (dev, staging, beta, production)
5. Base configuration files exist in development environment
6. User has environment-specific capabilities (e.g., config:deploy:production)

Postconditions

Success Postconditions

1. Configuration files created/updated in target environment
2. Environment-specific overrides applied correctly
3. Configuration validation passed for target environment
4. Deployment history recorded with environment context
5. Applications in target environment fetch updated configurations
6. Changes logged in audit trail with environment information
7. Notifications sent to relevant stakeholders

Failure Postconditions

1. Configuration deployment rejected if validation fails
2. Rollback initiated for failed deployments
3. Error details logged with environment context
4. Alerts sent to administrators
5. Previous configuration remains active

Triggers

• Developer creates/modifies configuration in development environment
• DevOps engineer promotes configuration from staging to production
• CI/CD pipeline deploys environment-specific configuration
• Administrator compares configurations across environments
• Application service restart in specific environment triggers config fetch
• Scheduled deployment automation runs
• Emergency rollback initiated in production

Basic Flow (Happy Path - Configuration Promotion)

Alternative Flows

Alt-1: Environment-Specific Override

Trigger: Configuration needs different values per environment

Flow:

1. Developer creates base configuration in development:

   {
     "Database": {
       "ConnectionString": "{{DB_CONNECTION}}",
       "MaxPoolSize": 100
     },
     "Logging": {
       "Level": "Debug"
     }
   }
   

2. DevOps creates environment overrides:

   • Development: LogLevel: Debug, small pool size
   • Staging: LogLevel: Information, medium pool size
   • Production: LogLevel: Warning, large pool size, connection string from secret

3. System merges base config with environment-specific overrides

4. Applications fetch environment-appropriate configuration

5. Variables like {{DB_CONNECTION}} resolved from environment secrets

Alt-2: Configuration Diff and Comparison

Trigger: DevOps wants to compare staging vs production configs

Flow:

1. DevOps selects "Compare Environments"
2. UI prompts for source and target environments
3. DevOps selects "Staging" vs "Production"
4. API fetches configurations from both environments
5. System performs file-by-file comparison
6. UI displays side-by-side diff:
   • Files only in staging (green)
   • Files only in production (red)
   • Files with differences (yellow)
   • Identical files (grey)
7. DevOps can drill down to line-by-line differences
8. DevOps can promote individual files or bulk promote

Alt-3: Automated Promotion (CI/CD Integration)

Trigger: CI/CD pipeline deploys application to staging

Flow:

1. CI/CD pipeline builds application
2. Pipeline calls Configuration Manager API:

   POST /api/v1/config/promote
   -H "Authorization: Bearer $CI_TOKEN"
   -d '{"sourceEnv": "dev", "targetEnv": "staging", "applicationId": "app-1"}'
   

3. API validates CI token has promotion permission
4. API promotes all configurations for application
5. API returns promotion summary (files updated, validation results)
6. Pipeline continues with deployment
7. Pipeline confirms configurations applied

Alt-4: Production Deployment with Approval

Trigger: DevOps promotes configuration to production

Flow:

1. DevOps initiates promotion to production
2. System detects production requires approval
3. API creates pending deployment request
4. System sends notification to production approvers
5. Approver reviews deployment request:
   • Configuration diff
   • Deployment notes
   • Risk assessment
   • Previous deployment history
6. Approver approves or rejects request
7. If approved, deployment proceeds automatically
8. If rejected, requester notified with rejection reason

Alt-5: Failed Production Deployment Rollback

Trigger: Deployed configuration causes application errors

Flow:

1. Application in production applies new configuration
2. Application health checks start failing
3. Monitoring system detects degraded health
4. Alert sent to on-call engineer
5. Engineer reviews recent configuration changes
6. Engineer initiates emergency rollback:

   POST /api/v1/config/rollback
   {"environment": "production", "fileId": "...", "version": "v1"}
   

7. System immediately reverts to previous version
8. Application fetches rolled-back configuration
9. Application health restored
10. Incident logged for post-mortem

Business Rules

Environment Hierarchy Rules

• BR-020-01: Environments ordered: Development < Staging < Beta < Production
• BR-020-02: Configurations can only be promoted up the hierarchy (dev → staging → beta → prod)
• BR-020-03: Demotion (prod → staging) requires explicit config:demote permission
• BR-020-04: Cross-environment comparisons allowed for all authenticated users

Permission Rules

• BR-020-05: Development access: All developers have read/write access
• BR-020-06: Staging deployment: Requires config:deploy:staging capability
• BR-020-07: Production deployment: Requires config:deploy:production capability
• BR-020-08: Production deployment approval: Configurable (optional or required)
• BR-020-09: Emergency production rollback: Requires config:rollback:production

Validation Rules

• BR-020-10: All configurations validated before deployment
• BR-020-11: Environment-specific validation rules enforced (e.g., prod requires encryption)
• BR-020-12: Production configurations must not contain "localhost" or "127.0.0.1"
• BR-020-13: Secret placeholders (e.g., {{DB_PASSWORD}}) resolved from environment secrets
• BR-020-14: Schema validation failures block deployment

Version Control Rules

• BR-020-15: Each environment maintains independent version history
• BR-020-16: Promotions create new version in target environment
• BR-020-17: Rollback possible to any previous version within retention period
• BR-020-18: Version retention: Development (3 versions), Staging (5), Production (10)

Data Requirements

Environment Entity

ConfigurationFile Entity (Extended)

EnvironmentOverride Entity

User Interface

Environment Selector

┌─────────────────────────────────────────┐
│ Environment: [Staging ▼]                │
├─────────────────────────────────────────┤
│ • Development   (18 configs)            │
│ • Staging   ← You are here              │
│ • Beta          (15 configs)            │
│ • Production    (15 configs) 🔒         │
└─────────────────────────────────────────┘

Configuration Promotion Dialog

┌──────────────────────────────────────────────────┐
│ Promote Configuration to Production             │
├──────────────────────────────────────────────────┤
│ File: appsettings.json                           │
│ Source: Staging (v3)                             │
│ Target: Production (currently v2)                │
│                                                  │
│ Configuration Diff:                              │
│ ┌──────────────────────────────────────────────┐ │
│ │   "Database": {                              │ │
│ │ -   "ConnectionString": "Server=staging-db" │ │
│ │ +   "ConnectionString": "Server=prod-db"    │ │
│ │     "MaxPoolSize": 100                       │ │
│ │   },                                         │ │
│ │   "Logging": {                               │ │
│ │ -   "Level": "Information"                   │ │
│ │ +   "Level": "Warning"                       │ │
│ │   }                                          │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ Deployment Notes (Required):                     │
│ ┌──────────────────────────────────────────────┐ │
│ │ Deploy latest database connection string    │ │
│ │ and reduce logging verbosity for production │ │
│ └──────────────────────────────────────────────┘ │
│                                                  │
│ ⚠️  This deployment requires approval.           │
│                                                  │
│ [Cancel]                    [Submit for Approval]│
└──────────────────────────────────────────────────┘

Environment Comparison View

┌────────────────────────────────────────────────────────┐
│ Compare: [Staging ▼] vs [Production ▼]    [Refresh]   │
├────────────────────────────────────────────────────────┤
│ File                        Staging      Production    │
├────────────────────────────────────────────────────────┤
│ 🟢 appsettings.json         v3 (newer)   v2           │
│ 🟡 database.json            v2 (diff)    v2 (diff)    │
│ ⚪ logging.json             v1           v1           │
│ 🔴 experimental.json        v1           (missing)    │
├────────────────────────────────────────────────────────┤
│ Legend:                                                 │
│ 🟢 Newer in source  🟡 Different  ⚪ Identical  🔴 Missing│
│                                                        │
│ [Promote All Differences] [Promote Selected]          │
└────────────────────────────────────────────────────────┘

API Endpoints

List Environments

Endpoint: GET /api/v1/config/environments

Response: 200 OK

{
  "environments": [
    {"id": "env-1", "name": "development", "displayName": "Development", "tier": "Development", "order": 1, "color": "#28a745"},
    {"id": "env-2", "name": "staging", "displayName": "Staging", "tier": "Staging", "order": 2, "color": "#ffc107"},
    {"id": "env-3", "name": "beta", "displayName": "Beta", "tier": "Beta", "order": 3, "color": "#17a2b8"},
    {"id": "env-4", "name": "production", "displayName": "Production", "tier": "Production", "order": 4, "color": "#dc3545"}
  ]
}

Promote Configuration

Endpoint: POST /api/v1/config/promote

Request Body:

{
  "sourceEnvironmentId": "env-2",
  "targetEnvironmentId": "env-4",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "deploymentNotes": "Deploy optimized database connection pool settings",
  "validateOnly": false
}

Response: 200 OK

{
  "promotionId": "660e8400-e29b-41d4-a716-446655440099",
  "status": "AwaitingApproval",
  "sourceEnvironment": "staging",
  "targetEnvironment": "production",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "appsettings.json",
  "validationResult": {
    "valid": true,
    "warnings": [],
    "errors": []
  },
  "requiresApproval": true,
  "estimatedApprovalTime": "2026-02-24T10:00:00Z"
}

Compare Environments

Endpoint: GET /api/v1/config/compare?source={envId}&target={envId}

Response: 200 OK

{
  "sourceEnvironment": "staging",
  "targetEnvironment": "production",
  "differences": [
    {
      "filePath": "/appsettings.json",
      "status": "SourceNewer",
      "sourceVersion": "v3",
      "targetVersion": "v2",
      "lastModified": "2026-02-23T10:00:00Z"
    },
    {
      "filePath": "/database.json",
      "status": "Different",
      "sourceVersion": "v2",
      "targetVersion": "v2",
      "contentHash": "different"
    }
  ],
  "summary": {
    "totalFiles": 15,
    "identical": 11,
    "different": 2,
    "sourceOnly": 1,
    "targetOnly": 1
  }
}

Rollback Configuration

Endpoint: POST /api/v1/config/rollback

Request Body:

{
  "environmentId": "env-4",
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "targetVersion": "v2",
  "reason": "New configuration causing high error rates"
}

Response: 200 OK

{
  "rollbackId": "770e8400-e29b-41d4-a716-446655440088",
  "environment": "production",
  "fileName": "appsettings.json",
  "rolledBackFrom": "v3",
  "rolledBackTo": "v2",
  "rolledBackBy": "jane@example.com",
  "timestamp": "2026-02-23T11:15:00Z"
}

Performance Requirements

• PR-020-01: Environment listing completed within 200ms
• PR-020-02: Configuration promotion completed within 3 seconds
• PR-020-03: Environment comparison for 100 files completed within 2 seconds
• PR-020-04: Configuration rollback completed within 1 second
• PR-020-05: Application configuration fetch completed within 500ms

Security Considerations

Access Control

• Environment-specific permissions enforced (dev, staging, production)
• Production deployment requires elevated privileges
• Audit trail for all cross-environment operations
• RBAC enforced at environment level

Secret Management

• Environment variables encrypted at rest (AES-256)
• Secret placeholders resolved only at application runtime
• Secrets never logged in plain text
• Production secrets accessible only to production deploy role

Change Management

• Production deployments optionally require approval
• Emergency rollback capability for production incidents
• All promotions logged with user identity and timestamp
• Deployment notes required for production changes

Testing Scenarios

Test Case TC-020-01: Configuration Promotion

Steps:

1. Developer creates configuration in development
2. Configuration validated and deployed to dev
3. DevOps promotes to staging
4. DevOps tests in staging
5. DevOps promotes to production (with approval)
6. Approver reviews and approves
7. Configuration deployed to production

Expected Results:

• Configuration successfully promoted through all environments
• Version history maintained per environment
• Audit trail shows promotion chain
• Applications in each environment fetch correct version

Test Case TC-020-02: Environment Comparison

Steps:

1. DevOps compares staging vs production
2. System generates diff report
3. DevOps reviews differences

Expected Results:

• Diff accurately shows configuration differences
• Files categorized correctly (identical, different, missing)
• Side-by-side comparison available

Test Case TC-020-03: Emergency Rollback

Steps:

1. Production deployment causes issues
2. Engineer identifies problem configuration
3. Engineer initiates rollback to v2
4. System immediately reverts configuration

Expected Results:

• Rollback completed within 1 second
• Applications fetch rolled-back version
• Rollback logged in audit trail
• Alert sent to team

Monitoring and Analytics

Metrics

• config.promotion.count: Promotions per environment
• config.promotion.duration: Promotion completion time
• config.rollback.count: Rollback frequency per environment
• config.deployment.failure: Failed deployment count
• config.approval.duration: Time from request to approval

Alerts

• High rollback rate: > 10% deployments rolled back in 7 days
• Pending approvals: Approval pending > 24 hours
• Deployment failures: > 3 failures in 1 hour

Related Use Cases

• UC-007: Configuration File Management - Base configuration operations
• UC-008: Configuration Version Control and Rollback - Version management
• UC-010: Activity Logging and Audit Trail - Deployment logging
• UC-006: Role-Based Access Control - Environment permissions

Notes and Assumptions

Assumptions

1. Applications support environment-aware configuration fetching
2. Environment secrets managed securely
3. Approval workflows configured per organization policy

Implementation Notes

1. Support for configuration templates with environment variable substitution
2. Consider GitOps integration for configuration as code
3. Implement canary deployments for phased production rollouts

Revision History