MeteorOps | DevOps Dictionary | Kubernetes ConfigMap

Kubernetes ConfigMap

Kubernetes ConfigMap is a Kubernetes API object that stores non-sensitive configuration data separately from container images and pod definitions. In practical terms, it lets you change application settings, environment-specific values, or config files without rebuilding your application image.

What a ConfigMap does

A ConfigMap gives pods access to configuration values at runtime. You can use it to store values such as:

Application feature flags
Log levels, such as debug, info, or warn
Service hostnames and ports
Runtime settings for frameworks and agents
Small configuration files, such as nginx.conf or app-specific YAML files

This helps teams keep the same container image across dev, staging, and production while changing only the configuration that the app receives in each environment.

How it works

A ConfigMap stores data as key-value pairs. Kubernetes then makes that data available to a pod in one of several ways:

Environment variables: Useful for simple values like APP_ENV=production.
Command-line arguments: Useful when your container entrypoint accepts flags.
Mounted files: Useful for full config files that the application reads from disk.

For example, a ConfigMap might define a log level and an API endpoint. A Deployment can then reference that ConfigMap and pass those values into every pod it creates.

Simple example

A typical ConfigMap might look like this:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_ENV: production
  LOG_LEVEL: info
  API_BASE_URL: https://api.example.com

A pod can then read these values as environment variables:

envFrom:
  - configMapRef:
      name: app-config

With this setup, you can move the same application image between environments and inject different runtime values per cluster or namespace.

Common use cases

Environment-specific application settings: For example, different API URLs for staging and production.
Runtime flags: For example, turning on a feature flag for one namespace before rolling it out wider.
Config files: For example, mounting an NGINX, Fluent Bit, or Prometheus configuration file into a container.
Platform defaults: For example, standard log settings used by many services in the same namespace.
Deployment automation: ConfigMaps are often managed through Helm, Kustomize, GitOps tools, or Terraform workflows such as deploying Kubernetes resources using Terraform.

ConfigMap vs Secret

Use a ConfigMap for non-sensitive data. Do not store passwords, API keys, private tokens, database credentials, or TLS private keys in a ConfigMap.

Use a Kubernetes Secret for sensitive values. Secrets are also Kubernetes API objects, but they are designed for confidential data and can integrate with stronger access controls, encryption at rest, and external secret management systems.

ConfigMap: App settings, config files, flags, hostnames, non-sensitive values.
Secret: Passwords, tokens, certificates, private keys, credentials.

Important limitations

ConfigMaps are not encrypted by default: Treat them as plain configuration, not secure storage.
Large files are a poor fit: ConfigMaps are meant for relatively small configuration data, not large binaries or bulky assets.
Updates may not restart pods: If your application reads config only at startup, you may need to restart pods after changing a ConfigMap.
Environment variable values do not update live: If a pod receives ConfigMap data as environment variables, those values stay fixed until the pod restarts.
Mounted ConfigMap files can update: Kubernetes can update projected files, but application behavior depends on whether the app rereads those files.

Operational notes

In production, teams usually manage ConfigMaps as code. They store them in Git, template them with Helm or Kustomize, and apply them through CI/CD or GitOps pipelines. This gives you version history, review workflows, and repeatable deployments.

If you provision Kubernetes workloads with infrastructure-as-code, ConfigMaps may be managed alongside Deployments, Services, and Ingress objects. The same idea applies when using Kubernetes as a control plane for infrastructure, such as in workflows that deploy AWS resources using Crossplane on Kubernetes.

ConfigMaps also matter during cluster maintenance. Before making platform changes, check workloads that depend on mounted config files or environment-based settings. This is especially useful when planning Kubernetes upgrades for startups, where small teams need predictable rollout and rollback behavior.

Real-world example

Suppose your team runs the same Node.js API in three environments. The container image is identical in all three, but each environment needs different settings:

dev: LOG_LEVEL=debug and API_BASE_URL=https://dev-api.example.com
staging: LOG_LEVEL=info and API_BASE_URL=https://staging-api.example.com
production: LOG_LEVEL=warn and API_BASE_URL=https://api.example.com

Instead of building three different images, you create one image and three ConfigMaps. Each Kubernetes namespace references the correct ConfigMap for that environment.

When to use a ConfigMap

Use a ConfigMap when you need to separate non-sensitive configuration from application code and container images. It is a good fit for values that change by environment, cluster, namespace, or release.

A ConfigMap is not a replacement for a secrets manager, a full configuration service, or application-level dynamic config. For many Kubernetes workloads, though, it is the simplest built-in way to inject runtime configuration cleanly and repeatably.

DevOps Dictionary