Skip to content

Kubernetes config: ConfigMaps, Secrets, namespaces, Helm

The same container image should run unchanged in development, staging and production; what changes is configuration, credentials, and where and how much it is allowed to run. This page covers the Kubernetes objects that carry that difference (ConfigMaps and Secrets), the namespace boundary that separates teams and environments, and Helm, which packages all of these manifests into a versioned, configurable release.

The examples use the invented OrdersPortal application and its orders-api Deployment from the workloads page. The manifests were validated against the Kubernetes 1.37 API schemas with kubernetes-validate. No cluster, kubectl or helm binary was available, so commands are not run here; Helm commands follow the Helm 4 documentation.

Topic What it answers
ConfigMaps How to keep non-secret configuration out of the image.
Secrets What Secrets protect, what they do not, and how to harden them.
Using configuration in Pods Environment variables versus mounted files, and how updates propagate.
Namespaces How to partition a cluster by team or environment.
Quotas limits and access ResourceQuota, LimitRange and namespace-scoped RBAC.
Helm Charts, values and release history with Helm 4.

A ConfigMap stores non-confidential configuration as key-value pairs: single values such as a log level, or whole files such as appsettings.json. Keeping configuration in a ConfigMap rather than in the image means one image serves every environment, and a configuration change does not require a rebuild.

# config.yaml (part 1)
apiVersion: v1
kind: ConfigMap
metadata:
name: orders-api-config
namespace: ordersportal
data:
LOG_LEVEL: info
PAYMENTS_URL: https://payments.example.test
appsettings.json: |
{ "Features": { "GuestCheckout": true } }

You can also create one imperatively, kubectl create configmap orders-api-config --from-literal=LOG_LEVEL=info --from-file=appsettings.json, but a manifest in Git is easier to review and reproduce. A ConfigMap holds at most 1 MiB of data, so large files belong in a volume or an object store.

Setting immutable: true prevents further changes. Immutable ConfigMaps protect against accidental edits and reduce load on the API server because kubelets stop watching them; to change configuration you create a new ConfigMap (for example with a version suffix in its name) and point the Deployment at it, which also triggers a rollout.

Pitfalls:

  • Putting secrets in ConfigMaps. ConfigMaps are readable by anyone with read access to the namespace and are not treated as sensitive anywhere. Use a Secret.
  • Editing live ConfigMaps by hand. The change is lost on the next deploy and Pods may not pick it up anyway (see below).

A Secret holds a small amount of sensitive data, such as a database password, an API token or a TLS key pair. Secrets look like ConfigMaps, with a type and values in data that are base64-encoded. Base64 is an encoding, not encryption: anyone who can read the Secret object can decode it. Write plain text in stringData and the API server encodes it for you.

# config.yaml (part 2) - demonstration only; do not commit real values
apiVersion: v1
kind: Secret
metadata:
name: orders-db
namespace: ordersportal
type: Opaque
stringData:
username: orders_app
password: change-me-in-the-secret-store

Common types are Opaque (arbitrary data), kubernetes.io/tls (certificate and key, used by Ingress and Gateway), kubernetes.io/dockerconfigjson (registry credentials for imagePullSecrets) and kubernetes.io/service-account-token.

What makes Secrets safer than ConfigMaps is how clusters treat them, and that depends on configuration. By default, Secrets are stored unencrypted in etcd. The Kubernetes documentation recommends enabling encryption at rest, granting least-privilege RBAC access to Secrets (remember that anyone who can create a Pod in a namespace can mount any Secret in it), restricting Secret access to specific containers, and considering an external secret store. In practice, teams keep real values out of Git and sync them from a store such as HashiCorp Vault, AWS Secrets Manager, Azure Key Vault or Google Secret Manager with the External Secrets Operator or the Secrets Store CSI Driver, or commit only encrypted values with a tool such as Sealed Secrets or SOPS.

Pitfalls:

  • Committing Secret manifests with real values. Base64 in Git is plain text in Git. Commit references to a secret store instead.
  • Granting list on Secrets. Listing returns every Secret’s contents in the namespace; grant get on named Secrets where possible.

A container consumes a ConfigMap or Secret either as environment variables or as files in a mounted volume. This fragment of the orders-api container spec shows both:

# fragment of the Deployment's container spec
envFrom:
- configMapRef:
name: orders-api-config # LOG_LEVEL and PAYMENTS_URL become env vars
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: orders-db
key: password
volumeMounts:
- name: app-settings
mountPath: /app/config
readOnly: true
# and at Pod level:
# volumes:
# - name: app-settings
# configMap:
# name: orders-api-config
# items:
# - key: appsettings.json
# path: appsettings.json

The two methods differ in how changes arrive. Environment variables are read when the container starts and never change afterwards. Files in a mounted ConfigMap or Secret volume are updated in place by the kubelet after a delay (its sync period plus cache propagation), unless the volume is mounted with subPath, in which case it never updates. Whether the application notices a changed file is up to the application.

The reliable pattern is to treat a configuration change like a code change: change the manifest and restart the Pods. Helm charts often do this automatically by putting a checksum of the ConfigMap in a Pod template annotation, so any configuration change alters the template and triggers a rolling update. Without that, kubectl rollout restart deployment/orders-api restarts the Pods by hand.

Pitfalls:

  • Expecting env vars to update. They do not; a restart is required.
  • Secrets in env vars leaking into logs and crash dumps. Mounted files are harder to leak accidentally; prefer them for high-value credentials.

A namespace is a name scope inside a cluster. Names of namespaced objects (Pods, Services, Deployments, ConfigMaps, Secrets, Roles) must be unique within a namespace, and policies such as quotas and RBAC bindings attach to a namespace. Cluster-scoped objects (nodes, PersistentVolumes, StorageClasses, ClusterRoles, namespaces themselves) belong to no namespace.

Every cluster starts with default (where objects go if you name no namespace), kube-system (control plane and add-ons), kube-public (readable by all clients) and kube-node-lease (node heartbeat Lease objects). Create your own for each team or application rather than using default.

# ns.yaml (part 1)
apiVersion: v1
kind: Namespace
metadata:
name: ordersportal
labels:
team: orders

Work in a namespace with -n ordersportal, see everything with -A, or make it your context default with kubectl config set-context --current --namespace=ordersportal. Services in other namespaces are reachable by DNS as <service>.<namespace>.

Namespaces are an organizational boundary, not a security one by themselves. Network traffic crosses them freely unless NetworkPolicies say otherwise, and nodes are shared. Many organizations run dev and staging as namespaces in one cluster but production in its own cluster, for stronger isolation and a smaller blast radius for cluster upgrades. Deleting a namespace deletes everything in it; if it hangs in Terminating, look for resources with finalizers that their controller can no longer process.

Pitfalls:

  • Everything in default. You lose the ability to apply quotas, RBAC and policies per team.
  • Assuming namespace isolation for untrusted workloads. Use separate clusters or stronger sandboxing for multi-tenant scenarios with untrusted code.

Three namespace-scoped objects turn a namespace into a governed space:

  • A ResourceQuota caps the total that all objects in the namespace may request or create: CPU and memory requests and limits, number of Pods, PersistentVolumeClaims and more. Once a quota covers CPU or memory, every new Pod must declare those values or it is rejected.
  • A LimitRange sets default requests and limits for containers that do not declare them, and can enforce minimum and maximum values. It works hand in hand with a quota, because defaults keep Pods without explicit resources from being rejected.
  • A RoleBinding grants a Role (namespace-scoped permissions) or ClusterRole to users, groups or service accounts within that namespace only.
# ns.yaml (parts 2 and 3)
apiVersion: v1
kind: ResourceQuota
metadata:
name: ordersportal-quota
namespace: ordersportal
spec:
hard:
requests.cpu: "8"
requests.memory: 16Gi
limits.memory: 32Gi
pods: "50"
---
apiVersion: v1
kind: LimitRange
metadata:
name: ordersportal-defaults
namespace: ordersportal
spec:
limits:
- type: Container
defaultRequest:
cpu: 100m
memory: 128Mi
default:
memory: 256Mi

For access, bind the built-in edit or view ClusterRoles to a team group with a RoleBinding in their namespace, and create narrower Roles for CI service accounts. kubectl auth can-i create deployments -n ordersportal --as=system:serviceaccount:ordersportal:deployer checks the result.

Pitfalls:

  • Quota without a LimitRange. Deployments that omit resources fail with “must specify requests” errors that are confusing to application teams.
  • Binding cluster-admin for convenience. Grant namespace-scoped roles; audit ClusterRoleBindings regularly.

Helm is the package manager for Kubernetes. A chart is a folder of templated manifests plus a Chart.yaml (metadata and the chart’s version) and a values.yaml (defaults that users override). Installing a chart creates a release; Helm records every revision of a release so you can see history and roll back. The current major version is Helm 4 (4.3.x in November 2026). Helm 4 keeps compatibility with existing apiVersion: v2 charts but changes some behavior: new releases use server-side apply by default, --atomic was renamed --rollback-on-failure, and the install script is get-helm-4.

A minimal chart for OrdersPortal’s API:

orders-api/
Chart.yaml
values.yaml
values-staging.yaml
templates/
deployment.yaml
service.yaml
_helpers.tpl
Chart.yaml
apiVersion: v2
name: orders-api
description: OrdersPortal orders API
type: application
version: 1.4.0 # chart version
appVersion: "2.4.1" # application version, used as the default image tag
values.yaml
replicaCount: 3
image:
repository: registry.example.test/ordersportal/orders-api
tag: "" # empty means use appVersion
resources:
requests:
cpu: 250m
memory: 256Mi
# templates/deployment.yaml (excerpt)
spec:
replicas: {{ .Values.replicaCount }}
template:
metadata:
annotations:
checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
spec:
containers:
- name: orders-api
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

The checksum/config annotation is the restart-on-config-change pattern from earlier (it assumes the chart also has a templates/configmap.yaml). Typical commands, not run here:

Terminal window
helm lint ./orders-api
helm template orders-api ./orders-api -f orders-api/values-staging.yaml # render locally
helm upgrade --install orders-api ./orders-api \
--namespace ordersportal --create-namespace \
-f orders-api/values-staging.yaml --set image.tag=2.5.0 \
--wait --rollback-on-failure
helm history orders-api -n ordersportal
helm rollback orders-api 3 -n ordersportal

helm upgrade --install is idempotent, so pipelines use it for both first install and later upgrades. Later -f files and --set values override earlier ones. Charts can be shared through OCI registries (helm push and oci:// references) as well as classic chart repositories; check who maintains a third-party chart and pin its version, because public chart catalogs change their terms and image sources over time.

Pitfalls:

  • Rendering secrets from values files in Git. Values end up in the release record stored in the cluster and in your repository. Reference Secrets created by an external secret operator instead.
  • Manual kubectl edit on Helm-managed objects. The next upgrade overwrites the edit, or conflicts with it under server-side apply. Change values and upgrade.
You need Use
Non-secret settings that differ per environment ConfigMap, consumed as env vars or files
Passwords, tokens, TLS keys Secret, populated from an external secret store, with encryption at rest and tight RBAC
Settings that must change without a rebuild but with a controlled restart ConfigMap plus a checksum annotation or rollout restart
Separate teams or environments in one cluster Namespaces with ResourceQuota, LimitRange and RoleBindings
Strong isolation for production A separate cluster
Versioned, parameterized releases of many manifests A Helm chart

Are Kubernetes Secrets encrypted? Not by default. Values are base64-encoded in the API and stored unencrypted in etcd unless encryption at rest is configured. Protection comes from encryption at rest, RBAC, and keeping real values in an external secret store.

A ConfigMap was updated but the application still uses the old value. Why? If it is consumed as environment variables, the values were fixed at container start. If it is mounted as files, the update arrives after the kubelet sync delay, never arrives with subPath, and the application may not reload files. Restart the Pods or use a checksum annotation to trigger a rollout.

What is the difference between a ResourceQuota and a LimitRange? A ResourceQuota limits the namespace’s total consumption and object counts. A LimitRange applies per container or Pod: it sets defaults and enforces minimum and maximum values.

What does helm upgrade --install --rollback-on-failure do? It installs the release if it does not exist or upgrades it if it does, waits for resources to become ready, and rolls back to the last successful revision if the upgrade fails. In Helm 3 the rollback flag was called --atomic.

Senior scenario: OrdersPortal’s database password leaked from a Git repository containing Secret manifests. What do you change? Rotate the credential immediately and remove it from Git history, accepting that it must be treated as compromised anyway. Move the value into a managed secret store and sync it into the cluster with the External Secrets Operator or the CSI driver, so Git holds only references. Enable encryption at rest, restrict get/list on Secrets to the workloads and operators that need them, add secret scanning to CI, and make rotation routine so the next leak has a short lifetime.