> ## 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

> Manage Kubernetes ConfigMaps for storing non-sensitive configuration data

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

<CardGroup cols={2}>
  <Card title="ConfigMap" icon="file-text">
    A Kubernetes resource that stores configuration data as key-value pairs.
  </Card>

  <Card title="Data" icon="key">
    String key-value pairs for configuration files, environment variables, or command arguments.
  </Card>

  <Card title="Binary Data" icon="file-binary">
    Base64-encoded binary content for non-UTF8 data like images or certificates.
  </Card>

  <Card title="Mounting" icon="hard-drive">
    ConfigMaps can be mounted as volumes or exposed as environment variables in pods.
  </Card>
</CardGroup>

## Required Permissions

| Action           | Permission                                     |
| ---------------- | ---------------------------------------------- |
| View configmaps  | `iam:project:infrastructure:kubernetes:read`   |
| Create configmap | `iam:project:infrastructure:kubernetes:write`  |
| Edit configmap   | `iam:project:infrastructure:kubernetes:write`  |
| Delete configmap | `iam:project:infrastructure:kubernetes:delete` |

## How to View ConfigMaps

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the cluster dropdown.
  </Step>

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view ConfigMaps across all namespaces.
  </Step>

  <Step title="Search">
    Use the search box to find ConfigMaps by name, namespace, or data key.
  </Step>
</Steps>

## How to View ConfigMap Details

<Steps>
  <Step title="Find the ConfigMap">
    Locate the ConfigMap in the list.
  </Step>

  <Step title="Click ConfigMap Name">
    Click on the ConfigMap name to open the detail drawer.
  </Step>

  <Step title="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
  </Step>
</Steps>

## How to Create a ConfigMap

<Steps>
  <Step title="Click Create ConfigMap">
    Click the **Create ConfigMap** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the ConfigMap manifest in YAML format. Key fields:

    * `data` - String key-value pairs
    * `binaryData` - Base64-encoded binary content
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the ConfigMap.
  </Step>

  <Step title="Create">
    Click **Create** to apply the manifest.
  </Step>
</Steps>

## How to Edit a ConfigMap

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the ConfigMap row.
  </Step>

  <Step title="Click Edit ConfigMap">
    Select **Edit ConfigMap** to open the YAML editor.
  </Step>

  <Step title="Modify Data">
    Edit the ConfigMap content. Common changes:

    * Add or update configuration keys
    * Modify values
    * Update labels and annotations
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  Updating a ConfigMap does not automatically restart pods using it. Pods must be restarted or use dynamic configuration reloading to pick up changes.
</Warning>

## How to Delete a ConfigMap

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the ConfigMap row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. Pods referencing this ConfigMap may fail if they require it.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Using ConfigMaps in Pods

### As Environment Variables

```yaml theme={null}
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

```yaml theme={null}
spec:
  containers:
    - name: app
      volumeMounts:
        - name: config-volume
          mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        name: app-config
```

### With Specific Keys

```yaml theme={null}
volumes:
  - name: config-volume
    configMap:
      name: app-config
      items:
        - key: app.properties
          path: application.properties
```

## ConfigMap Size Limits

| Limit                | Value                       |
| -------------------- | --------------------------- |
| **Maximum size**     | 1 MiB (1,048,576 bytes)     |
| **Key name length**  | 253 characters              |
| **Key name pattern** | Alphanumeric, `-`, `_`, `.` |

<Info>
  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.
</Info>

## Data vs Binary Data

| Field          | Use Case                               | Encoding       |
| -------------- | -------------------------------------- | -------------- |
| **data**       | Text files, properties, JSON, YAML     | UTF-8 string   |
| **binaryData** | Images, certificates, compressed files | Base64 encoded |

<Tip>
  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.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod fails to start with ConfigMap error">
    * 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
  </Accordion>

  <Accordion title="Configuration changes not reflected in pod">
    * 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
  </Accordion>

  <Accordion title="ConfigMap too large">
    * ConfigMaps are limited to 1 MiB
    * Split large configurations into multiple ConfigMaps
    * Consider using external configuration storage
    * Compress data if appropriate
  </Accordion>

  <Accordion title="Invalid key name">
    * Keys must be alphanumeric with `-`, `_`, or `.`
    * Keys cannot start with `..`
    * Maximum length is 253 characters
    * Avoid special characters and spaces
  </Accordion>

  <Accordion title="Binary data not working">
    * Ensure binaryData values are base64 encoded
    * Don't mix the same key in both data and binaryData
    * Verify encoding with `base64 -d` command
  </Accordion>

  <Accordion title="Permission denied reading mounted ConfigMap">
    * Check file permissions in the ConfigMap volume
    * Use `defaultMode` to set permissions (e.g., `0644`)
    * Verify container runs with appropriate user
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between ConfigMaps and Secrets?">
    **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.
  </Accordion>

  <Accordion title="Do pods automatically update when ConfigMaps change?">
    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.
  </Accordion>

  <Accordion title="Can I use ConfigMaps across namespaces?">
    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.
  </Accordion>

  <Accordion title="How do I create a ConfigMap from a file?">
    Use kubectl: `kubectl create configmap my-config --from-file=config.properties`. This creates a key with the filename and value with the file content.
  </Accordion>

  <Accordion title="Can I have multiple files in one ConfigMap?">
    Yes. Add multiple keys to the data section. When mounted as a volume, each key becomes a file in the mount directory.
  </Accordion>

  <Accordion title="What happens if a required ConfigMap doesn't exist?">
    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.
  </Accordion>

  <Accordion title="How do I mount only specific keys from a ConfigMap?">
    Use the `items` field in the volume definition to select specific keys and optionally rename them with the `path` field.
  </Accordion>

  <Accordion title="Can I edit ConfigMap data in the UI?">
    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.
  </Accordion>
</AccordionGroup>