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.
Topics on this page
Section titled “Topics on this page”| 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. |
ConfigMaps
Section titled “ConfigMaps”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: v1kind: ConfigMapmetadata: name: orders-api-config namespace: ordersportaldata: 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).
Secrets
Section titled “Secrets”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 valuesapiVersion: v1kind: Secretmetadata: name: orders-db namespace: ordersportaltype: OpaquestringData: username: orders_app password: change-me-in-the-secret-storeCommon 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
liston Secrets. Listing returns every Secret’s contents in the namespace; grantgeton named Secrets where possible.
Using configuration in Pods
Section titled “Using configuration in Pods”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 specenvFrom: - configMapRef: name: orders-api-config # LOG_LEVEL and PAYMENTS_URL become env varsenv: - name: DB_PASSWORD valueFrom: secretKeyRef: name: orders-db key: passwordvolumeMounts: - 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.jsonThe 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.
Namespaces
Section titled “Namespaces”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: v1kind: Namespacemetadata: name: ordersportal labels: team: ordersWork 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.
Quotas limits and access
Section titled “Quotas limits and access”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: v1kind: ResourceQuotametadata: name: ordersportal-quota namespace: ordersportalspec: hard: requests.cpu: "8" requests.memory: 16Gi limits.memory: 32Gi pods: "50"---apiVersion: v1kind: LimitRangemetadata: name: ordersportal-defaults namespace: ordersportalspec: limits: - type: Container defaultRequest: cpu: 100m memory: 128Mi default: memory: 256MiFor 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-adminfor 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.tplapiVersion: v2name: orders-apidescription: OrdersPortal orders APItype: applicationversion: 1.4.0 # chart versionappVersion: "2.4.1" # application version, used as the default image tagreplicaCount: 3image: repository: registry.example.test/ordersportal/orders-api tag: "" # empty means use appVersionresources: 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:
helm lint ./orders-apihelm template orders-api ./orders-api -f orders-api/values-staging.yaml # render locallyhelm 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-failurehelm history orders-api -n ordersportalhelm rollback orders-api 3 -n ordersportalhelm 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 editon Helm-managed objects. The next upgrade overwrites the edit, or conflicts with it under server-side apply. Change values and upgrade.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Kubernetes workloads: Pods and Deployments: the Deployment these objects configure.
- Kubernetes networking: Services, Ingress and Gateway: TLS Secrets on the entry point.
- kubectl command reference
- Docker Compose and environment variables: the single-host equivalent of this configuration model.