# Kustomize configMapGenerator

> configMapGenerator builds ConfigMaps from files, literals, or env files with a content hash suffix. Reference for the fields and the rollout and key errors in CI.

Source: https://latchkey.dev/learn/command-reference/kustomize-configmap-generator  
Updated: 2026-06-30

configMapGenerator creates ConfigMaps from files, literals, or env files and appends a content hash to the name.

Generated ConfigMaps get a hash suffix, so changing the data changes the name and forces a rollout. This is the idiomatic way to ship config with Kustomize.

## What it does

configMapGenerator produces a ConfigMap from literals, whole files, or an env file. By default Kustomize appends an 8-character content hash to the name and rewrites every reference to it, so editing the data renames the ConfigMap and triggers a rolling update of the consuming Deployment.

## Common usage

```kustomization.yaml
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
      - REGION=us-east-1
    files:
      - config.json
    envs:
      - app.env
```

## Fields

| Field | What it does |
| --- | --- |
| name | Base name of the ConfigMap |
| literals | KEY=value pairs as data entries |
| files | Files whose contents become data (key is the filename) |
| envs | Env files: each line becomes a data key |
| behavior | create, replace, or merge with an existing ConfigMap |
| options.disableNameSuffixHash | Turn off the content hash suffix |

## In CI

The hash suffix is the feature, not a bug: it guarantees a rollout when config changes. Only disable it (disableNameSuffixHash: true) when an external system references the ConfigMap by a fixed name. Keep env files out of secrets; use secretGenerator for sensitive values.

## Common errors in CI

"already registered id" or a hash-mismatch reference means a manifest references the ConfigMap by its base name without the generator rewriting it; reference it through the generated resource, not a hardcoded name. "env file ... not found" means the envs path is wrong. A key with characters outside [-._a-zA-Z0-9] is rejected with "a valid config key must consist of alphanumeric characters".

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### Kustomize configMapGenerator?

Generated ConfigMaps get a hash suffix, so changing the data changes the name and forces a rollout. This is the idiomatic way to ship config with Kustomize.

### What it does?

configMapGenerator produces a ConfigMap from literals, whole files, or an env file. By default Kustomize appends an 8-character content hash to the name and rewrites every reference to it, so editing the data renames the ConfigMap and triggers a rolling update of the consuming Deployment.

### In CI?

The hash suffix is the feature, not a bug: it guarantees a rollout when config changes. Only disable it (disableNameSuffixHash: true) when an external system references the ConfigMap by a fixed name. Keep env files out of secrets; use secretGenerator for sensitive values.

### Common errors in CI?

"already registered id" or a hash-mismatch reference means a manifest references the ConfigMap by its base name without the generator rewriting it; reference it through the generated resource, not a hardcoded name. "env file ... not found" means the envs path is wrong.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt