Master Kubernetes ConfigMap & Secret: From Basics to Production‑Ready GitOps

1. Why Need ConfigMap and Secret?

1.1 Traditional configuration management pain points (real production view)

Before containerization, configuration was typically stored as hard‑coded values in code or images, manually edited per environment, and sensitive data like passwords or tokens appeared in plain text in Git repositories or CI logs.

Configuration hard‑coded in code or image

Multiple environments require manual file edits

Passwords/Tokens in plain text in Git or CI logs

# Typical anti‑example
ENV=prod
DB_PASSWORD=123456
REDIS_HOST=10.0.0.12

Production risks :

Changing config requires rebuilding images → high release cost

Manual config changes cause environment drift

A single Git leak exposes all credentials

1.2 Kubernetes standard solution

Kubernetes solves these problems with ConfigMap + Secret at the architectural level:

Decouple configuration from image

Same image, different configs for multiple environments

Configuration can be changed independently

Sensitive data isolated and managed securely

One‑line summary: Images are immutable, configuration evolves.

2. ConfigMap: Standard containerized solution for non‑sensitive configuration

2.1 What ConfigMap is

Kubernetes native object

Stores non‑sensitive configuration

Exists as key‑value pairs or files

Stored in etcd in plain text

2.2 Four common ways to create ConfigMap (production‑ready)

# 1️⃣ CLI
kubectl create configmap app-config \
  --from-literal=APP_ENV=prod \
  --from-literal=APP_COLOR=blue

# 2️⃣ From file
kubectl create configmap nginx-config \
  --from-file=nginx.conf

# 3️⃣ From directory (recommended)
kubectl create configmap app-config-dir \
  --from-file=conf/

# 4️⃣ YAML (GitOps / Helm required)
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  application.yml: |
    server:
      port: 8080
    logging:
      level:
        root: INFO

2.3 Three ways to use ConfigMap (pros & cons)

Method 1: Environment variables (❌ not recommended for hot update)

envFrom:
- configMapRef:
    name: app-config

Production note : ConfigMap updates do not refresh env variables; pod must be restarted.

Method 2: Command‑line arguments (rare)

args:
- "--spring.config.location=/etc/config/application.yml"

Method 3: File mount (⭐ production preferred)

volumes:
- name: config
  configMap:
    name: app-config

volumeMounts:
- name: config
  mountPath: /etc/config
  readOnly: true

✅ Supports hot update, ❌ Application must reload itself.

3. Secret: Minimum security line for sensitive data

3.1 A common misconception

Secret ≠ encryption

Secret is only Base64‑encoded

etcd stores it in plain text by default

Access to etcd gives all passwords

3.2 Secret types

Opaque – generic password / token

kubernetes.io/tls – HTTPS certificate

dockerconfigjson – image‑registry credentials

service-account-token – SA token

3.3 Creating and using Secret

kubectl create secret generic db-secret \
  --from-literal=DB_USER=admin \
  --from-literal=DB_PASSWORD=strong-password

env:
- name: DB_PASSWORD
  valueFrom:
    secretKeyRef:
      name: db-secret
      key: DB_PASSWORD

Or file mount:

volumes:
- name: secret
  secret:
    secretName: db-secret
    defaultMode: 0400

4. ConfigMap / Secret injection architecture (Mermaid diagrams)

4.1 Pod configuration injection path

4.2 GitOps configuration flow model

4.3 External Secret management (production recommended)

5. Real‑world production pitfalls

Case 1: ConfigMap changed but application not refreshed

Symptoms : kubectl apply succeeds, pod does not restart, application still uses old config.

Root cause : Application does not watch file changes; Spring Boot does not reload by default.

Solution : Use Spring Cloud @RefreshScope, a sidecar reloader (e.g., reloader), or force a rolling restart of the Deployment.

Case 2: Secret leaked into logs, causing an incident

Incident : Java printed environment variables, logs collected by ELK, DB password exposed.

Improvement : Prohibit printing env, mount Secret only as files, apply log redaction and strict RBAC.

Case 3: Multiple applications sharing a ConfigMap, causing pollution

Anti‑pattern : A single common-config used by many apps.

Correct approach : One ConfigMap per application, or use subPath to isolate files.

6. Production‑grade best‑practice summary

6.1 Security baseline (must‑do)

Enable etcd encryption

Apply minimal‑permission RBAC for Secrets

Prohibit plain‑text Secrets in Git repositories

Rotate credentials regularly

6.2 Configuration evolution strategy (strongly recommended)

Version ConfigMap

Do not overwrite old configuration

Trigger upgrades via Deployment

app-config-v2

6.3 Engineering recommendations

Multi‑environment: Kustomize

Templating: Helm

GitOps: ArgoCD

Key management: Vault / SealedSecrets

7. Final checklist (release‑grade)

✅ Config and image fully decoupled ✅ ConfigMap only for non‑sensitive data ✅ Secret never in code or logs ✅ etcd encrypted ✅ Configurable rollback ✅ Change audit ✅ Credential rotation policy

Conclusion

ConfigMap and Secret are not just YAML tricks; they are architectural capabilities. When configuration is treated as a first‑class citizen, Kubernetes truly reaches production maturity.