Kubernetes ConfigMaps and Secrets

Separate code from deploy-time values

Application images should remain reusable across environments. Put feature settings, endpoint names, log levels, and small text configuration outside the image when they vary by deployment. ConfigMaps are designed for non-confidential key-value data or files. They are not suitable for large datasets, durable application state, or values whose exposure creates harm.

Secrets use a separate Kubernetes object and receive special handling in APIs and volume projection, but their values are often merely base64-encoded in manifests. Encoding makes bytes transportable, not private. Confidentiality depends on cluster encryption configuration, access policy, node and workload security, logging discipline, and any external secret system used by the platform.

Choose an injection method

Environment variables are easy for applications to read but are fixed when the container starts and may appear in process inspection or diagnostics. Mounted volumes can present individual keys as files and may receive updates eventually, though applications must reread or watch them correctly. A subPath mount has different update behavior and should be reviewed carefully.

Map only required keys and use descriptive file paths or variable names. Avoid importing every Secret into every container. Validate required keys at startup and fail with a useful message that names the missing key without printing its value. Do not place secrets in command arguments, annotations, status fields, or error logs.

Control access and source of truth

Use namespace boundaries and least-privilege role rules for reading and modifying Secrets. Restrict who can create workloads under identities that can access them. Admission policy can prevent risky patterns, while audit logs can record access according to platform policy. Service accounts should receive only the values needed by that workload.

Keep secret values out of source repositories and ordinary CI output. If manifests reference an external secret manager, define who owns synchronization, rotation, outage behavior, and deletion. For non-secret configuration in version control, review changes like code and avoid embedding environment-specific credentials in templating files.

Roll out and verify changes

Configuration changes do not always restart Pods. Environment-variable consumers need replacement to see new values. Mounted values may update asynchronously, but the process may cache them. Use versioned names or a template annotation containing a configuration hash when your deployment tool supports that pattern, creating a visible rollout tied to content.

Test a rotation or configuration update in a non-production namespace. Verify old and new instances, readiness, rollback, and what happens when a key is missing or malformed. Keep compatible overlap for credential rotation when the backing service permits it. Never invalidate the old credential before confirming that all intended consumers use the new one.

Rotate a database credential

An API reads its database password from a Kubernetes Secret through an environment variable and must change it without an outage.

1. Confirm the database supports overlapping credentials or create a second credential with the same narrow permissions.
2. Update the approved secret source and synchronize a new version without printing either value in commands or logs.
3. Trigger a controlled Deployment rollout, watch readiness and database authentication errors, and verify every old Pod has terminated.
4. Revoke the prior credential only after the new fleet is healthy, then record the rotation and test the rollback boundary.

Workload configuration inventory

Track each runtime value from source to consumer and update behavior.

• Key purpose, classification, owner, authoritative source, namespace, and consumer identity.
• ConfigMap, Secret, or external-store choice with encryption, access, and audit expectations.
• Injection method, target file or variable, required validation, and sensitive-log exclusions.
• Update propagation, restart trigger, compatibility window, rollback value, and rotation cadence.
• Missing-value test, malformed-value test, access review, and last successful rotation evidence.

Common mistakes

• Calling base64-encoded manifest data encrypted and committing it to a public or broadly readable repository.
• Updating an environment-backed Secret while assuming already running containers receive the new value.
• Granting broad Secret read access because the namespace contains only one application today.

Try one

Sources

• Kubernetes ConfigMaps documentationOfficial Kubernetes reference for injecting non-confidential configuration into workloads.
• Kubernetes Secrets documentationOfficial Kubernetes guidance and cautions for confidential workload data.