Chapter 8: Configuring applications with ConfigMaps and Secrets

Introduction

This chapter introduction previews configuring applications through pod manifests or referenced resources and exposing pod metadata to containers.

8.1 Setting the command, arguments, and environment variables

The section shows how a container image supplies application configuration defaults and explains that a Kubernetes pod manifest can override them.

• Container image configuration methods: Describe how a Dockerfile supplies a container's command, arguments, environment variables, and configuration files.
  Why it matters: These image settings are the defaults that the pod configuration may replace.
• Pod manifest configuration overrides: Explain that the command, arguments, and environment variables defined in an image are defaults that Kubernetes can override in a pod manifest, using the Kiada changes as examples.
  Why it matters: The same image can run with different settings supplied by its pod manifest.

Key terms: ENTRYPOINT, CMD, ENV, COPY, Dockerfile, defaults, pod manifest, --listen-port, INITIAL_STATUS_MESSAGE

8.1.1 Setting the command and arguments

This section explains how a pod manifest sets a container’s command and arguments, and how those settings relate to Dockerfile defaults.

• Command and argument mapping: Explain how the pod manifest’s command and args fields correspond to Dockerfile ENTRYPOINT and CMD, and how their arrays form the command run in the container.
  Why it matters: This mapping lets you work out what a container will run from its image and pod manifest.
• Independent command and argument overrides: Describe how changing command or args in the pod manifest overrides the corresponding Dockerfile default, using the Kiada profiling and listen-port examples.
  Why it matters: You can adjust how an image starts without modifying its Dockerfile and rebuilding it.
• Quoting ambiguous YAML values: State why some values in a YAML command array need quotes, including numbers and words that YAML can interpret as Boolean values.
  Why it matters: Quoting ambiguous values preserves the intended command arguments.

Key terms: ENTRYPOINT, CMD, command, args, --cpu-prof, --heap-prof, YAML parser, command array, quotes

8.1.2 Setting environment variables in a container

This subsection shows how to set environment variables for individual containers, reference them in a pod manifest or shell command, and configure a pod’s internal hostname and FQDN.

• Per-container environment settings: Describe how to set literal environment variable values in a container’s pod manifest and why the settings are specified for each container rather than for the whole pod.
  Why it matters: These rules let you put application settings in the right container and avoid YAML interpreting a value as the wrong type.
• Manifest variable reference rules: Explain when Kubernetes resolves a $(VAR_NAME) reference inside another environment variable and what happens when it cannot resolve one.
  Why it matters: It explains why a reference to a variable from the container image can appear literally in the application’s output.
• Command versus shell references: Distinguish Kubernetes variable references in command and args from variable expansion performed by a shell.
  Why it matters: The distinction helps you choose a reference that will actually expand when starting a container.
• Pod hostname and internal FQDN: Describe how hostname and subdomain affect a pod’s internal FQDN and state the DNS limitation noted here.
  Why it matters: A pod’s internal name and a DNS-resolvable address are not necessarily the same thing.

Key terms: env field, environment variable, pod manifest, $(VAR_NAME), $$(VAR_NAME), command, args, $VAR_NAME, ${VAR_NAME}, hostname

8.2 Using a ConfigMap to decouple configuration from the pod manifest

This section explains why moving environment-specific configuration from a pod manifest into a ConfigMap makes the pod definition reusable.

• ConfigMap configuration decoupling: Explain why hardcoding configuration in a pod manifest can require different manifests for different environments, and how placing that configuration in a ConfigMap referenced by the pod allows the same pod definition to be reused.
  Why it matters: Separating configuration lets you avoid maintaining a different pod manifest for each environment.

Key terms: pod manifest, ConfigMap object, decouple the configuration

8.2.1 Introducing ConfigMaps

Introduces ConfigMaps as reusable configuration objects that pods can consume without embedding environment-specific settings in their manifests.

• ConfigMap entries and references: Describe a ConfigMap as a Kubernetes API object containing key–value pairs, and explain how pods can reference its entries.
  Why it matters: This establishes what configuration a ConfigMap holds and how pods can share it.
• Container access to ConfigMaps: Explain how ConfigMap entries reach containers without requiring the application to read the Kubernetes REST API, and describe the stated connection to command-line arguments.
  Why it matters: The application can receive configuration through familiar container interfaces rather than depending on the Kubernetes API.
• Environment-specific configuration separation: Explain how separate ConfigMap manifests let the same pod manifest run with different configuration in different environments.
  Why it matters: You can vary configuration by environment without maintaining a different pod manifest for each one.

Key terms: ConfigMap, key–value pairs, Kubernetes REST API, environment variables, configMap volume, command-line argument, ConfigMap manifests, pod manifest, ConfigMap name

8.2.2 Creating a ConfigMap object

This section shows how to create ConfigMaps from literals, manifests, and files, then inspect how their entries are represented.

• ConfigMap creation methods: Describe how to create a ConfigMap with kubectl or a YAML manifest, and how to supply one or more entries from literals or files.
  Why it matters: These options let you choose how to supply configuration entries when creating the object.
• Generated ConfigMap manifests: Explain how the file-based create command can generate a YAML manifest without creating the ConfigMap in the cluster.
  Why it matters: Generating a manifest lets you keep the configuration definition with your other application manifests.
• Text and binary entries: Distinguish how text and non-UTF-8 file contents appear in a ConfigMap manifest.
  Why it matters: This explains why entries generated from different files look different in the manifest.
• Manifest readability and inspection: Explain how trailing whitespace affects a file-derived ConfigMap entry’s readability, and describe how to display ConfigMap contents with kubectl.
  Why it matters: Clean source files produce easier-to-edit manifests, and inspecting the YAML lets you check the resulting entries.

Key terms: ConfigMap, kubectl create configmap, --from-literal, --from-file, --from-env-file, kubectl apply, --dry-run, -o yaml, ConfigMap manifest, version control system

8.2.3 Injecting ConfigMap values into environment variables

This section shows how to inject individual or entire ConfigMap entries into a container’s environment and explains naming, missing-reference, and precedence behavior.

• Single ConfigMap entry injection: Explain how a container environment variable obtains its value from one ConfigMap entry instead of a fixed value.
  Why it matters: This lets a pod obtain a particular setting from a ConfigMap rather than hard-code it in the pod manifest.
• Missing ConfigMap reference behavior: Distinguish what happens to a container when its referenced ConfigMap or key is missing, depending on whether the reference is optional.
  Why it matters: Optionality determines whether an absent configuration value merely goes unset or prevents the affected container from starting.
• Whole ConfigMap environment injection: Explain when and how envFrom injects an entire ConfigMap, including its effect on environment variable names.
  Why it matters: Whole-map injection is convenient, but the ConfigMap keys must suit the names the application expects.
• Combined ConfigMap value precedence: Describe how entries from multiple ConfigMaps can be combined and which values win when names overlap.
  Why it matters: These precedence rules help predict the value a container receives when configuration sources overlap.

Key terms: env, valueFrom, ConfigMap, name, key, optional, configMapKeyRef, configMapRef, envFrom, prefix

8.2.4 Updating and deleting ConfigMaps

This section explains how to edit and delete ConfigMaps, why updates can leave pods with different configurations, and how immutable ConfigMaps prevent changes.

• ConfigMap update methods: Describe how to update a ConfigMap by changing and reapplying its manifest or by editing the API object directly with kubectl edit.
  Why it matters: These are two ways to make a configuration change in the cluster.
• Configuration differences after updates: Explain why changing a ConfigMap used for environment variables can leave application instances running with different configurations.
  Why it matters: A ConfigMap change can make otherwise similar pods behave differently.
• Immutable ConfigMap behavior: Explain what marking a ConfigMap immutable prevents and why the section recommends it for stable configuration.
  Why it matters: Immutability guards against accidental configuration changes and avoids unnecessary change notifications.
• Deletion effects on containers: Describe what happens to running pods after their ConfigMap is deleted and what can happen when their containers restart.
  Why it matters: A deleted ConfigMap may cause a failure later rather than immediately.

Key terms: ConfigMap, kubectl apply, kubectl edit, environment variables, containers, immutable ConfigMap, data, binaryData, API server, kubectl delete

8.3 Using Secrets to pass sensitive data to containers

The section explains why sensitive application data should use Secrets rather than ConfigMaps.

• Secrets for sensitive data: Explain why credentials and encryption keys should be stored in Secrets rather than ConfigMaps.
  Why it matters: Choosing the right object helps keep sensitive configuration separate from ordinary configuration.

Key terms: ConfigMaps, Secrets, sensitive data

8.3.1 Introducing Secrets

Introduces Secrets by comparing their fields with ConfigMaps and explaining why Kubernetes treats Secret data differently.

• Secret data fields: Explain how a Secret’s data and stringData fields compare with ConfigMap fields, and what happens to Secret values when they are read back or injected into a container.
  Why it matters: This explains why a Secret’s manifest can look different from both the retrieved object and the value the application receives.
• Sensitive data handling: Justify storing sensitive data in Secrets rather than ConfigMaps using the Kubernetes handling described here.
  Why it matters: The storage and distribution differences explain the section’s recommendation to use Secrets for sensitive values.
• Built-in Secret types: Describe what a Secret’s type field is for and why a Secret using a built-in type must meet that type’s requirements.
  Why it matters: A built-in type tells Kubernetes components what shape of Secret data to expect.

Key terms: Secret, ConfigMap, data, binaryData, stringData, Base64-encoded, Secrets, ConfigMaps, worker nodes, sensitive data

8.3.2 Creating a Secret

This section shows how to create several types of Kubernetes Secrets, enter their values, and reference a registry pull Secret from a pod.

• Secret creation and manifest safety: Explain how to create a generic Secret directly with kubectl or from a YAML manifest, and why storing Secret manifests in version control is discouraged.
  Why it matters: The way you create and store a Secret affects whether sensitive configuration is exposed.
• Plain text Secret entries: Describe how stringData lets you enter plain text Secret values and what appears when you read the Secret back.
  Why it matters: This explains why values entered as readable text look different when the Secret is retrieved.
• TLS certificate Secret creation: Describe what the TLS Secret for the Envoy proxy contains and how its inputs are supplied.
  Why it matters: The example shows a Secret type suited to certificate and private-key material.
• Private registry pull Secrets: Explain why a pod pulling a private image needs a registry Secret and where the pod references it.
  Why it matters: Without the registry credentials, Kubernetes cannot start a pod whose image is private.

Key terms: generic secret, kubectl create secret, YAML manifest, stringData, data, Base64-encoded values, tls Secret, certificate, private key, kiada-tls

8.3.3 Using Secrets in containers

This section shows how to expose Secret values as container environment variables and explains why doing so can risk exposing sensitive data.

• Secret environment variable injection: Describe how to inject one Secret entry or an entire Secret into a container’s environment variables using the fields named in this section.
  Why it matters: These two options let you choose between exposing one Secret entry and exposing the whole Secret.
• Environment variable exposure risks: Explain why injecting Secrets into environment variables can expose them, and state the safer alternative recommended here.
  Why it matters: A supported injection method is not necessarily the safest way to pass sensitive data to an application.

Key terms: Secret, valueFrom.secretKeyRef, envFrom, secretRef, environment variables, error reports, application log, child processes, secret volume

8.3.4 Understanding why Secrets aren’t always secure

This section explains why Kubernetes Secrets can still expose sensitive data and what protections they do not provide on their own.

• Encoding versus encryption: Distinguish Base64 encoding in a Secret manifest from encryption, and explain what someone with access to the Secret can do with its values.
  Why it matters: Encoding must not be mistaken for protection against someone who can read the Secret.
• Secret storage at rest: Explain where Kubernetes stores Secrets and what risk exists if storage encryption is not enabled.
  Why it matters: Using a Secret does not by itself protect the stored data from direct access to etcd or its disk.
• API and pod exposure: Describe how permissions and a compromised application can each expose Secret data.
  Why it matters: Protecting API access is important, but data also needs protection after an application receives it.
• Manual Secret rotation: Explain what Kubernetes Secrets do and do not do when secret values need regular rotation.
  Why it matters: An updated file is not the same thing as automatic rotation of the secret value.
• External secret management: Explain why the section recommends complementing Kubernetes Secrets with a dedicated external secret management tool.
  Why it matters: The recommendation addresses security features that Kubernetes Secrets do not provide by themselves.

Key terms: Secret, Base64-encoded, encryption, etcd, Secrets, RBAC, Kubernetes API, environment variable, file, logs

8.4 Exposing metadata to containers via the Downward API

This section contrasts static configuration with pod-specific information and explains why repeating values already in a pod manifest is undesirable.

• Static versus pod-specific values: Distinguish configuration values known before deployment from values determined when a pod is created and scheduled, such as its IP address or node name.
  Why it matters: It explains why fixed configuration values cannot supply every piece of information an application might need.
• Avoiding duplicate manifest information: Explain why information already specified elsewhere in a pod manifest should not be repeated as configuration data, using allocated CPU or memory as an example.
  Why it matters: Keeping a value in one place avoids unnecessary repetition in a manifest.

Key terms: configuration data, pod, cluster node, pod manifest, CPU, memory

8.4.1 Introducing the Downward API

Introduces the Downward API as a way to pass selected Pod and container information into containers without repeating it in application configuration.

• Downward API purpose: Explain why an application might use the Downward API and what it receives through it.
  Why it matters: It lets an application receive information already held by Kubernetes without duplicating it in the container configuration.
• Metadata reference fields: Distinguish the two Downward API references used with valueFrom for environment variables.
  Why it matters: Choosing the reference depends on whether the value describes the Pod or the container’s resource constraints.
• Supported fields and delivery: Describe the limits on which Downward API values can be injected and where they can appear.
  Why it matters: The available delivery method depends on the field, so not every Pod value can be exposed in the same way.

Key terms: Downward API, pod metadata, environment variables, valueFrom, fieldRef, resourceFieldRef, downwardAPI volume

8.4.2 Injecting pod metadata into environment variables

Shows how the Downward API supplies pod metadata and container resource limits to an application through environment variables.

• Pod metadata environment variables: Explain how the Kiada application receives its pod and node names and IP addresses through environment variables supplied by the Downward API.
  Why it matters: It lets an application use information about the pod and node it is running on.
• Container limit environment variables: Describe how the Downward API exposes a container’s CPU and memory limits as environment variables, including how a divisor changes the value’s unit and how to select another container’s limits.
  Why it matters: An application can adapt to its allocated CPU and memory rather than assuming fixed resources.

Key terms: Downward API, POD_NAME, POD_IP, NODE_NAME, NODE_IP, CPU and memory resource limits, valueFrom.resourceFieldRef, divisor, containerName

8.5 Summary

Summarizes how pod manifests, ConfigMaps, Secrets, and the Downward API supply settings and data to containers.