3.4. Configuration Data
When to Use It
- When you want only the connection addresses or setting values to differ across development, staging, and production
- When you want to manage passwords without putting them inside the image
- When you do not want to rebuild the image every time a setting changes
Why Configuration Belongs Outside the Image
Putting configuration into a container image means building a new image for each environment.
| Inside the image | Outside it | |
|---|---|---|
| Per-environment deployment | You build separate development and production images | You use the same image |
| Changing a setting | You rebuild the image and redeploy | You change only the value |
| What you tested versus what runs in production | Different images | The same image |
| Passwords | Baked into the image where anyone can see them | Only those with permission can see them |
"What you tested and what runs in production are the same" matters most. With different images, what passed testing can fail in production.
What a ConfigMap Is
It is the resource for holding setting values that do not need to be hidden.
It stores key-value pairs, where a value can be a short string or an entire configuration file.
| Example content | Form |
|---|---|
| Connection address | DB_HOST=db.example.local |
| Log level | LOG_LEVEL=info |
| Feature on or off | FEATURE_NEW_UI=true |
| A whole configuration file | The entire contents of application.yml |
What a Secret Is
It is the resource for holding values that must be hidden. Its structure is the same as a ConfigMap, but it is handled differently.
| ConfigMap | Secret | |
|---|---|---|
| On screen | Shown as is | Masked. You have to select to reveal it |
| Read permission | Included in the view role | Excluded from the view role (see 7.1) |
| Storage format | Plain text | base64-encoded |
| Type distinction | None | Yes (see below) |
A Secret Is Not Encryption
Secrets are not stored encrypted. They are only base64-encoded, and anyone can reverse the encoding.
The protection a Secret provides is this.
| What you get | What you do not get |
|---|---|
| Read permission can be managed separately | Encryption of the value itself |
| Accidental exposure on screen and in logs is reduced | Protection if the store is breached |
| When injected into a pod as a file, it stays in memory only |
So grant Secret read permission only to those who truly need it. Encryption of the cluster store (etcd) is configured separately by operations staff.
The ConfigMap List
Go to Workloads > Config Maps.

| Column | Description |
|---|---|
| Name | The ConfigMap name |
| Namespace | The namespace it belongs to |
| Data | The number of keys it holds |
| Age | Time elapsed since creation |
ConfigMaps and Secrets are namespace-scoped resources. Pods in other namespaces cannot use them. If several namespaces need the same configuration, you have to create it in each.
ConfigMap Detail
Selecting the name shows the keys and values it holds.

- If a value is a long configuration file, the whole content is shown as is.
- The edit button lets you change values.
- Which pods use this ConfigMap is not shown here. Check the environment variables and mounts on the pod detail (see 3.1).
The Secret List
View them under Workloads > Secrets.

The list layout is the same as for ConfigMaps, with an extra Type column. Values are masked by default and are revealed by selecting the eye button.
Secret Types
The type indicates what the Secret is used for. Each type has a fixed set of keys it must hold.
| Type | What it holds | How it is created |
|---|---|---|
Opaque | General secret values. Key names are free | You create it |
kubernetes.io/dockerconfigjson | Registry sign-in information | Used when pulling images |
kubernetes.io/tls | A TLS certificate (tls.crt) and private key (tls.key) | Generated automatically by cert-manager (see 7.3) |
kubernetes.io/basic-auth | A user name and password | Git repository authentication and similar |
kubernetes.io/ssh-auth | An SSH private key | Git access over SSH |
kubernetes.io/service-account-token | A service account token | Generated automatically by the cluster |
helm.sh/release.v1 | Helm release information | Generated automatically by Helm (see 9.1) |
Seeing several helm.sh/release.v1 entries is normal. Helm leaves one per revision.
When a build cannot push an image to the registry, check the account and password in the dockerconfigjson
Secret (see 4.2).
Creating a Secret — Guided Edit
Select the + next to the Secret list title to open the type menu. Choose a type to open an input form made for that type.

| Menu item | Type created | Used for |
|---|---|---|
| Key/value secret | Opaque | Values passed to an application as files or environment variables |
| Image pull secret | kubernetes.io/dockerconfigjson | Authentication to a private image registry |
| Source secret | kubernetes.io/basic-auth | Authentication to a Git server |
| Webhook secret | Opaque (one key, WebHookSecretKey) | Authentication of a webhook call |
| TLS secret | kubernetes.io/tls | The certificate an Ingress serves over HTTPS |
The window has the same tabs as for a Deployment (see 3.2). The Guided Edit tab opens by default.

Enter values in plain text. The Console encodes them in base64 when it saves. If you enter a value that is already encoded, it is encoded twice and the application receives a broken value.
Fields by Type
For all types, fill in Name and Namespace under Basic Info. Both are required.
| Type | Section | Fields |
|---|---|---|
| Key/value secret | Key/Value | Key and Value. Select Add Key/Value to add a row |
| Image pull secret | Registry Credentials | Choose an Authentication Type. For Image registry credentials, enter Registry Server Address, Username, Password, and Email (optional). For Upload configuration file, enter the contents of a docker config file (~/.docker/config.json) |
| Source secret | Git Credentials | Username (optional) and Password or Token |
| Webhook secret | Webhook Key | Webhook Secret Key. A random value is filled in when the window opens |
| TLS secret | TLS Certificate | Certificate, Private Key, and CA Certificate (optional) |
- In Registry Server Address, enter the host name only. Leave out
https://and any path. For more than one registry, select Add Credentials to add a row. - Select Regenerate to replace the Webhook Secret Key with a new value. Use the copy button next to it to copy the value.
- For the TLS certificate and private key, enter PEM text that starts with
-----BEGIN. Append intermediate CA certificates after the server certificate. The private key must not have a passphrase. - For a key/value value, the configuration file, and the three TLS fields, you can select Load from file to load the contents of a file. A file can be up to 750 KiB.
- If you load a file that is not text (a keystore, for example) into a key/value secret, the Console saves it unchanged. That field is then locked, so edit the value in the YAML Edit tab.
If a required value is empty, a message appears and the Secret is not saved. The Secret is also not saved if the same key or the same registry server appears twice. The Secret is also not saved if the configuration file is not valid JSON. A TLS field shows a warning if the value is not PEM or is already base64-encoded. This warning does not block saving, so check the value yourself.
Editing an Existing Secret
Select the edit button on the Secret detail to open the same form. The Console chooses the form from the type of the Secret. Existing values are shown decoded as plain text.
A Secret that is not one of the five types above (kubernetes.io/ssh-auth, kubernetes.io/service-account-token,
and others) has no Guided Edit tab. Edit it in the YAML Edit or Form Edit tab.
Two Ways to Attach Them to a Pod
| Method | Description | When it fits |
|---|---|---|
| Environment variables | Passes keys as environment variable names | When there are only a few values |
| Volume mount | Turns keys into files and attaches them to a directory | When a whole configuration file is needed |
The environment variable method splits into two.
| Method | Behavior |
|---|---|
| Specifying keys one at a time | You can pick only the keys you want and rename them |
| Injecting everything | Every key in the ConfigMap becomes an environment variable |
You can check which ConfigMaps and Secrets are attached, and by which method, on the pod detail screen.
Creating and Attaching — YAML
Creating a ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
namespace: my-app
data:
LOG_LEVEL: "info" # a single-value entry
MAX_CONNECTIONS: "50"
application.yaml: | # putting in a whole file
server:
port: 8080
logging:
level: info
All values are written as strings. Writing the number 50 without quotes is rejected on apply.
Several lines after | become the contents of a single file.
Creating a Secret
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
namespace: my-app
type: Opaque
stringData: # written in plain text and converted on save
username: appuser
password: "s3cr3t-p@ssw0rd"
Use stringData. With data you have to encode values in advance, and if you forget and enter plain text the
application receives a broken value. stringData lets Kubernetes do the conversion for you.
When you create a Secret with Guided Edit in the Console, this conversion happens automatically, so you only enter the value (see "Creating a Secret — Guided Edit" above).
Method 1 — Injecting as Environment Variables
Pick keys and give them names.
containers:
- name: app
image: registry.example.com/my-app:1.0
env:
- name: LOG_LEVEL # the name to use in the container
valueFrom:
configMapKeyRef:
name: app-config # the ConfigMap name
key: LOG_LEVEL # the key inside it
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-credentials
key: password
With many keys, inject everything. The ConfigMap key names become the environment variable names as they are.
envFrom:
- configMapRef:
name: app-config
- secretRef:
name: db-credentials
When injecting everything, the key names must be usable as environment variables. A key containing a dot, such as
application.yaml, cannot become an environment variable and is silently dropped. Use the volume method below for
file-like values.
Method 2 — Attaching as Files
containers:
- name: app
image: registry.example.com/my-app:1.0
volumeMounts:
- name: config # must match the name under volumes below
mountPath: /etc/app # the files are created in this directory
readOnly: true
volumes:
- name: config
configMap:
name: app-config
This creates one file per key name under /etc/app/. In the example above, three files appear:
LOG_LEVEL, MAX_CONNECTIONS, and application.yaml.
You can also pick only the keys you need and rename the files.
volumes:
- name: config
configMap:
name: app-config
items:
- key: application.yaml
path: config.yaml # created as /etc/app/config.yaml
Secrets work the same way, using secret instead of configMap and secretName instead of name.
volumes:
- name: creds
secret:
secretName: db-credentials
defaultMode: 0400 # readable by the owner only
Narrow the permissions when attaching credentials as files. Without a setting, they are created as 0644 and can
be read by others besides the owner.
Cautions When Mounting
Existing contents of the directory given in mountPath are hidden. For example, attaching a ConfigMap at
/etc/nginx makes every file under /etc/nginx that came with the image invisible. To replace only one file,
specify just that file.
- name: config
mountPath: /etc/nginx/nginx.conf
subPath: nginx.conf # overwrites only this one file
However, a file attached with subPath is not refreshed when the ConfigMap changes. The pod has to be restarted
for it to take effect. Read this together with "What to Do After Changing a Value" below.
What to Do After Changing a Value
Not knowing this part is a frequent cause of "I changed the setting but it did not take effect".
| Attachment method | Whether a value change takes effect |
|---|---|
| Environment variables | It does not. The pod has to be restarted |
| Volume mount | The file contents change within about a minute. The application still has to reread the file for it to apply |
Environment variables do not take effect because they are values passed once when the process starts. The environment variables of a running process cannot be changed from outside.
To be sure it takes effect, restart the corresponding Deployment (see 3.2).
Cautions When Reverting
ConfigMaps and Secrets have no version history. Editing one erases the previous value.
Rolling back a Deployment does not revert the ConfigMap contents (see 3.2). A rollback reverts only the pod template, and the template records only "which ConfigMap to use".
Do one of the following before editing a setting.
| Method | Description |
|---|---|
| Copy the current content | Copy the YAML from the detail screen and keep it as a file |
| Put a version in the name | Create app-config-v2 and change the reference in the deployment definition |
With the second method, a rollback reverts the reference too, so the configuration is restored as well.
Cautions While Working With Them
- Do not rename them. Pods reference them by name. Renaming stops the pods from starting.
- Check whether a key is in use before deleting it. A pod referencing a missing key cannot start.
- If a value needs line breaks, use multi-line notation in the YAML editor.
- A single resource can hold about 1MB. Put large files on a volume (see 6.1).
- Do not write Secret values into application logs. Logs are seen by many people and are included in diagnostic material (see 2.3).