ConfigMaps & Secrets

Inject configuration and secrets into Node.js pods as environment variables or files without baking values into Docker images.

Recipe

Quick-reference recipe card - copy-paste ready.

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
data:
  LOG_LEVEL: info
  API_BASE_URL: https://api.acme.dev
---
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
type: Opaque
stringData:
  DATABASE_URL: postgres://user:pass@db:5432/app

containers:
  - name: api
    envFrom:
      - configMapRef:
          name: api-config
      - secretRef:
          name: api-secrets

When to reach for this: Every Kubernetes Deployment. Non-secret config in ConfigMap; credentials in Secret (or external secret operator).

Working Example

# k8s/config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
data:
  NODE_ENV: production
  PORT: "3000"
  LOG_LEVEL: info
  FEATURE_EXPORT_CSV: "false"
---

// src/env.ts
import { z } from "zod";
 
const schema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  PORT: z.coerce.number().default(3000),
  LOG_LEVEL: z.enum

What this demonstrates:

• Non-sensitive toggles in ConfigMap
• Secrets as env vars (simple) parsed by Zod at boot
• Downward API POD_NAME for structured logs

Deep Dive

Config vs Secret Decision

Never put secrets in ConfigMap (base64 is not encryption).

File Mount Pattern

volumeMounts:
  - name: config
    mountPath: /app/config
    readOnly: true
volumes:
  - name: config
    projected:
      sources:
        - configMap:
            name: api-config

import { readFileSync } from "node:fs";
 
const jwtSecret = readFileSync("/app/config/JWT_SECRET", "utf8").trim();

Files avoid env var size limits and reduce accidental env logging. App must read files at boot.

External Secrets Operator

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-secrets
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-ssm
    kind: ClusterSecretStore
  target:
    name

Syncs AWS SSM into K8s Secret automatically. See Secrets Managers.

ECS Equivalent

"secrets": [
  {
    "name": "DATABASE_URL",
    "valueFrom": "arn:aws:ssm:us-east-1:123:parameter/prod/api/DATABASE_URL"
  }
]

Cloud Run: --set-secrets DATABASE_URL=api-database-url:latest.

Gotchas

• Secret in image ENV - layer history leak. Fix: orchestrator injection only.
• Logging process.env on boot - credential leak. Fix: log keys only, never values.
• ConfigMap change without rollout - pods keep stale env until restart. Fix: Reloader sidecar or trigger rollout on config change.
• Giant ConfigMap as env - 1 MiB limit per env source. Fix: file mounts or split config.
• Same Secret for dev and prod - blast radius. Fix: namespace-scoped secrets per environment.
• JWT in ConfigMap - wrong store type. Fix: Secret with RBAC limited to service account.

Alternatives

FAQs

Related

• Secrets Managers - SSM and Vault fetch
• Configuration Basics - Zod env module
• Kubernetes Deployment - mount in Deployment
• ECS Fargate & Cloud Run - AWS/GCP secret injection
• Platform Deploy Best Practices - section checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.