[Proposal] Standardize Environment Variable Prefix Across Gateway Components

[renuka-fernando]

Summary

This proposal standardizes the environment variable prefix used by gateway-controller and policy-engine into a single unified prefix scheme. Currently, gateway-controller uses GATEWAY_ and policy-engine uses PE_, forcing operators to maintain two separate naming conventions when configuring the gateway as a unit. A unified prefix eliminates this inconsistency, simplifies deployment configurations, and reduces operator error.

Motivation

Problem Statement

The WSO2 API Platform gateway is composed of two tightly co-deployed components -- gateway-controller and policy-engine -- that share a single TOML configuration file (config.toml) but use completely different environment variable prefixes for overrides:

• Gateway-controller uses GATEWAY_ (defined in gateway/gateway-controller/pkg/config/config.go, line 37)
• Policy-engine uses PE_ (defined in gateway/policy-engine/internal/config/config.go, line 35)

This causes several concrete problems:

1. Duplicated configuration logic in deployments. In Kubernetes, operators must create separate ConfigMap entries or separate environment variable blocks for each prefix, even though both components are configured from the same logical configuration tree. For example, docker-compose.yaml currently mixes both conventions:

   # Gateway-controller vars
   - GATEWAY_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
   - GATEWAY_GATEWAY__CONTROLLER_LOGGING_LEVEL=info
   # Policy-engine vars
   - PE_POLICY__ENGINE_METRICS_PORT=9003

2. Inconsistent naming creates cognitive load. Operators must remember which prefix applies to which sub-component, and the mapping rules differ (e.g., GATEWAY_ uses double-underscore for nested keys differently than PE_).

Who Benefits

• Platform operators / SREs: Simpler, consistent environment variable naming across all gateway components reduces deployment errors and configuration sprawl.
• Developer experience engineers: Fewer prefixes to document, fewer edge cases to explain.
• CI/CD pipeline maintainers: A single prefix convention simplifies templating in Helm charts, Kustomize overlays, and docker-compose files.
• Contributors: One convention to learn instead of two.

Why Now

• The gateway is approaching broader adoption, and configuration conventions established now will be difficult to change after widespread deployment.
• The shared config.toml pattern (introduced recently with the unified TOML configuration) makes this the natural time to also unify environment variable overrides.

Industry Patterns

Research into how popular tools name their environment variables shows two distinct patterns:

Full Names (No Abbreviations)

• Testcontainers: TESTCONTAINERS_RYUK_DISABLED, TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE
• MongoDB: MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD
• GitHub Actions: GITHUB_REPOSITORY, GITHUB_WORKSPACE, GITHUB_ACTIONS
• Google Cloud: GOOGLE_CLOUD_PROJECT (also supports shorter GCP_PROJECT)

Established Abbreviations

• AWS: AWS_ACCESS_KEY_ID, AWS_REGION, AWS_PROFILE (not AMAZON_WEB_SERVICES_)
• Elasticsearch: ES_NETWORK_HOST, ES_CLUSTER_NAME (not ELASTICSEARCH_)
• PostgreSQL: POSTGRES_USER, POSTGRES_PASSWORD (not POSTGRESQL_)
• Docker: DOCKER_HOST, DOCKER_TLS_VERIFY

Key Observations

1. Well-known brands use full names: GitHub, Google Cloud, Testcontainers use complete words
2. Established abbreviations stick: AWS, ES, POSTGRES use short, recognizable forms
3. Product recognition drives choice: If your product/brand is establishing itself, use the full name
4. Modern tools favor clarity: Recent projects (Testcontainers, GitHub Actions) prefer explicit full names over brevity

Recommendation: While modern tools favor full names, we must balance clarity with practicality. Configuration keys can be deeply nested (e.g., gateway_controller.router.policy_engine.timeout_ms), resulting in very long environment variable names. APIP_GW_ provides clear namespacing while keeping variable names manageable.

Proposed Prefix Options

1. APIP_GW_ (8 chars) - Recommended - Platform namespaced, concise

   • Example: APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
   • APIP = API Platform (clear product identity)
   • GW = Gateway (widely understood abbreviation)
   • Keeps total variable length reasonable for deeply nested configuration keys

2. APIPLATFORM_GW_ (15 chars) - Full product name with component abbreviation

   • Example: APIPLATFORM_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
   • More explicit but adds 7 extra characters to every variable
   • Aligns with Testcontainers, MongoDB, GitHub Actions pattern

3. APIP_GATEWAY_ (13 chars) - Abbreviated platform with full component name

   • Example: APIP_GATEWAY_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite

4. APIPLATFORM_GATEWAY_ (19 chars) - Fully explicit, no abbreviations

   • Example: APIPLATFORM_GATEWAY_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
   • Results in very long variable names (54+ chars in examples)

5. GW_ (3 chars) - Bare minimum, high collision risk

   • Example: GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite

Understanding the Double Underscore Convention

You'll notice examples like APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite use double underscores (__) in the middle of the variable name. This is intentional and follows a standard convention for mapping environment variables to nested configuration structures.

Mapping Rules

Both gateway components use the Koanf configuration library, which maps environment variables to TOML configuration keys using these rules:

• Single underscore (_) → Converts to a dot (.) in the TOML path (nested sections)
• Double underscore (__) → Converts to a single underscore (_) in the TOML key (literal underscore)

Examples

Environment Variable	Maps to TOML Key
APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE	gateway_controller.storage.type
APIP_GW_POLICY__ENGINE_METRICS_PORT	policy_engine.metrics.port
APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL	gateway_controller.logging.level

Why This Pattern?

The TOML configuration structure uses underscores in section names (e.g., gateway_controller, policy_engine). To preserve these literal underscores when setting values via environment variables, we use double underscores. The single underscores between words then represent the nested hierarchy (section → subsection → key).

TOML structure:

[gateway_controller.storage]
type = "sqlite"

[policy_engine.metrics]
port = 9003

Environment variable equivalent:

APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
APIP_GW_POLICY__ENGINE_METRICS_PORT=9003

This convention is standard across many configuration tools (including Spring Boot, .NET, and other frameworks using hierarchical configuration).

Example Configuration Impact

Current state (split prefixes):

# docker-compose.yaml
services:
  gateway-controller:
    environment:
      - GATEWAY_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
      - GATEWAY_GATEWAY__CONTROLLER_LOGGING_LEVEL=info
      - GATEWAY_GATEWAY__CONTROLLER_METRICS_PORT=9091

  policy-engine:
    environment:
      - PE_POLICY__ENGINE_METRICS_PORT=9003
      - PE_POLICY__ENGINE_LOGGING_LEVEL=debug

Proposed (unified prefix with APIP_GW_):

# docker-compose.yaml - shared environment configuration
x-gateway-env: &gateway-env
  - APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=sqlite
  - APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL=info
  - APIP_GW_GATEWAY__CONTROLLER_METRICS_PORT=9091
  - APIP_GW_POLICY__ENGINE_METRICS_PORT=9003
  - APIP_GW_POLICY__ENGINE_LOGGING_LEVEL=debug

services:
  gateway-controller:
    environment: *gateway-env

  policy-engine:
    environment: *gateway-env

Kubernetes ConfigMap (unified):

apiVersion: v1
kind: ConfigMap
metadata:
  name: gateway-config
data:
  # Single prefix for all gateway components
  APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE: sqlite
  APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL: info
  APIP_GW_POLICY__ENGINE_METRICS_PORT: "9003"
  APIP_GW_POLICY__ENGINE_LOGGING_LEVEL: info

References

Codebase

• Gateway-controller config.go - Current GATEWAY_ prefix definition
• Policy-engine config.go - Current PE_ prefix definition
• Shared config.toml - Unified TOML configuration file
• docker-compose.yaml - Current mixed-prefix usage

Industry Research - Environment Variable Naming Patterns

• Testcontainers Configuration - Uses TESTCONTAINERS_ prefix
• GitHub Actions Variables Reference - Uses GITHUB_ prefix
• AWS CLI Environment Variables - Uses AWS_ prefix
• Google Cloud Auth Action - Uses GOOGLE_CLOUD_PROJECT, GCP_PROJECT
• Elasticsearch Configuration - Uses ES_ prefix
• MongoDB Docker Image - Uses MONGO_ prefix

[renuka-fernando]

Done the changes to go with APIP_GW_.