Cấu hình

Tổng quan

Cấu hình di chuyển từ file .env của Docker Compose sang Kubernetes ConfigMap và Secret. Trên staging, secrets được tạo thủ công qua create-secrets.sh. Trên production, Sealed Secrets cung cấp mã hóa an toàn để lưu trong Git.

Tổ chức ConfigMap

Mỗi service có ConfigMap riêng với cấu hình không nhạy cảm. ConfigMap là YAML thuần, định nghĩa theo từng môi trường (staging vs production) và áp dụng bằng kubectl.

ConfigMap Dùng chung

Các giá trị được chia sẻ qua tất cả backend service. Lưu ý khác biệt namespace cho service discovery và truy cập tầng dữ liệu.

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

# Sao chép từ shared-config của staging; chỉ thay đổi các giá trị
# thực sự khác nhau giữa các môi trường (được đánh dấu bên dưới).
apiVersion: v1
kind: ConfigMap
metadata:
  name: nx-shared-config
  namespace: nx-backend
data:
  NODE_ENV: production            # khác với 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    # khác với 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

Khác biệt ConfigMap Staging vs Production

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`	Chưa đặt	`http://nx-otel-collector.nx-watcher.svc.cluster.local:4317`

TIP

Các URL service discovery (APP_ENV_IDENTITY_SERVICE_BASE_URL, APP_ENV_COMMERCE_SERVICE_BASE_URL, v.v.) giống nhau ở mọi môi trường vì chúng dùng DNS nội bộ cluster trong nx-backend. Chỉ các domain public-facing khác nhau.

ConfigMap theo Service

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

Ánh xạ DNS từ Docker Compose sang K8s

Docker Compose (`.env`)	K8s ConfigMap	Ghi chú
`APP_ENV_POSTGRES_HOST=nx-postgresql`	`APP_ENV_POSTGRES_HOST=nx-pgbouncer.nx-persistent.svc.cluster.local`	Cùng key; Compose dùng một host, K8s dùng pooler PgBouncer (FQDN cross-namespace)
`APP_ENV_CACHE_REDIS_HOST=nx-redis`	`APP_ENV_CACHE_REDIS_CLUSTER_NODES=nx-redis-{0,1,2}.nx-redis-headless.nx-broker...`	Redis một node trong Compose → cluster mode 3 node trong `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 với SASL trong `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`	Cùng key; chỉ host/DNS thay đổi

TIP

Trong cùng một namespace, tên DNS ngắn hoạt động: nx-identity:3000. Cross-namespace cần dạng đầy đủ \<svc\>.\<ns\>.svc.cluster.local. Tất cả backend service đều ở nx-backend; frontend service nằm ở nx-app. Các data service được chia qua nx-persistent, nx-broker, và nx-search.

Quản lý Secrets

Staging: Tạo Thủ công qua `create-secrets.sh`

Trên staging, secrets được tạo thủ công bằng script create-secrets.sh trong infrastructure/deployments/staging/manifests/02-secrets/. File YAML template định nghĩa cấu trúc; script hỏi giá trị thực và tạo K8s secret trực tiếp.

bash

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

Production: Sealed Secrets

Sealed Secrets mã hóa secrets phía client để có thể lưu trong Git (chỉ production).

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

Tổ chức Secret

Secret	Namespace	Nội dung
`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`	Cấu hình JAAS Kafka SASL/SCRAM
`nx-kafka-scram-secret`	`nx-broker`	SCRAM username/password
`nx-typesense-secret`	`nx-search`	`TYPESENSE_API_KEY`
`staging-bana-tls`	`nx-internal`	TLS cert và key
`bcr-registry`	`nx-backend` / `nx-app` / `nx-internal`	Container registry pull credentials

INFO

bcr-registry là imagePullSecret cần thiết để pull image từ private registry bcr.bana.com.vn. Nó phải được tạo trong nx-backend, nx-app, và nx-internal và được tham chiếu trong tất cả Deployment spec hoặc ServiceAccount mặc định của namespace.

Cấu hình Pod

Pod tham chiếu cả config dùng chung và config theo service:

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

Phân cấp Cấu hình

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

Các entry sau override entry trước khi key trùng. Điều này cho phép:

nx-shared-config đặt APP_ENV_POSTGRES_HOST cho tất cả service
nx-identity-config có thể override bất kỳ key dùng chung nào nếu cần

Tham khảo Namespace

Namespace	Mục đích	Phạm vi ConfigMap/Secret
`nx-internal`	nginx-ingress, Traefik, cert-manager, API Portal	TLS certs, cấu hình gateway, 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	Cấu hình giám sát

Biến Môi trường

Service đọc cấu hình qua ApplicationEnvironment của IGNIS, vốn nạp mọi biến có tiền tố APP_ENV_. Các key được khai báo dưới dạng hằng số có kiểu trên class EnvironmentKeys - tập key dùng chung nằm trong @nx/core, và mỗi service mở rộng thêm key riêng.

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';
}

Core EnvironmentKeys đã khai báo sẵn các key dùng chung (APP_ENV_POSTGRES_HOST, APP_ENV_POSTGRES_PORT, APP_ENV_POSTGRES_DATABASE, APP_ENV_POSTGRES_USERNAME, …). Đây là cùng một contract dùng trong Docker Compose - chuyển sang K8s chỉ thay đổi giá trị, không thay đổi key.

Nhà cung cấp

Các loại Hóa đơn

Cấu hình ​

Tổng quan ​

Tổ chức ConfigMap ​

ConfigMap Dùng chung ​

Khác biệt ConfigMap Staging vs Production ​

ConfigMap theo Service ​

Ánh xạ DNS từ Docker Compose sang K8s ​

Quản lý Secrets ​

Staging: Tạo Thủ công qua create-secrets.sh ​

Production: Sealed Secrets ​

Workflow (Production) ​

Tổ chức Secret ​

Cấu hình Pod ​

Phân cấp Cấu hình ​

Tham khảo Namespace ​

Biến Môi trường ​

Cấu hình

Tổng quan

Tổ chức ConfigMap

ConfigMap Dùng chung

Khác biệt ConfigMap Staging vs Production

ConfigMap theo Service

Ánh xạ DNS từ Docker Compose sang K8s

Quản lý Secrets

Staging: Tạo Thủ công qua `create-secrets.sh`

Production: Sealed Secrets

Workflow (Production)

Tổ chức Secret

Cấu hình Pod

Phân cấp Cấu hình

Tham khảo Namespace

Biến Môi trường