Kubernetes Configuration Definition

Kubernetes Configuration Definition is the precise characterization of the ConfigMap object as the formal representation of non-sensitive configuration data within the cluster's API, structured as a set of key-value pairs, or embedded file contents, that can be projected into a Pod independently of the container image that consumes it. A ConfigMap is not itself configuration applied to anything by default; it is a passive data record that becomes active configuration only once explicitly referenced from a Pod's environment variables, command-line arguments, or mounted volumes.

Formal Structure

The data and binaryData Fields

A ConfigMap's content is formally carried in one of two mutually applicable maps: data, holding UTF-8 string values, and binaryData, holding base64-encoded binary content, together forming the complete set of key-value entries the object exposes.

apiVersion: v1
kind: ConfigMap
metadata:
  name: codartium-app-config
data:
  LOG_LEVEL: "info"
  application.yaml: |
    server:
      port: 8080

Namespaced Scope

A ConfigMap is formally a namespaced resource; a Pod may reference only ConfigMaps residing in its own namespace, meaning configuration intended for consumption across multiple namespaces must be duplicated into each, since no cross-namespace reference mechanism exists for it.

Formal Consumption Mechanisms

Environment Variable Injection

A single key can be projected into a container as one environment variable via valueFrom.configMapKeyRef, or an entire ConfigMap's keys can be bulk-imported as environment variables via envFrom.configMapRef, with keys formally becoming variable names directly.

env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: codartium-app-config
        key: LOG_LEVEL
envFrom:
  - configMapRef:
      name: codartium-app-config

Volume Projection

A ConfigMap can be mounted as a volume, formally materializing each of its keys as a separate file within the mount path, with the file's name equal to the key and its contents equal to the corresponding value, a mechanism distinct from and independent of environment variable injection.

volumes:
  - name: config-volume
    configMap:
      name: codartium-app-config
containers:
  - name: app
    volumeMounts:
      - name: config-volume
        mountPath: /etc/codartium

Formal Update Propagation Behavior

Environment Variables Are Fixed at Start

Values injected as environment variables are formally resolved once, at container start, and remain fixed for that container's lifetime; updating the referenced ConfigMap has no effect on an already-running container's environment until it is restarted.

Mounted Volumes Update Asynchronously

Values projected as a mounted volume are formally kept synchronized with the underlying ConfigMap by the kubelet on a periodic basis, meaning a running container observes updated file contents without requiring a restart, subject to a defined propagation delay rather than being instantaneous.

Immutability

The immutable Field

Setting immutable: true on a ConfigMap formally forbids any subsequent modification to its data or binaryData fields; any change to configuration under this mode requires creating a new ConfigMap object rather than editing the existing one, and this restriction additionally permits the kubelet to skip watching the object for changes.

apiVersion: v1
kind: ConfigMap
metadata:
  name: codartium-app-config-v2
immutable: true
data:
  LOG_LEVEL: "warn"

Formal Distinction from Secret

Structurally Identical, Semantically Distinct

A ConfigMap and a Secret formally share the same key-value structure and the same consumption mechanisms, environment variables and volume mounts, but are formally distinguished by intended content and handling: a ConfigMap's values are treated as non-sensitive and stored as plain text, while a Secret's values are treated as sensitive, base64-encoded in storage, and subject to additional access-control and encryption-at-rest considerations.

kubectl create configmap codartium-app-config --from-literal=LOG_LEVEL=info
kubectl get configmap codartium-app-config -o yaml
kubectl describe configmap codartium-app-config

Why Configuration Is Externalized This Way

Representing configuration as an independent API object, rather than embedding it in a container image, is what formally allows the same image to be deployed unchanged across multiple environments; only the referenced ConfigMap, not the image itself, needs to differ between a development, staging, and production deployment of the identical workload.