> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server. # Migration to Azure App Configuration-(Fluxx) This document outlines the steps and code changes required to migrate our application’s configuration management to Azure App Configuration. The goal is to centralize runtime configuration values, improve maintainability, and support environment-specific settings with better security and consistency. The migration involves: * Organizing configuration keys into logical groups * Introducing a consistent prefix for all runtime keys * Moving secret or optional environment variables to dedicated groups * Updating how configuration values are accessed in the codebase * Synchronizing configuration values in Helm deployment files and Azure App Configuration service Following this guide will ensure a smooth transition with minimal impact on existing functionality. --- ## Related Pull Requests * [File Intake new App Configuration Values](https://github.com/CLADevOps/fluxx-file-intake/pull/183) * [File Intake Migration to Azure App Configuartion](https://github.com/CLADevOps/appdevcommon-lz-config/pull/62) ## 1. App Configuration Setup Files Copy the following files into your service repository: * `src/internal/createAppConfigOptions.ts` * `src/middlware/app.config.middleware.ts` * `src/config/app.config.ts` --- ## 2. Update `index.ts` to Use the New App Configuration Setup Add the following during application startup: ```ts // Setup application configuration and get required config values const appConfig = await setupAppConfig(frameworkApp); ``` ## 3. Update Your Configuration Keys in `configurations.ts` ### Configuration Keys Are Now Grouped * [configuration.ts](https://github.com/CLADevOps/fluxx-file-intake/pull/183/changes#diff-1ffd45f8d7f31508a73639b5402d723e9df99d59846d4f7e3920374475e1da60) Previously, all environment keys were defined in a single object: ```ts export const ENV_KEYS = { ... } ``` Now the keys are separated into three categories: | Constant | Purpose | | ------------------- | ------------------------------------------------------------- | | APP\_CONFIG\_KEYS | Keys stored in App Configuration | | OPTIONAL\_ENV\_KEYS | Optional environment variables (mainly for local development) | | SYSTEM\_ENVS | Environment variables required for application startup | These are then merged into `ENV_KEYS`. ```ts export const ENV_KEYS = {   ...APP_CONFIG_KEYS,   ...OPTIONAL_ENV_KEYS,   ...SYSTEM_ENVS, } as const; ``` This keeps configuration organized and clarifies where each value comes from. --- ### App Configuration Keys Now Use a Prefix All runtime configuration keys now include the prefix: ``` FLUXX_FILE_INTAKE_ ``` Example changes: | Before | After | | --------------------- | ------------------------------------------ | | SQL\_SERVER | FLUXX\_FILE\_INTAKE\_SQL\_SERVER | | SQL\_PORT | FLUXX\_FILE\_INTAKE\_SQL\_PORT | | APPLICATION\_PORT | FLUXX\_FILE\_INTAKE\_APPLICATION\_PORT | | TOPIC\_ACCEPTED\_FILE | FLUXX\_FILE\_INTAKE\_TOPIC\_ACCEPTED\_FILE | This prevents key collisions across services. Example: ```ts SQL_SERVER: 'FLUXX_FILE_INTAKE_SQL_SERVER' ``` --- ### SQL Credentials Moved to Optional Environment Keys `SQL_USERNAME` and `SQL_PASSWORD` were removed from the main configuration and moved to: ```ts export const OPTIONAL_ENV_KEYS = {   SQL_USERNAME: 'SQL_USERNAME',   SQL_PASSWORD: 'SQL_PASSWORD', } ``` These are only needed when: * running locally * not using managed identity --- ### Added System Environment Variables Startup-related environment variables are now grouped under `SYSTEM_ENVS`. ```ts export const SYSTEM_ENVS = {   AZURE_APP_CONFIG_ENDPOINT: 'AZURE_APP_CONFIG_ENDPOINT',   NODE_ENV: 'NODE_ENV', } ``` These variables are required **before the application loads runtime configuration**. --- ### No Changes Required in Code Usage Developers should continue using: ```ts ENV_KEYS. ``` Example: ```ts ENV_KEYS.SQL_SERVER ENV_KEYS.APPLICATION_PORT ``` Since `ENV_KEYS` now merges all key groups, **existing usage remains compatible**. ## 4. Move Environment Variable Values to `appdevcommon-lz-config` * [sbx-eus2-adc-app-appcs-001.yaml](https://github.com/CLADevOps/appdevcommon-lz-config/pull/62/changes#diff-3d8216857c43fa4fd86cffa40cfccd153caf8fa9c0e47f57b4b38240441d10a7) Move the environment variable values to the **`appdevcommon-lz-config` repository** for each environment. Update the following files accordingly: * `app_config/-eus2-adc-app-appcs-001.yaml` * `app_config/-eus2-adc-app-appcs-001.json` * `app_config/-eus2-saas-adc-app-appcs-001.json` --- ### 1. Get the Configuration Values Locate the configuration values in the service Helm files: * `values.yml` * `-values.yml` Example: ```yaml SQL_SERVER: my-sql-server APPLICATION_PORT: 3000 ``` --- ### 2. Map the Key to the New Config Key Convert the existing key to the new prefixed format. Example mapping: | values.yml Key | App Config Key | | ----------------- | -------------------------------------- | | SQL\_SERVER | FLUXX\_FILE\_INTAKE\_SQL\_SERVER | | APPLICATION\_PORT | FLUXX\_FILE\_INTAKE\_APPLICATION\_PORT | --- ### 3. Add the Merged Values to the Environment-Specific Config Add the converted keys to the **environment-specific YAML/JSON files** in the `appdevcommon-lz-config` repository. Example mapping: | values.yml Key | App Config Key | | ----------------- | -------------------------------------- | | SQL\_SERVER | FLUXX\_FILE\_INTAKE\_SQL\_SERVER | | APPLICATION\_PORT | FLUXX\_FILE\_INTAKE\_APPLICATION\_PORT | --- ### Note Do **not** add the following values to `appdevcommon-lz-config`: * `NODE_ENV` * `AZURE_APP_CONFIG_ENDPOINT` * `SQL_USERNAME` * `SQL_PASSWORD` Also exclude any variables defined in: * `OPTIONAL_ENV_KEYS` * `SYSTEM_ENVS` ## 4. Update Configuration Access in the Service ### 1. Replace `app.lookup()` Calls Replace all `app.lookup()` calls in the service with the appropriate `appConfig` methods. Use: * `appConfig.get()` for string values * `appConfig.getNumber()` for numeric values * `appConfig.getBoolean()` for boolean values Example: **Before** ```ts app.lookup('SQL_SERVER') ``` **After** ```ts appConfig.get('SQL_SERVER') ``` --- ### 2. Remove Deprecated Lookup Utilities Delete references to the following functions: * `lookUp()` * `createLookup()` * `prepareLookup()` These may appear in files such as: * `app.ts` * `prepareLookup.ts` * `createLookup.ts` Remove the files and any related imports if they are no longer used. ## 5. Updating `.env.local.example` and `.env.example` with Prefixed Keys As part of migrating to Azure App Configuration, you need to update your local environment example files to reflect the new prefixed configuration keys. Example: * [.env.example](https://github.com/CLADevOps/fluxx-file-intake/pull/183/changes#diff-a3046da0d15a27e89f2afe639b25748a7ad4d9290af3e7b1b6c1a5533c8f0a8c) * [.env.local.example](https://github.com/CLADevOps/fluxx-file-intake/pull/183/changes#diff-51db1e9260201708554a6d042039c4cd3366a090e6d2c3c59f281b22740dc7d6) ### Steps: 1. Locate `.env.local.example` and `.env.example` files\*\* in your repository root. 2. Rename all existing keys by adding the prefix `FLUXX_FILE_INTAKE_`. For example: ```env # Before SQL_SERVER=your-sql-server SQL_PORT=1433 APPLICATION_PORT=3000 # After FLUXX_FILE_INTAKE_SQL_SERVER=your-sql-server FLUXX_FILE_INTAKE_SQL_PORT=1433 FLUXX_FILE_INTAKE_APPLICATION_PORT=3000 ``` 3. Leave **optional (`OPTIONAL_ENV_KEYS`) and system environment (`SYSTEM_ENVS`) variables** unchanged: ```env # Optional environment variables SQL_USERNAME=your-username SQL_PASSWORD=your-password # System environment variables AZURE_APP_CONFIG_ENDPOINT=https://your-app-config.azconfig.io NODE_ENV=development ```