Introduction

The key thing to understand is that a plain Kubernetes YAML manifest cannot directly "read a local file" at apply time. A ConfigMap manifest can contain file content under data, but the file has to be embedded into the YAML before Kubernetes sees it. In practice, you either write the content into the manifest yourself or generate the YAML from a local file with kubectl create configmap --from-file ... --dry-run=client -o yaml.

The Explicit YAML Form

If the file content is small and stable, you can place it directly into the ConfigMap manifest.

Suppose your local file contains:

server.port=8080
feature.enabled=true

The matching ConfigMap YAML looks like this:

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: app-config
5data:
6  app.properties: |
7    server.port=8080
8    feature.enabled=true

The important part is that the file contents become the value of a key such as app.properties. Kubernetes stores text; it does not keep a pointer back to your original local file.

Generating the YAML from a Real File

When you already have a file on disk and do not want to paste it manually, generate the manifest with kubectl:

kubectl create configmap app-config   --from-file=app.properties   --dry-run=client   -o yaml

That prints a complete YAML manifest that you can save to source control if you want a declarative file afterward.

This is the usual answer to the question "how do I define a ConfigMap from a file in YAML". You use the file as input to generate the YAML, then the resulting YAML contains the embedded data.

Mounting the File into a Pod

A ConfigMap becomes useful when a pod consumes it, often as a mounted file.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: config-demo
5spec:
6  containers:
7    - name: app
8      image: nginx:stable
9      volumeMounts:
10        - name: config-volume
11          mountPath: /etc/config
12  volumes:
13    - name: config-volume
14      configMap:
15        name: app-config

With that setup, the key app.properties appears as a file under /etc/config/app.properties inside the container.

Using env Versus Files

ConfigMaps can also provide environment variables, but that works best for simple key-value entries. If your source material is an actual config file such as .properties, .yaml, or .json, mounting it as a file is usually cleaner.

That distinction matters because a file-based ConfigMap preserves the shape the application already expects.

Limits and Tradeoffs

ConfigMaps are for non-secret configuration. They are not the right place for passwords, tokens, or certificates that should be treated as sensitive.

They also have size limits, so very large files are a sign that another distribution strategy may be better.

For maintainability, many teams keep the original config file in source control and regenerate or template the ConfigMap manifest as part of their deployment workflow.

Common Pitfalls

• Expecting Kubernetes YAML to read a local file path directly at apply time.
• Forgetting that the file contents must be embedded into data in the final manifest.
• Putting secrets into a ConfigMap instead of using a Secret.
• Mounting the ConfigMap but looking for the wrong filename inside the container.
• Hand-editing generated YAML without remembering which source file it came from.

Summary

• A ConfigMap YAML manifest cannot directly reference a local file path for content loading.
• You can either embed the file text manually under data or generate the YAML with kubectl --from-file.
• File-style ConfigMaps are usually mounted into pods as files.
• Use ConfigMaps for non-sensitive configuration and Secrets for sensitive values.
• Treat the final manifest as embedded data, not as a live link to the original file.