Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt

Use this file to discover all available pages before exploring further.

ConfigMaps store non-sensitive configuration data as key-value pairs. They allow you to decouple configuration from container images, making applications portable and easier to configure.

​
Key Concepts

ConfigMap

A Kubernetes resource that stores configuration data as key-value pairs.

Data

String key-value pairs for configuration files, environment variables, or command arguments.

Binary Data

Base64-encoded binary content for non-UTF8 data like images or certificates.

Mounting

ConfigMaps can be mounted as volumes or exposed as environment variables in pods.

​
Required Permissions

ActionPermission
View configmapsiam:project:infrastructure:kubernetes:read
Create configmapiam:project:infrastructure:kubernetes:write
Edit configmapiam:project:infrastructure:kubernetes:write
Delete configmapiam:project:infrastructure:kubernetes:delete

​
How to View ConfigMaps

1

Select Cluster

Choose a cluster from the cluster dropdown.
2

Select Namespace

Choose a namespace or select “all” to view ConfigMaps across all namespaces.
3

Search

Use the search box to find ConfigMaps by name, namespace, or data key.

​
How to View ConfigMap Details

1

Find the ConfigMap

Locate the ConfigMap in the list.
2

Click ConfigMap Name

Click on the ConfigMap name to open the detail drawer.
3

Review Details

View ConfigMap information including:
  • Overview: Name, namespace, key count, size, age
  • Data: All key-value pairs with content preview
  • Binary Data: Binary keys (content shown as placeholder)
  • Labels & Annotations: Metadata attached to the ConfigMap
  • Events: Recent Kubernetes events

​
How to Create a ConfigMap

1

Click Create ConfigMap

Click the Create ConfigMap button in the page header.
2

Write YAML

Enter the ConfigMap manifest in YAML format. Key fields:
  • data - String key-value pairs
  • binaryData - Base64-encoded binary content
3

Select Namespace

Choose the target namespace for the ConfigMap.
4

Create

Click Create to apply the manifest.

​
How to Edit a ConfigMap

1

Open Actions Menu

Click the actions menu (three dots) on the ConfigMap row.
2

Click Edit ConfigMap

Select Edit ConfigMap to open the YAML editor.
3

Modify Data

Edit the ConfigMap content. Common changes:
  • Add or update configuration keys
  • Modify values
  • Update labels and annotations
4

Save

Click Update to apply changes.
Updating a ConfigMap does not automatically restart pods using it. Pods must be restarted or use dynamic configuration reloading to pick up changes.

​
How to Delete a ConfigMap

1

Open Actions Menu

Click the actions menu on the ConfigMap row.
2

Click Delete

Select Delete from the menu.
3

Confirm

Confirm the deletion. Pods referencing this ConfigMap may fail if they require it.
Deleting a ConfigMap that is mounted by running pods will cause those pods to fail if they try to read the configuration. Ensure no pods depend on the ConfigMap before deletion.

​
Using ConfigMaps in Pods

​
As Environment Variables

spec:
  containers:
    - name: app
      envFrom:
        - configMapRef:
            name: app-config
      # Or individual keys:
      env:
        - name: DATABASE_URL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: database-url

​
As Volume Mounts

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

​
With Specific Keys

volumes:
  - name: config-volume
    configMap:
      name: app-config
      items:
        - key: app.properties
          path: application.properties

​
ConfigMap Size Limits

LimitValue
Maximum size1 MiB (1,048,576 bytes)
Key name length253 characters
Key name patternAlphanumeric, -, _, .
The 1 MiB limit applies to the total size of all data in a single ConfigMap. For larger configurations, split into multiple ConfigMaps or consider using external configuration storage.

​
Data vs Binary Data

FieldUse CaseEncoding
dataText files, properties, JSON, YAMLUTF-8 string
binaryDataImages, certificates, compressed filesBase64 encoded
Use data for configuration files and environment variables. Use binaryData only when you need to store non-text content that can’t be represented as UTF-8.

​
Troubleshooting

  • Verify the ConfigMap exists in the same namespace as the pod
  • Check ConfigMap name spelling in pod spec
  • Ensure referenced keys exist in the ConfigMap
  • Check for optional flag if ConfigMap might not exist
  • ConfigMap updates don’t automatically restart pods
  • Restart the deployment/pod to pick up changes
  • Use subPath mounts prevent automatic updates
  • Consider using reloader controllers for automatic restarts
  • ConfigMaps are limited to 1 MiB
  • Split large configurations into multiple ConfigMaps
  • Consider using external configuration storage
  • Compress data if appropriate
  • Keys must be alphanumeric with -, _, or .
  • Keys cannot start with ..
  • Maximum length is 253 characters
  • Avoid special characters and spaces
  • Ensure binaryData values are base64 encoded
  • Don’t mix the same key in both data and binaryData
  • Verify encoding with base64 -d command
  • Check file permissions in the ConfigMap volume
  • Use defaultMode to set permissions (e.g., 0644)
  • Verify container runs with appropriate user

​
FAQ

ConfigMaps store non-sensitive configuration data in plain text. Secrets store sensitive data (passwords, tokens) with base64 encoding and additional security features like encryption at rest. Use Secrets for sensitive data, ConfigMaps for everything else.
No. Pods don’t automatically restart when ConfigMaps change. Volume-mounted ConfigMaps eventually update (kubelet sync period), but environment variables never update. Restart pods or use a reloader controller for automatic updates.
No. ConfigMaps are namespace-scoped. A pod can only reference ConfigMaps in its own namespace. For shared configuration, create identical ConfigMaps in each namespace or use cluster-level configuration tools.
Use kubectl: kubectl create configmap my-config --from-file=config.properties. This creates a key with the filename and value with the file content.
Yes. Add multiple keys to the data section. When mounted as a volume, each key becomes a file in the mount directory.
The pod will fail to start with a “CreateContainerConfigError”. Use optional: true in the volume or envFrom to allow the pod to start without the ConfigMap.
Use the items field in the volume definition to select specific keys and optionally rename them with the path field.
Yes. Use the Edit ConfigMap action to modify the YAML, including data values. Changes take effect immediately but pods need to be restarted to pick up the changes.