Introduction

ConfigMaps are meant for non-sensitive configuration data, but Kubernetes does support binary payloads when you need them. The key detail is that binary content belongs in the binaryData field, not in plain data, and you should still ask whether a ConfigMap is the right object before storing a file that large or that sensitive.

data Versus binaryData

Kubernetes ConfigMaps have two relevant sections:

• 'data for UTF-8 text values'
• 'binaryData for binary content encoded as base64'

If your file is not valid text, forcing it into data is fragile. binaryData exists specifically for byte sequences.

Here is a minimal ConfigMap that stores a small binary file:

1apiVersion: v1
2kind: ConfigMap
3metadata:
4  name: app-binary-config
5binaryData:
6  license.bin: AAECAwQF

The value under license.bin is base64 text that Kubernetes decodes back into bytes when the ConfigMap is mounted as a file.

Creating the Base64 Content

Suppose you have a local binary file named license.bin. You can base64-encode it and place the result into binaryData.

For example, on a Unix-like shell:

base64 license.bin

Then paste that output into the manifest.

If you apply the ConfigMap and mount it as a volume, the container sees a file named license.bin with the original binary content.

Mounting the Binary File into a Pod

A common pattern is to mount the ConfigMap as a volume:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: binary-config-demo
5spec:
6  containers:
7    - name: app
8      image: busybox
9      command: ["sh", "-c", "ls -l /config && sleep 3600"]
10      volumeMounts:
11        - name: config-volume
12          mountPath: /config
13  volumes:
14    - name: config-volume
15      configMap:
16        name: app-binary-config

When the pod starts, /config/license.bin appears as a file.

This is usually better than trying to pass binary content through environment variables, which are a poor fit for non-text payloads.

When a Secret Is the Better Choice

Many binary files are not just binary. They are also sensitive. Private keys, certificates with private material, and proprietary license files usually should not be stored in a ConfigMap.

In those cases, a Secret is the better Kubernetes object because it is intended for confidential data and uses data as base64-encoded content by design.

A simple decision rule is:

• non-sensitive binary configuration: ConfigMap with binaryData
• sensitive binary material: Secret

That distinction matters more than the file extension.

Watch the Size Limit

ConfigMaps are not general-purpose file storage. Kubernetes documentation recommends treating ConfigMaps as configuration objects, and the total object size is limited. Large binaries do not belong there.

If the file is large, or if it changes independently of deployment configuration, better options include:

• a container image layer
• an object store
• a persistent volume
• a dedicated artifact distribution step

Trying to use a ConfigMap as a mini file server usually becomes awkward quickly.

kubectl create configmap --from-file

For text files, kubectl create configmap --from-file is convenient. With binary files, you should be careful about what lands in the generated object and verify whether the resulting manifest uses the correct fielding for your use case.

If your workflow must be explicit and reviewable, hand-writing the manifest with binaryData is often clearer than relying on a generated object and hoping the encoding lands where you expect.

That explicitness is especially valuable in GitOps-style repositories.

Example End-to-End Workflow

1. base64-encode the binary file
2. store the encoded value under binaryData
3. apply the ConfigMap
4. mount it into the pod as a file
5. read the file normally from the container filesystem

For many applications, that is the whole story.

The important part is that Kubernetes is reconstructing a file on disk for your container, not asking the application to decode base64 manually at runtime.

Common Pitfalls

The biggest mistake is storing binary content under data and assuming text handling will be fine. That works only if the file is actually valid UTF-8 text.

Another issue is using a ConfigMap for secrets. A binary certificate or key file is still sensitive even if it is base64-encoded.

Developers also sometimes overlook size constraints and try to push large artifacts through ConfigMaps. That makes deployments brittle and hard to manage.

Finally, do not confuse base64 text in the manifest with the file bytes seen by the container. The manifest stores encoded text, but the mounted file is the decoded binary content.

Summary

• Use binaryData in a ConfigMap when you need to store non-sensitive binary content.
• Mount the ConfigMap as a volume so the container receives a real file.
• Use a Secret instead when the binary file is confidential.
• Keep ConfigMaps small and configuration-focused rather than treating them as artifact storage.
• Remember that base64 appears in the manifest, while the mounted file is the original decoded binary data.