Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubernetes Secrets: store sensitive data

By updated

Improve this page

Logo Kubernetes

A Secret is a Kubernetes object designed for sensitive data: a password, an API key, a certificate. It takes these values out of the manifest of a Deployment, which is versioned and shared, and keeps them in a separate object that the Pod receives as an environment variable or as a file. In this lesson, you start from a Deployment whose password is written in clear text, you move it into a Secret created on the command line, you prove it from inside the container, then you read the error of a wrong key.

Prerequisites: the demo cluster from First cluster, the lesson Deployments and the lesson ConfigMaps, whose injection mechanisms are the same. All commands are typed in the default namespace.

What you will learn

  • Recognize the flaw of a password written in a manifest
  • Create a Secret on the command line, without writing its value in a versioned manifest
  • Say why base64 is not encryption, and what the Secret type brings anyway
  • Inject a Secret as an environment variable and as a mounted file, and prove it in the container
  • Read in kubectl describe the error of a wrong Secret key
  • Recognize the signs that call for an external secrets manager

What is the problem with a password in a manifest?

A manifest is committed to Git, copied into a ticket, displayed in a terminal. A password that appears in it is found everywhere the manifest goes. Create a Deployment that carries its password in the env field to see the flaw:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: compte
spec:
replicas: 1
selector:
matchLabels:
app: compte
template:
metadata:
labels:
app: compte
spec:
containers:
- name: compte
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sleep", "3600"]
env:
- name: DB_PASSWORD
value: "S3cr3t!P@ss"
EOF
kubectl rollout status deployment/compte
kubectl get deployment compte -o yaml | grep -A1 DB_PASSWORD
deployment.apps/compte created
Waiting for deployment "compte" rollout to finish: 0 of 1 updated replicas are available...
deployment "compte" successfully rolled out
{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"annotations":{},"name":"compte","namespace":"default"},"spec":{"replicas":1,"selector":{"matchLabels":{"app":"compte"}},"template":{"metadata":{"labels":{"app":"compte"}},"spec":{"containers":[{"command":["sleep","3600"],"env":[{"name":"DB_PASSWORD","value":"S3cr3t!P@ss"}],"image":"busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4","name":"compte"}]}}}}
creationTimestamp: "2026-11-11T07:08:16Z"
--
- name: DB_PASSWORD
value: S3cr3t!P@ss

The last command reads the password directly in the Deployment object: anyone who reads the Deployment also reads the password. The grep even shows it twice. The first line is the kubectl.kubernetes.io/last-applied-configuration annotation, where kubectl apply keeps a copy of the applied manifest, password included. After the -- line, the env field shows value: S3cr3t!P@ss in clear text. The value must be moved into a Secret.

How do you create a Secret without writing the password in a manifest?

The kubectl create secret generic command creates a Secret from a file (--from-file) or from a literal value (--from-literal). The file prevents the value from appearing in the shell history, which happens with --from-literal. In practice, the file comes from a password manager or a generator; here, it is written by hand so that the demonstration can be replayed:

Terminal window
printf 'S3cr3t!P@ss' > password.txt
kubectl create secret generic db-secret --from-file=password=password.txt
rm password.txt
kubectl get secret db-secret
kubectl describe secret db-secret
secret/db-secret created
NAME TYPE DATA AGE
db-secret Opaque 1 0s
Name: db-secret
Namespace: default
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
password: 11 bytes

The Secret has the key password and the type Opaque, and describe only shows its size (11 bytes), not its value. This masking only applies to this command: the value can be read in other ways, as the next section shows.

Why is base64 not encryption?

Kubernetes stores the values of a Secret encoded in base64. It is a transport encoding, which lets you fit binary data into YAML or JSON, and it is undone with a single command. Read the Secret you just created:

Terminal window
kubectl get secret db-secret -o jsonpath='{.data.password}'
echo
kubectl get secret db-secret -o jsonpath='{.data.password}' | base64 -d
echo
UzNjcjN0IVBAc3M=
S3cr3t!P@ss

The first command shows the encoded value, UzNjcjN0IVBAc3M=, and the second the decoded value, S3cr3t!P@ss, that of the starting password. Anyone who can read the Secrets of the namespace therefore reads all the passwords.

The Secret is not protected by its encoding, but by what controls access to it: RBAC, that is, the rules that say who is allowed to read what in the cluster. The lesson Protect the Secrets of a Kubernetes cluster (in French) covers RBAC, encryption of data at rest and external managers.

The Secret type still brings three things. It is a distinct object, which RBAC can protect separately from Deployments. describe masks its value. And mounted as a file, it stays in memory rather than on the disk of the node.

How do you inject the Secret into the Deployment?

A Secret is injected like a ConfigMap: as an environment variable with secretKeyRef, or as a file with a volume of type secret. The manifest below replaces the clear-text password of the compte Deployment with a reference to db-secret, and also mounts the Secret in /etc/secret:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: compte
spec:
replicas: 1
selector:
matchLabels:
app: compte
template:
metadata:
labels:
app: compte
spec:
containers:
- name: compte
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sleep", "3600"]
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-secret
key: password
volumeMounts:
- name: secret
mountPath: /etc/secret
readOnly: true
volumes:
- name: secret
secret:
secretName: db-secret
EOF
kubectl rollout status deployment/compte
deployment.apps/compte configured
Waiting for deployment "compte" rollout to finish: 1 old replicas are pending termination...
Waiting for deployment "compte" rollout to finish: 1 old replicas are pending termination...
deployment "compte" successfully rolled out

Prove both sides: the value arrives in the container, and it has left the manifest.

Terminal window
kubectl exec deploy/compte -- printenv DB_PASSWORD
kubectl exec deploy/compte -- ls /etc/secret
kubectl exec deploy/compte -- cat /etc/secret/password
echo
kubectl exec deploy/compte -- grep /etc/secret /proc/mounts
kubectl get deployment compte -o yaml | grep -c 'S3cr3t' || true
S3cr3t!P@ss
password
S3cr3t!P@ss
tmpfs /etc/secret tmpfs ro,relatime,size=4009776k,inode64,noswap 0 0
0

The application receives its password as before, as a variable and as a file, but the manifest of the Deployment no longer holds any trace of it: the last count is 0, last-applied-configuration annotation included, since the second application of the manifest replaced the first.

The file carries the name of the key of the Secret. The /proc/mounts line confirms that it lives on an in-memory file system (tmpfs), mounted read-only (ro), and not on the disk of the node.

Prefer the file to the variable when the application can read a file: an environment variable ends up more easily in a log or an error report.

As with a ConfigMap, a variable is never refreshed after a change of the Secret: only replacing the Pod updates it. The lesson ConfigMaps details it.

Which Secret types exist?

The Opaque type, used above, fits any arbitrary key-value pair. The two other common types impose a structure of keys that Kubernetes checks at creation. The table gives, for each one, the command that creates it (values between angle brackets are to be replaced with yours):

TypeCreation commandUse
Opaquekubectl create secret generic <name> --from-literal=<key>=<value>Passwords, API keys, anything with no imposed shape
kubernetes.io/tlskubectl create secret tls <name> --cert=<file.crt> --key=<file.key>A certificate and its private key, for example for an Ingress
kubernetes.io/dockerconfigjsonkubectl create secret docker-registry <name> --docker-server=<registry> --docker-username=<user> --docker-password=<password>The credentials of a private image registry

What happens when the Secret key is wrong?

As with a ConfigMap, a Pod that references a Secret or a key that cannot be found does not start: it stays in CreateContainerConfigError. Trigger the error with a Pod that asks for the key motdepasse instead of password, then read the diagnosis in kubectl describe. The error is intentional:

Terminal window
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: casse-secret
spec:
containers:
- name: casse-secret
image: busybox:1.38.0@sha256:a46257e06c82ad85242d0d38077d0a52d9896389ca60a1a59d3463db586e5fa4
command: ["sleep", "3600"]
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-secret
key: motdepasse
EOF
kubectl wait --for=jsonpath='{.status.containerStatuses[0].state.waiting.reason}'=CreateContainerConfigError pod/casse-secret --timeout=60s
kubectl get pod casse-secret
kubectl describe pod casse-secret | grep -iE 'CreateContainerConfigError|motdepasse'
pod/casse-secret created
pod/casse-secret condition met
NAME READY STATUS RESTARTS AGE
casse-secret 0/1 CreateContainerConfigError 0 4s
Reason: CreateContainerConfigError
DB_PASSWORD: <set to the key 'motdepasse' in secret 'db-secret'> Optional: false
Warning Failed 0s (x2 over 1s) kubelet spec.containers{casse-secret}: Error: couldn't find key motdepasse in Secret default/db-secret

The filter keeps three lines. Reason: CreateContainerConfigError gives the state of the container, the DB_PASSWORD line shows the faulty reference (the key motdepasse of the Secret db-secret), and the Warning event gives the cause: couldn't find key motdepasse in Secret default/db-secret. This message names the key that cannot be found and the Secret that does not contain it. Compare with the real keys in kubectl describe secret db-secret: the cause is often a typo in the name of the key.

When should you move to an external secrets manager?

A Kubernetes Secret is enough for one application and a small team. Three signs call for an external manager: secrets must be renewed automatically, an audit must trace who reads what, or several clusters must share the same values. Choosing a tool, with the encryption of data at rest and the RBAC that go with it, is covered in Protect the Secrets of a Kubernetes cluster (in French).

Put it into practice

Two labs complete the lesson. The first starts from a Deployment that carries its password in clear text, moves it into a Secret and injects it as a variable and as a file; the validation reads both sides, the value having left the manifest while arriving in the running container. The second makes a ConfigMap and a Secret live together in the same Pod, and the validation checks from inside the container that each value did arrive.

Clean up what you created in the demo cluster:

Terminal window
kubectl delete deployment compte
kubectl delete pod casse-secret
kubectl delete secret db-secret
deployment.apps "compte" deleted from default namespace
pod "casse-secret" deleted from default namespace
secret "db-secret" deleted from default namespace

Key takeaways

  1. A password written in a manifest is found everywhere the manifest goes: it goes into a Secret.
  2. A Secret is created on the command line, from a file or an input, never from a value written in a versioned manifest.
  3. base64 is not encryption: kubectl get secret -o jsonpath then base64 -d returns the value.
  4. What the Secret type brings: a distinct object that RBAC can protect, a display masked by describe, an in-memory mount.
  5. A Secret is injected as a variable (secretKeyRef) or as a file (secret volume), the file carrying the name of the key.
  6. An environment variable is never refreshed; only replacing the Pod updates it.
  7. A Secret or a key that cannot be found blocks the Pod in CreateContainerConfigError, readable in kubectl describe.
  8. Automatic renewal, audit and multi-cluster sharing call for an external secrets manager.

Test your knowledge

Seven questions on the points that cost dearly: what base64 does not do, what gets refreshed, and how to read a wrong key.

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer