Managing environment variables on Kubernetes

Have you ever wondered about the ways in which you can manage environment variables when working with Kubernetes? If so, you have come to the right place!

This article will take you through how to set up and use environment variables in your Kubernetes cluster. I will first create a cluster with Civo, demonstrate how to set environment variables from ConfigMaps, share environment variables securely using Secrets, and finally show you how to use a tool called Doppler to securely store your environment variables.

Prerequisites

• Verified Civo account
• Civo CLI installed
• kubectl installed
• Basic understanding of Kubernetes

Creating a Kubernetes cluster on Civo

You can run every command in this guide on any Kubernetes cluster, including minikube. If you want a real managed cluster to test against, the Civo CLI spins one up in well under two minutes:

1civo kubernetes create env-demo \
2  --size g4s.kube.small \
3  --nodes 1 \
4  --wait --save --switch

The --save --switch flags merge the new kubeconfig and make it your active context, so you can confirm you are talking to the cluster straight away:

1kubectl get nodes

With a cluster in hand, we can start wiring configuration into pods.

Inline env and valueFrom

Start with the simplest case, values written straight into the pod spec. This is fine for genuinely static, non-sensitive values:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web
11  template:
12    metadata:
13      labels:
14        app: web
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          env:
20            - name: HOST_NAME
21              value: "server1.example.com"
22            - name: PORT_NUMBER
23              value: "9001"
24EOF

Confirm the values landed inside the container:

1kubectl exec deploy/web -- printenv | grep -E 'HOST_NAME|PORT_NUMBER'
2HOST_NAME=server1.example.com
3PORT_NUMBER=9001

Inline values do not scale, the same string gets copied into every Deployment that needs it.

More often we want to pull individual values from a ConfigMap or Secret, or from the pod's own metadata, with valueFrom:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web-valuefrom
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web-valuefrom
11  template:
12    metadata:
13      labels:
14        app: web-valuefrom
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          env:
20            - name: LOG_LEVEL                # from a ConfigMap key
21              valueFrom:
22                configMapKeyRef:
23                  name: app-config
24                  key: log_level
25            - name: DB_PASSWORD              # from a Secret key
26              valueFrom:
27                secretKeyRef:
28                  name: db-creds
29                  key: PASSWORD
30            - name: POD_IP                   # from pod metadata
31              valueFrom:
32                fieldRef:
33                  fieldPath: status.podIP
34            - name: CPU_LIMIT                # from the container's resources
35              valueFrom:
36                resourceFieldRef:
37                  containerName: web
38                  resource: limits.cpu
39                  divisor: 1m                 # report millicores, not whole cores
40          resources:
41            limits:
42              cpu: "500m"
43EOF

A few things are happening here:

• configMapKeyRef and secretKeyRef pull a single named key from a ConfigMap or Secret (create those first, we do so in the next two sections).
• fieldRef exposes pod metadata such as the namespace, node name, or pod IP.
• resourceFieldRef exposes the container's own resource requests and limits. There is one sharp edge worth knowing: a CPU resourceFieldRef rounds up to the nearest whole core unless you set a divisor. Without divisor: 1m, a 500m limit is reported as 1. With it, you get the millicore value you expected.

Once app-config and db-creds exist, all four sources resolve inside the pod:

1kubectl exec deploy/web-valuefrom -- printenv | grep -E 'LOG_LEVEL|DB_PASSWORD|POD_IP|CPU_LIMIT'
2CPU_LIMIT=500
3DB_PASSWORD=s3cr3t-p@ss
4LOG_LEVEL=info
5POD_IP=10.244.0.8

All four valueFrom sources resolved, including CPU_LIMIT=500 once divisor: 1m is set.

ConfigMaps (literal, from file, as env, as volume)

ConfigMaps hold non-sensitive configuration.

There are several ways to create and consume them, and the right one depends on whether your app reads config from environment variables or from files on disk.

Create a ConfigMap from literals on the command line:

1kubectl create configmap app-config \
2  --from-literal=log_level=info \
3  --from-literal=feature_flags=beta-ui

Or from a file, where each file becomes a key:

1cat > app.properties <<'EOF'
2log_level=info
3feature_flags=beta-ui
4EOF
5kubectl create configmap app-config-file --from-file=app.properties

Inspect what you created:

1kubectl get configmap app-config -o yaml

Surface every key as an environment variable with envFrom:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web-cm-env
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web-cm-env
11  template:
12    metadata:
13      labels:
14        app: web-cm-env
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          envFrom:
20            - configMapRef:
21                name: app-config
22EOF
23kubectl exec deploy/web-cm-env -- printenv | grep -E 'log_level|feature_flags'
24log_level=info
25feature_flags=beta-ui

Or mount the ConfigMap as files, which is the right choice for whole config files (an nginx.conf, an application.yaml) that the app reads from disk:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web-cm-volume
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web-cm-volume
11  template:
12    metadata:
13      labels:
14        app: web-cm-volume
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          volumeMounts:
20            - name: config-volume
21              mountPath: /etc/app-config
22              readOnly: true
23      volumes:
24        - name: config-volume
25          configMap:
26            name: app-config
27EOF

Each key becomes a file under the mount path:

1kubectl exec deploy/web-cm-volume -- cat /etc/app-config/log_level
2info

One behavioural difference is worth remembering: a mounted ConfigMap updates in place when the ConfigMap changes (after a short kubelet sync), whereas env vars are fixed at pod start.

That difference often decides which method to use.

Secrets, and what base64 does not do

Secrets look a lot like ConfigMaps, with one key difference in how you should think about them. Create one imperatively:

1kubectl create secret generic db-creds \
2  --from-literal=USERNAME=admin \
3  --from-literal=PASSWORD='s3cr3t-p@ss'

Now the most important point in this whole article. The Secret stores values base64 encoded, which is not encryption. Anyone who can read the Secret can decode it instantly:

1kubectl get secret db-creds -o jsonpath='{.data.PASSWORD}' | base64 -d ; echo
2s3cr3t-p@ss

base64 only keeps binary data safe to store as text, it provides zero confidentiality.

Treat a Secret object as plaintext to anyone with read access to it or to etcd. We harden that further down.

Decoding the stored Secret value: base64 is encoding, not encryption.

stringData vs data

When you write Secrets as YAML, prefer stringData so you do not have to base64-encode by hand. Kubernetes encodes it into data for you:

1kubectl apply -f - <<'EOF'
2apiVersion: v1
3kind: Secret
4metadata:
5  name: api-creds
6type: Opaque
7stringData:           # plain text in, encoded at rest by the API server
8  API_KEY: "live_abc123"
9data:                 # this field expects already-base64 values
10  LEGACY_TOKEN: "bGVnYWN5LXRva2Vu"
11EOF

The stringData values are write-only convenience fields. After apply, both keys live under data as base64.

Secret types

Secrets are typed. The type field tells Kubernetes what shape to expect:

• Opaque is the default, arbitrary key/value pairs.
• kubernetes.io/dockerconfigjson holds registry pull credentials (kubectl create secret docker-registry ...).
• kubernetes.io/tls holds a tls.crt and tls.key pair for Ingress and similar (kubectl create secret tls ...).
• kubernetes.io/basic-auth holds username and password keys.

Consuming a Secret: env vars vs mounted files

Consume a Secret either as env vars or as mounted files. As env vars with envFrom:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web-secret-env
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web-secret-env
11  template:
12    metadata:
13      labels:
14        app: web-secret-env
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          envFrom:
20            - secretRef:
21                name: db-creds
22EOF

Mounting as files is generally safer than env vars.

Environment variables can leak into logs, crash dumps, and child processes, whereas a mounted file can be readOnly and is easier to rotate:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: web-secret-volume
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: web-secret-volume
11  template:
12    metadata:
13      labels:
14        app: web-secret-volume
15    spec:
16      containers:
17        - name: web
18          image: nginx:1.27
19          volumeMounts:
20            - name: secret-volume
21              mountPath: /etc/secrets
22              readOnly: true
23      volumes:
24        - name: secret-volume
25          secret:
26            secretName: db-creds
27EOF

When you just want to confirm a Secret's shape without printing its values, describe shows the keys and byte counts only:

1kubectl describe secret db-creds

Hardening native Secrets

We have established that a Secret is plaintext to anyone with read access.

Three native controls tighten that story before you reach for an external tool.

Make ConfigMaps and Secrets immutable

An immutable object cannot be updated, only deleted and recreated.

This prevents accidental changes and lets the kubelet stop watching it, which improves performance on large clusters:

1kubectl apply -f - <<'EOF'
2apiVersion: v1
3kind: Secret
4metadata:
5  name: db-creds-immutable
6type: Opaque
7immutable: true
8stringData:
9  PASSWORD: "s3cr3t-p@ss"
10EOF

After this, an attempt to change the data is rejected by the API server:

1kubectl patch secret db-creds-immutable -p '{"stringData":{"PASSWORD":"new"}}'
2The Secret "db-creds-immutable" is invalid: data: Forbidden: field is immutable when `immutable` is set

An immutable Secret rejecting a value change.

Enable encryption at rest

By default Secrets are stored in etcd as plaintext (base64).

On a self-managed control plane you harden this with an EncryptionConfiguration passed to the API server, so Secrets are encrypted before they hit disk:

1apiVersion: apiserver.config.k8s.io/v1
2kind: EncryptionConfiguration
3resources:
4  - resources:
5      - secrets
6    providers:
7      - aescbc:
8          keys:
9            - name: key1
10              secret: <base64-encoded-32-byte-key>
11      - identity: {}   # allows reading existing unencrypted Secrets during rollout

For real key management, point the kms provider at a KMS plugin instead of holding the key in this file.

On managed offerings the provider handles control-plane encryption for you, so confirm what your platform already does before rolling your own.

On Civo managed Kubernetes you do not edit the API server flags directly, so treat encryption at rest as a "confirm with your platform" item rather than something you configure by hand.

Limit who can read Secrets with RBAC

Read access to Secrets is effectively read access to your credentials, so scope it tightly.

This Role grants get on a single named Secret and nothing else:

1kubectl apply -f - <<'EOF'
2apiVersion: rbac.authorization.k8s.io/v1
3kind: Role
4metadata:
5  namespace: default
6  name: secret-reader
7rules:
8  - apiGroups: [""]
9    resources: ["secrets"]
10    resourceNames: ["db-creds"]   # this one Secret only
11    verbs: ["get"]
12EOF

You can check what a given identity is allowed to do with kubectl auth can-i:

1kubectl auth can-i get secrets --as=system:serviceaccount:default:limited-sa

A correctly scoped Role lets the service account read its one Secret while denying broad access:

1can get secrets/db-creds : yes
2can list ALL secrets     : no
3can get pods             : no

A Role scoped to one Secret name: get on that Secret yes, list all Secrets and get pods no.

Using external secret managers

The primitives get you a long way, but they have limits.

Native Secrets are not encrypted by default, there is no built-in rotation, and there is no single source of truth when you run many clusters or want one canonical store shared with non-Kubernetes systems.

Committing Secret YAML to git is also off the table, since the values are only encoded.

External secret managers close these gaps in different ways. There is no single winner here, so pick based on where you want secrets to live and how you deploy.

• External Secrets Operator (ESO): The most widely adopted option. It runs in the cluster, reads from an external store (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, and more), and materialises the result as a normal Kubernetes Secret your pods consume unchanged. Pick it when your source of truth already lives in a cloud secret manager.
• Sealed Secrets: The kubeseal CLI encrypts a Secret into a SealedSecret that is safe to commit to git; only the in-cluster controller can decrypt it. Pick it when you want secrets in the same repo as your manifests, GitOps-style, with no external store to run.
• HashiCorp Vault: For dynamic secrets, leasing, and fine-grained policy. The Vault Secrets Operator syncs Vault secrets into native Kubernetes Secrets, and a CSI provider mounts them per pod instead. Pick it when you need Vault's policy engine and dynamic secrets.
• Doppler: A hosted secrets platform whose operator syncs a Doppler project into a managed Kubernetes Secret. Pick it when you want a SaaS dashboard, change history, and syncing across environments without running your own store.

Doppler is one option among these. The walkthrough below shows how to wire it up as one concrete example.

How to use Doppler to store environment variables for Kubernetes

Install the Doppler Kubernetes operator:

1kubectl apply -f https://github.com/DopplerHQ/kubernetes-operator/releases/latest/download/recommended.yaml

Next you need a Doppler service token. In the Doppler dashboard, create a project if you do not have one, select the config you want to sync, then open the Access tab and click Generate to create a service token. Copy it when it is shown, you will not see it again. The service tokens docs cover scopes and expiry in more detail.

Store the token as a Secret the operator can read:

1kubectl create secret generic doppler-token-secret \
2  --namespace doppler-operator-system \
3  --from-literal=serviceToken=<paste-service-token>

Tell the operator which Doppler config to sync and what managed Secret to produce:

1kubectl apply -f - <<'EOF'
2apiVersion: secrets.doppler.com/v1alpha1
3kind: DopplerSecret
4metadata:
5  name: dopplersecret-test
6  namespace: doppler-operator-system
7spec:
8  tokenSecret:
9    name: doppler-token-secret
10  managedSecret:
11    name: doppler-test-secret
12    namespace: default
13    type: Opaque
14EOF

Consume the managed Secret like any other. The secrets.doppler.com/reload annotation rolls the Deployment when the synced values change:

1kubectl apply -f - <<'EOF'
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: doppler-test-deployment-envfrom
6  annotations:
7    secrets.doppler.com/reload: 'true'
8spec:
9  replicas: 1
10  selector:
11    matchLabels:
12      app: doppler-test
13  template:
14    metadata:
15      labels:
16        app: doppler-test
17    spec:
18      containers:
19        - name: doppler-test
20          image: alpine:3.20
21          command: ["/bin/sh", "-c", "printenv && sleep 3600"]
22          envFrom:
23            - secretRef:
24                name: doppler-test-secret
25EOF
26kubectl logs deploy/doppler-test-deployment-envfrom

The synced values appear in the container's environment, exactly as if you had created the Secret by hand.

Cleaning up

When you are done experimenting, remove the objects you created and, if you spun one up, the cluster:

1kubectl delete deploy,configmap,secret,dopplersecret --all -n default
2civo kubernetes remove env-demo

Summary

In this article, we have been able to go through how to set up and use environment variables in your Kubernetes cluster. We went from creating a cluster with Civo, demonstrated how to set environment variables from ConfigMaps, store sensitive environment variables securely, and finally showed you how to use Doppler as an example of an external tool to securely store and manage your environment variables.

Hopefully, with this information, you will be able to confidently start working with environment variables in your Kubernetes application.