Kubernetes ConfigMaps and Secrets Guide for Practical Teams

Configuration should be separate from container images

Container images should package application code and runtime dependencies. Environment-specific settings should live outside the image so the same build can run in development, staging, and production. Kubernetes ConfigMaps and Secrets provide standard ways to inject configuration into pods.

A ConfigMap stores non-sensitive configuration such as feature flags, URLs, log levels, or application settings. A Secret stores sensitive values such as tokens, passwords, and private keys. The distinction matters because teams should review, access, rotate, and protect these values differently.

Use ConfigMaps for ordinary settings

ConfigMaps can be exposed as environment variables, command arguments, or mounted files. Environment variables are simple for small settings. Mounted files work better for larger config files or apps that already read configuration from disk. Choose the approach that makes the application behavior obvious.

Config changes need rollout strategy. Some apps read environment variables only at startup. Updating the ConfigMap may not change running pods until they restart. If the application supports live reload from mounted files, test that behavior carefully. Surprise partial reloads can be worse than planned restarts.

• Use ConfigMaps for non-sensitive environment-specific settings.
• Use Secrets for credentials and sensitive material.
• Know whether config changes require pod restarts.
• Keep config names and keys consistent across environments.

Secrets need more than base64

Kubernetes Secrets are base64-encoded by default, not magically encrypted in every context. Cluster configuration, etcd encryption, RBAC, namespace boundaries, audit logging, and external secret managers all affect real security. Do not treat a Secret manifest committed to a repository as safe just because the value is encoded.

Many production teams use external secret systems and sync values into Kubernetes at deploy time. This can improve rotation, access control, auditability, and separation of duties. Whatever approach is used, secrets should not appear in logs, container images, shell history, or public CI output.

Rotation should be designed early

Secret rotation is painful when apps assume credentials never change. Design applications to reconnect, reload, or restart cleanly when secrets rotate. Use overlapping credentials where possible so the old and new values work during the transition. Document which deployments depend on each secret.

For global systems, rotation may affect users in many regions. Coordinate database credentials, API keys, certificate renewal, and service tokens with monitoring and rollback plans. A secret update is a production change.

Configuration is part of release safety

Many outages come from bad configuration rather than bad code. Review ConfigMap and Secret changes, validate required keys, and make startup fail clearly when critical configuration is missing. Good configuration management makes deployments repeatable and reduces the chance that staging and production drift into different realities.

Audit who can read and change values

Configuration access should follow ownership. Developers may need to edit non-sensitive settings, while production secrets should have tighter controls and audit trails. Review RBAC regularly, especially for shared namespaces. A secure configuration process protects both the application and the people responsible for operating it.