compareBy Aliniyaz Mamat · updated

.env files vs Kubernetes Secrets & ConfigMaps

.env vs Kubernetes Secrets: on a laptop your config lives in a .env file; in Kubernetes the same values are split into a ConfigMap (non-sensitive settings) and a Secret (credentials), both injected into pods as environment variables. Your code keeps reading process.env.DATABASE_URL unchanged.

Key takeaways

  • ✓Non-sensitive values (PORT, LOG_LEVEL) → ConfigMap; credentials (DATABASE_URL, JWT_SECRET) → Secret.
  • ✓Secret values are base64-encoded, not encrypted. Anyone allowed to read the Secret can decode it.
  • ✓Real protection: RBAC on Secrets, encryption at rest (ideally envelope encryption with a KMS key), and keeping Secret YAML out of plain git.
  • ✓kubectl create secret generic app-env --from-env-file=.env converts a .env in one command.
  • ✓Environment variables don't update in running pods; mounted Secret files do (except with subPath).

Mapping a .env file to Kubernetes

.env
NODE_ENV=production
LOG_LEVEL=info
PORT=3000
DATABASE_URL=postgres://user:pass@db/app
JWT_SECRET=super-long-secret
apiVersion: v1
kind: ConfigMap
metadata: { name: app-config }
data:
  NODE_ENV: production
  LOG_LEVEL: info
  PORT: "3000"
---
apiVersion: v1
kind: Secret
metadata: { name: app-secrets }
type: Opaque
data:                      # base64 of the values (or use stringData: for plain text)
  DATABASE_URL: cG9zdGdyZXM6Ly91c2VyOnBhc3NAZGIvYXBw
  JWT_SECRET: c3VwZXItbG9uZy1zZWNyZXQ=
deployment.yaml (excerpt)
containers:
  - name: app
    envFrom:
      - configMapRef: { name: app-config }
      - secretRef: { name: app-secrets }

The ENV to Docker converter generates the Secret manifest (Kubernetes output), and the ENV to base64 tool encodes or decodes single values.

.env vs ConfigMap vs Secret

.envConfigMapSecret
Wherea file on diskKubernetes API (etcd)Kubernetes API (etcd)
Forlocal developmentnon-sensitive configcredentials, keys, certificates
Encodingplain textplain textbase64 (binary-safe, not encryption)
Access controlfile permissionsRBACRBAC (restrict get/list/watch)
Encryption at restdisk encryptionoptionalenable it (KMS envelope encryption recommended)
Size limitnone1 MiB1 MiB

Base64 is not encryption

Secrets are base64-encoded so the API can carry arbitrary binary data in YAML and JSON. kubectl get secret app-secrets -o jsonpath='{.data.JWT_SECRET}' | base64 -d prints the value for anyone with read access. To actually protect Secrets:

  • RBAC: only the workloads and people who need a Secret may read it; list on Secrets reveals all values in a namespace.
  • Encryption at rest: configure an EncryptionConfiguration (self-managed) or envelope encryption with your cloud KMS key (EKS, GKE, AKS offer it).
  • Sealed Secrets: encrypt Secret YAML with the cluster's public key so it can be committed for GitOps.
  • External Secrets Operator: sync values from Vault, AWS/GCP/Azure, Doppler or Infisical into Secrets; the source of truth stays outside the cluster.
  • SOPS: encrypt manifests in git with age or a cloud KMS, decrypt in the CD pipeline.

Which approach for which stage

StageUse
laptop.env (git-ignored)
docker compose.env + env_file:
Kubernetes, non-sensitiveConfigMap
Kubernetes, sensitiveSecret + RBAC + encryption at rest
GitOps (Argo CD, Flux)Sealed Secrets or SOPS
several clusters or teamsExternal Secrets Operator + a central secrets manager

Choosing that central store: dotenv vs secrets managers. Full Kubernetes .env example: Kubernetes .env generator.

Environment variables vs mounted files

env / envFromvolume mount
Updates when the Secret changesno, restart pods (kubectl rollout restart)yes, after a short delay (not with subPath)
Visible to child processesyes, inheritedonly if they read the file
Shows up in crash dumps / /proc/<pid>/environyesno
Good forsimple apps reading process.envTLS certs, key files, apps that reload config

Frequently asked questions

Can I use a .env file directly in Kubernetes?

Convert it: kubectl create configmap app-config --from-env-file=.env or kubectl create secret generic app-secrets --from-env-file=.env. Add --dry-run=client -o yaml to get the manifest instead of creating it.

Are Kubernetes Secrets encrypted by default?

Only as far as the underlying storage is encrypted. Kubernetes itself stores Secrets base64-encoded in etcd; enable encryption at rest (preferably envelope encryption with a KMS key) and restrict RBAC to really protect them.

What happens to running pods when I update a Secret?

Environment variables stay as they were until the pod restarts. Mounted files are refreshed automatically. Many teams add a checksum annotation of the Secret to the pod template so every change triggers a rollout.

Should I commit Secret YAML to git?

Not in plain form: base64 is readable by anyone with the repository. Use Sealed Secrets, SOPS or External Secrets Operator instead.

Should everything go into Secrets to be safe?

No. Non-sensitive settings in ConfigMaps are easier to review and debug, and keep the Secret list short, which makes access control meaningful.

Related tools

Continue reading