Application Configuration Management Process

Overview

To ensure services can be reliably deployed and operated across multiple environments, we maintain a central registry of required configuration settings in /app-config.json. This file provides a clear inventory of what must be provisioned for the system to function correctly.

When to Add a Setting to /app-config.json

Developers MUST add a configuration key to /app-config.json if:

  1. The setting is required for the service to start or perform its core functions.
  2. The setting is environment-specific (e.g., URLs, connection strings, API keys) and does not have a "one-size-fits-all" default.
  3. The setting is an override of a default value that is expected to change in most production or production-like environments.
  4. The setting is security-sensitive (e.g., Auth Authority, Secret Keys). Note: only the key and description are added; never the value.

When to Exclude a Setting

It is acceptable to exclude a setting if:

  1. It has a sufficient default value that is unlikely to require an override in any deployed environment (e.g., internal cache timeouts, logging levels).
  2. The setting is strictly for local development and has no relevance in deployed environments.

Integration into Workflow

Pull Requests (PRs)

  • Any PR that introduces a new required configuration setting MUST include an update to /app-config.json.
  • PR reviewers should verify that the description for any new setting is clear and that no sensitive values or environment-specific defaults are included.
  • Automated Check: CodeRabbit is configured to scan for newly introduced configuration keys in appsettings.json, application.yml, and environment variable definitions. If new keys are detected without corresponding updates to /app-config.json, the PR will be flagged for correction and should be blocked until reconciled.

DevOps & Release Notes

  • /app-config.json serves as the primary hand-off artifact for DevOps during environment provisioning.
  • Release notes should highlight changes to /app-config.json to ensure transparency across teams.

File Format and Schema

The /app-config.json follows a structured schema:

global Array

Contains settings shared across most or all services (e.g., Kafka connection, Database provider).

services Object

Contains service-specific settings, keyed by the service name.

Configuration Entry Fields:

  • key: The dot-delimited or colon-delimited path to the configuration setting as it appears in appsettings.json or environment variables.
  • description: A brief explanation of the setting's purpose and its impact on the system.
  • required: (Optional, default: true) A boolean indicating if the setting is strictly required for the service to function.

Security Warning

NEVER commit environment-specific values, passwords, or secrets to /app-config.json. This file is intended for documentation and schema enforcement only. Use secure secret management (e.g., Azure Key Vault) for actual values in deployed environments.

Relationships

flowchart LR
nappconfig_4B2B8CF5["Design: Application Configuration Management Process"]