Skip to navigation

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.

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:

// 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

Previously, all environment keys were defined in a single object:

export const ENV_KEYS = { ... }

Now the keys are separated into three categories:

ConstantPurpose
APP_CONFIG_KEYSKeys stored in App Configuration
OPTIONAL_ENV_KEYSOptional environment variables (mainly for local development)
SYSTEM_ENVSEnvironment variables required for application startup

These are then merged into ENV_KEYS.

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:

BeforeAfter
SQL_SERVERFLUXX_FILE_INTAKE_SQL_SERVER
SQL_PORTFLUXX_FILE_INTAKE_SQL_PORT
APPLICATION_PORTFLUXX_FILE_INTAKE_APPLICATION_PORT
TOPIC_ACCEPTED_FILEFLUXX_FILE_INTAKE_TOPIC_ACCEPTED_FILE

This prevents key collisions across services.

Example:

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:

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.

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:

ENV_KEYS.<KEY_NAME>

Example:

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

Move the environment variable values to the appdevcommon-lz-config repository for each environment.

Update the following files accordingly:

  • app_config/<env>-eus2-adc-app-appcs-001.yaml

  • app_config/<env>-eus2-adc-app-appcs-001.json

  • app_config/<env>-eus2-saas-adc-app-appcs-001.json

1. Get the Configuration Values

Locate the configuration values in the service Helm files:

  • values.yml

  • <env>-values.yml

Example:

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 KeyApp Config Key
SQL_SERVERFLUXX_FILE_INTAKE_SQL_SERVER
APPLICATION_PORTFLUXX_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 KeyApp Config Key
SQL_SERVERFLUXX_FILE_INTAKE_SQL_SERVER
APPLICATION_PORTFLUXX_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

app.lookup('SQL_SERVER')

After

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:

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:

# 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
  1. Leave optional (OPTIONAL_ENV_KEYS) and system environment (SYSTEM_ENVS) variables unchanged:
# 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