Configuration

Overview

Configuration migrates from Docker Compose .env files to Kubernetes ConfigMaps and Secrets. In staging, secrets are created manually via create-secrets.sh. In production, Sealed Secrets provides Git-safe encryption.

ConfigMap Organization

Each service gets its own ConfigMap with non-sensitive configuration. ConfigMaps are plain YAML, defined per environment (staging vs production) and applied with kubectl.

Shared ConfigMap

Values shared across all backend services. Note the namespace differences for service discovery and data layer access.

StagingProduction

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-shared-config
  namespace: nx-backend
data:
  NODE_ENV: staging

  # PostgreSQL via PgBouncer - nx-persistent namespace
  APP_ENV_POSTGRES_HOST: nx-pgbouncer.nx-persistent.svc.cluster.local
  APP_ENV_POSTGRES_PORT: "5432"
  APP_ENV_POSTGRES_USERNAME: nx_seller_operator
  APP_ENV_POSTGRES_DATABASE: nx_seller_core

  # Redis - cluster mode, 3 nodes (nx-broker namespace)
  APP_ENV_CACHE_REDIS_MODE: cluster
  APP_ENV_CACHE_REDIS_CLUSTER_NODES: "nx-redis-0.nx-redis-headless.nx-broker.svc.cluster.local:6379,nx-redis-1.nx-redis-headless.nx-broker.svc.cluster.local:6379,nx-redis-2.nx-redis-headless.nx-broker.svc.cluster.local:6379"

  # Kafka - CLIENT listener with SASL/SCRAM-SHA-512 (nx-broker namespace)
  APP_ENV_KAFKA_BROKERS: nx-kafka-0.nx-kafka-headless.nx-broker.svc.cluster.local:9092,nx-kafka-1.nx-kafka-headless.nx-broker.svc.cluster.local:9092,nx-kafka-2.nx-kafka-headless.nx-broker.svc.cluster.local:9092
  APP_ENV_KAFKA_SASL_ENABLE: "true"
  APP_ENV_KAFKA_SASL_MECHANISM: SCRAM-SHA-512
  APP_ENV_KAFKA_SASL_USERNAME: nx.staging
  # APP_ENV_KAFKA_SASL_PASSWORD is in nx-shared-secret

  # Service discovery - nx-backend namespace
  APP_ENV_IDENTITY_SERVICE_BASE_URL: http://nx-identity.nx-backend.svc.cluster.local:3000/v1/api/identity
  APP_ENV_COMMERCE_SERVICE_BASE_URL: http://nx-commerce.nx-backend.svc.cluster.local:3000/v1/api/commerce
  APP_ENV_PRICING_SERVICE_BASE_URL: http://nx-pricing.nx-backend.svc.cluster.local:3000/v1/api/pricing

  # Domains - staging
  APP_DOMAIN: sgw.staging.bana.com.vn
  HOOK_DOMAIN: hook.staging.bana.com.vn

yaml

# Mirrors the staging shared-config; only the values that actually
# differ between environments change (marked below).
apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-shared-config
  namespace: nx-backend
data:
  NODE_ENV: production            # differs from staging

  # PostgreSQL via PgBouncer - nx-persistent namespace
  APP_ENV_POSTGRES_HOST: nx-pgbouncer.nx-persistent.svc.cluster.local
  APP_ENV_POSTGRES_PORT: "5432"
  APP_ENV_POSTGRES_USERNAME: nx_seller_operator
  APP_ENV_POSTGRES_DATABASE: nx_seller_core

  # Redis - cluster mode, 3 nodes (nx-broker namespace)
  APP_ENV_CACHE_REDIS_MODE: cluster
  APP_ENV_CACHE_REDIS_CLUSTER_NODES: "nx-redis-0.nx-redis-headless.nx-broker.svc.cluster.local:6379,nx-redis-1.nx-redis-headless.nx-broker.svc.cluster.local:6379,nx-redis-2.nx-redis-headless.nx-broker.svc.cluster.local:6379"

  # Kafka - CLIENT listener with SASL/SCRAM-SHA-512 (nx-broker namespace)
  APP_ENV_KAFKA_BROKERS: nx-kafka-0.nx-kafka-headless.nx-broker.svc.cluster.local:9092,nx-kafka-1.nx-kafka-headless.nx-broker.svc.cluster.local:9092,nx-kafka-2.nx-kafka-headless.nx-broker.svc.cluster.local:9092
  APP_ENV_KAFKA_SASL_ENABLE: "true"
  APP_ENV_KAFKA_SASL_MECHANISM: SCRAM-SHA-512
  APP_ENV_KAFKA_SASL_USERNAME: nx.production    # differs from staging
  # APP_ENV_KAFKA_SASL_PASSWORD is in nx-shared-secret

  # Service discovery - nx-backend namespace
  APP_ENV_IDENTITY_SERVICE_BASE_URL: http://nx-identity.nx-backend.svc.cluster.local:3000/v1/api/identity
  APP_ENV_COMMERCE_SERVICE_BASE_URL: http://nx-commerce.nx-backend.svc.cluster.local:3000/v1/api/commerce
  APP_ENV_PRICING_SERVICE_BASE_URL: http://nx-pricing.nx-backend.svc.cluster.local:3000/v1/api/pricing

  # Domains - production (TBD)
  APP_DOMAIN: TBD
  HOOK_DOMAIN: TBD

  # OpenTelemetry - production only
  OTEL_EXPORTER_OTLP_ENDPOINT: http://nx-otel-collector.nx-watcher.svc.cluster.local:4317
  OTEL_SERVICE_NAME: bana

Staging vs Production ConfigMap Differences

Key	Staging	Production
`NODE_ENV`	`staging`	`production`
`APP_ENV_POSTGRES_HOST`	`nx-pgbouncer.nx-persistent...` (PgBouncer)	`nx-pgbouncer.nx-persistent...` (PgBouncer)
`APP_ENV_CACHE_REDIS_MODE`	`cluster`	`cluster`
`APP_ENV_KAFKA_SASL_USERNAME`	`nx.staging`	`nx.production`
`APP_DOMAIN`	`sgw.staging.bana.com.vn`	TBD
`HOOK_DOMAIN`	`hook.staging.bana.com.vn`	TBD
`OTEL_EXPORTER_OTLP_ENDPOINT`	Not set	`http://nx-otel-collector.nx-watcher.svc.cluster.local:4317`

TIP

Service discovery URLs (APP_ENV_IDENTITY_SERVICE_BASE_URL, APP_ENV_COMMERCE_SERVICE_BASE_URL, etc.) are the same across environments because they use cluster-internal DNS within nx-backend. Only external-facing domains differ.

Per-Service ConfigMaps

identity-specific config

yaml

# identity-specific config
apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-identity-config
  namespace: nx-backend
data:
  APP_ENV_APPLICATION_NAME: identity
  APP_ENV_APPLICATION_CODE: SVC-00010-IDENTITY
  APP_ENV_APPLICATION_ROLES: identity
  APP_ENV_SERVER_BASE_PATH: /v1/api/identity
  APP_ENV_SNOWFLAKE_WORKER_ID: "1"
  # JWKS - identity is the token issuer (ES256)
  APP_ENV_JWKS_ALGORITHM: ES256
  APP_ENV_JWKS_REST_PATH: /jw-certs
  APP_ENV_JWT_EXPIRES_IN: "86400"

payment-api specific config

yaml

# payment-api specific config
apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-payment-api-config
  namespace: nx-backend
data:
  APP_ENV_APPLICATION_NAME: payment-api
  APP_ENV_APPLICATION_CODE: SVC-00080-PAYMENT
  APP_ENV_APPLICATION_ROLES: payment
  APP_ENV_SERVER_BASE_PATH: /v1/api/payment
  APP_ENV_SNOWFLAKE_WORKER_ID: "8"
  # MQ-Pay runs in API mode
  APP_ENV_MQ_PAY_MODE: api

payment-worker specific config

yaml

# payment-worker specific config
apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-payment-worker-config
  namespace: nx-backend
data:
  APP_ENV_APPLICATION_NAME: payment-worker
  APP_ENV_APPLICATION_CODE: SVC-00080-PAYMENT
  APP_ENV_APPLICATION_ROLES: payment
  APP_ENV_SERVER_BASE_PATH: /v1/api/payment
  APP_ENV_SNOWFLAKE_WORKER_ID: "90"
  # MQ-Pay runs in worker mode
  APP_ENV_MQ_PAY_MODE: worker

Docker Compose to K8s DNS Mapping

Docker Compose (`.env`)	K8s ConfigMap	Notes
`APP_ENV_POSTGRES_HOST=nx-postgresql`	`APP_ENV_POSTGRES_HOST=nx-pgbouncer.nx-persistent.svc.cluster.local`	Same key; Compose uses one host, K8s the PgBouncer pooler (cross-namespace FQDN)
`APP_ENV_CACHE_REDIS_HOST=nx-redis`	`APP_ENV_CACHE_REDIS_CLUSTER_NODES=nx-redis-{0,1,2}.nx-redis-headless.nx-broker...`	Single-node Compose Redis → 3-node cluster mode in `nx-broker`
`APP_ENV_KAFKA_BROKERS=nx-kafka-1:29092,...`	`APP_ENV_KAFKA_BROKERS=nx-kafka-0.nx-kafka-headless.nx-broker...:9092,...`	CLIENT listener port 9092 with SASL in `nx-broker`
`APP_ENV_IDENTITY_SERVICE_BASE_URL=http://dev-nx-identity:3000`	`APP_ENV_IDENTITY_SERVICE_BASE_URL=http://nx-identity.nx-backend.svc.cluster.local:3000/v1/api/identity`	Same key; only the host/DNS changes

TIP

Within the same namespace, short DNS names work: nx-identity:3000. Cross-namespace requires the full \<svc\>.\<ns\>.svc.cluster.local form. All backend services are in nx-backend; frontend services stay in nx-app. Data services are split across nx-persistent, nx-broker, and nx-search.

Secrets Management

Staging: Manual Creation via `create-secrets.sh`

In staging, secrets are created manually using the create-secrets.sh script in infrastructure/deployments/staging/manifests/02-secrets/. Template YAML files define the structure; the script prompts for actual values and creates K8s secrets directly.

bash

# Run from the staging manifests directory
cd infrastructure/deployments/staging/manifests/02-secrets/
./create-secrets.sh

Production: Sealed Secrets

Sealed Secrets encrypts secrets client-side so they can be stored in Git (production only).

Workflow (Production)

bash

# 1. Create a regular secret YAML (DO NOT commit this)
cat <<EOF > secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: nx-identity-secret
  namespace: nx-backend
type: Opaque
stringData:
  APP_ENV_JWKS_PRIVATE_KEY: "<your-jwks-private-key>"
  APP_ENV_JWKS_PUBLIC_KEY: "<your-jwks-public-key>"
  APP_ENV_VNPAY_SMS_SECRET_KEY: "<your-vnpay-sms-secret>"
EOF

# 2. Seal it (encrypts with cluster's public key)
kubeseal --format yaml < secret.yaml > sealed-secret.yaml

# 3. Commit the sealed version
git add sealed-secret.yaml
rm secret.yaml  # Never commit the plain version

Secret Organization

Secret	Namespace	Contents
`nx-shared-secret`	`nx-backend`	`APP_ENV_POSTGRES_PASSWORD`, `APP_ENV_CACHE_REDIS_PASSWORD`, `APP_ENV_KAFKA_SASL_PASSWORD`
`nx-identity-secret`	`nx-backend`	ES256 keys, mail credentials, SMS API keys
`nx-payment-secret`	`nx-backend`	Payment DB & Redis credentials
`nx-commerce-secret`	`nx-backend`	S3 credentials, VNPAY TVAN API key, Typesense key
`nx-sale-secret`	`nx-backend`	Basic auth credentials
`nx-ledger-secret`	`nx-backend`	Encryption key, S3 credentials
`nx-postgresql-superuser-secret`	`nx-persistent`	Postgres superuser credentials
`nx-postgresql-app-secret`	`nx-persistent`	App user (nx_seller_operator) credentials
`nx-postgresql-replication-secret`	`nx-persistent`	Streaming replication credentials
`nx-redis-secret`	`nx-broker`	`REDIS_PASSWORD`
`nx-kafka-jaas`	`nx-broker`	Kafka SASL/SCRAM JAAS config
`nx-kafka-scram-secret`	`nx-broker`	SCRAM username/password
`nx-typesense-secret`	`nx-search`	`TYPESENSE_API_KEY`
`staging-bana-tls`	`nx-internal`	TLS cert and key
`bcr-registry`	`nx-backend` / `nx-app` / `nx-internal`	Container registry pull credentials

INFO

The bcr-registry is an imagePullSecret required for pulling images from bcr.bana.com.vn private registry. It must be created in nx-backend, nx-app, and nx-internal and referenced in all Deployment specs or the namespace default ServiceAccount.

Pod Configuration

Pods reference both shared and service-specific configs:

yaml

spec:
  imagePullSecrets:
    - name: bcr-registry
  containers:
    - name: identity
      envFrom:
        # Shared config (APP_ENV_POSTGRES_HOST, APP_ENV_CACHE_REDIS_*, APP_ENV_KAFKA_BROKERS, ...)
        - configMapRef:
            name: nx-shared-config
        # Service-specific config (APP_ENV_APPLICATION_*, APP_ENV_SNOWFLAKE_WORKER_ID, ...)
        - configMapRef:
            name: nx-identity-config
        # Shared secrets (APP_ENV_POSTGRES_PASSWORD, APP_ENV_CACHE_REDIS_PASSWORD, ...)
        - secretRef:
            name: nx-shared-secret
        # Service-specific secrets
        - secretRef:
            name: nx-identity-secret

Configuration Hierarchy

Pod Environment
├── nx-shared-config      (ConfigMap) - shared across all services
├── nx-<service>-config   (ConfigMap) - service-specific overrides
├── nx-shared-secret      (Secret)    - shared credentials
└── nx-<service>-secret   (Secret)    - service-specific credentials

Later entries override earlier ones when keys conflict. This allows:

nx-shared-config sets APP_ENV_POSTGRES_HOST for all services
nx-identity-config can override any shared key if needed

Namespace Reference

Namespace	Purpose	ConfigMap/Secret scope
`nx-internal`	nginx-ingress, Traefik, cert-manager, API Portal	TLS certs, gateway configs, registry creds
`nx-backend`	Backend services	Backend configs, backend secrets, registry creds
`nx-app`	Frontend apps	Frontend configs, registry creds
`nx-persistent`	PostgreSQL	Database credentials
`nx-broker`	Redis, Kafka	Broker credentials
`nx-search`	Typesense	Search credentials
`nx-watcher`	Observability stack	Monitoring configs

Environment Variables

Services read configuration through IGNIS's ApplicationEnvironment, which loads every variable prefixed with APP_ENV_. Keys are declared as typed constants on an EnvironmentKeys class - the shared set lives in @nx/core, and each service extends it with its own keys.

typescript

// packages/identity/src/common/environments.ts
import { EnvironmentKeys as BaseEnvironmentKeys } from '@nx/core';

export class EnvironmentKeys extends BaseEnvironmentKeys {
  static readonly APP_ENV_CODE_BY_PASS_SMS_OTP = 'APP_ENV_CODE_BY_PASS_SMS_OTP';
  static readonly APP_ENV_ENABLE_BY_PASS_SMS_OTP = 'APP_ENV_ENABLE_BY_PASS_SMS_OTP';
}

The core EnvironmentKeys already declares the shared keys (APP_ENV_POSTGRES_HOST, APP_ENV_POSTGRES_PORT, APP_ENV_POSTGRES_DATABASE, APP_ENV_POSTGRES_USERNAME, …). This is the same contract used under Docker Compose - moving to K8s changes the values, not the keys.

Providers

Invoice Types

Configuration ​

Overview ​

ConfigMap Organization ​

Shared ConfigMap ​

Staging vs Production ConfigMap Differences ​

Per-Service ConfigMaps ​

Docker Compose to K8s DNS Mapping ​

Secrets Management ​

Staging: Manual Creation via create-secrets.sh ​

Production: Sealed Secrets ​

Workflow (Production) ​

Secret Organization ​

Pod Configuration ​

Configuration Hierarchy ​

Namespace Reference ​

Environment Variables ​

Configuration

Overview

ConfigMap Organization

Shared ConfigMap

Staging vs Production ConfigMap Differences

Per-Service ConfigMaps

Docker Compose to K8s DNS Mapping

Secrets Management

Staging: Manual Creation via `create-secrets.sh`

Production: Sealed Secrets

Workflow (Production)

Secret Organization

Pod Configuration

Configuration Hierarchy

Namespace Reference

Environment Variables