Mapping a .env file to Kubernetes
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=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
| .env | ConfigMap | Secret | |
|---|---|---|---|
| Where | a file on disk | Kubernetes API (etcd) | Kubernetes API (etcd) |
| For | local development | non-sensitive config | credentials, keys, certificates |
| Encoding | plain text | plain text | base64 (binary-safe, not encryption) |
| Access control | file permissions | RBAC | RBAC (restrict get/list/watch) |
| Encryption at rest | disk encryption | optional | enable it (KMS envelope encryption recommended) |
| Size limit | none | 1 MiB | 1 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;
liston 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
| Stage | Use |
|---|---|
| laptop | .env (git-ignored) |
| docker compose | .env + env_file: |
| Kubernetes, non-sensitive | ConfigMap |
| Kubernetes, sensitive | Secret + RBAC + encryption at rest |
| GitOps (Argo CD, Flux) | Sealed Secrets or SOPS |
| several clusters or teams | External 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 / envFrom | volume mount | |
|---|---|---|
| Updates when the Secret changes | no, restart pods (kubectl rollout restart) | yes, after a short delay (not with subPath) |
| Visible to child processes | yes, inherited | only if they read the file |
Shows up in crash dumps / /proc/<pid>/environ | yes | no |
| Good for | simple apps reading process.env | TLS 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.