How to Parameterize Multi‑Line ConfigMap Data with Kustomize Patches

Background

In Kubernetes, a ConfigMap stores configuration data, and its data field often contains multi‑line text like configuration files. Modifying those multi‑line strings with Kustomize's replacements is difficult because the tool does not parse the internal structure of a multi‑line string.

Challenge

The replacements feature works well for simple key‑value pairs but fails when the target field is a multi‑line string inside data. Using fieldPaths on such a field typically results in an "unable to find field" error, as Kustomize does not descend into the string content.

Illustrative Example

Consider a base ConfigMap base/configmap.yaml with an app.properties entry:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  app.properties: |
    db.host=PLACEHOLDER_DB_HOST
    db.port=PLACEHOLDER_DB_PORT

We want to replace db.host and db.port with real development values.

Incorrect Attempt Using Replacements

# overlays/development/kustomization.yaml (incorrect)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
configMapGenerator:
- name: replacement-source-config
  literals:
  - db_host=dev-db.example.com
  - db_port=5432
replacements:
- source:
    kind: ConfigMap
    name: replacement-source-config
  fieldPath: data.db_host
  targets:
  - select:
      kind: ConfigMap
      name: my-config
    fieldPaths:
    - data.app\.properties
    options:
      delimiter: '='
      index: 1

Running kubectl kustomize overlays/development produces unexpected results because the multi‑line string is not correctly addressed.

Solution: Precise Control with Patches

Kustomize's patches field can apply a JSON Patch or Strategic Merge Patch directly to the ConfigMap resource, allowing exact modification of the data field.

Correct Patch Example

# overlays/development/kustomization.yaml (correct)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patches:
- target:
    kind: ConfigMap
    name: my-config
  patch: |-
    - op: replace
      path: /data/app.properties
      value: |
        db.host=dev-db.example.com
        db.port=5432

Code Explanation patches: defines a JSON Patch. target: selects the ConfigMap named my-config. patch: contains the JSON Patch operations. op: replace: replaces the value at the given path. path: /data/app.properties: points to the multi‑line field. value: provides the new content with the actual database host and port.

Running kubectl kustomize overlays/development now yields the updated ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  app.properties: |
    db.host=dev-db.example.com
    db.port=5432

The placeholders have been successfully replaced.

Advantages and Use Cases

Flexibility : Modify any multi‑line text without the constraints of replacements.

Readability : JSON Patch syntax is clear and easy to maintain.

Control : Precise definition of what changes and where, avoiding accidental side effects.

Parameterization : Enables environment‑specific configurations.

Typical scenarios include:

Traditional configuration files such as Java .properties, Python .ini, etc.

Third‑party ConfigMaps that cannot be directly edited.

Complex configuration changes requiring line‑level additions, deletions, or modifications.

Best Practices and Caveats

Refactor ConfigMaps : Whenever possible, split multi‑line content into separate key‑value pairs in data for simpler management.

Use Strategic Merge Patch for Complex Changes : It can intelligently merge lists and maps.

Avoid Overusing Patches : While powerful, excessive patches can reduce readability; use them judiciously.

Test Thoroughly : Always verify the resulting ConfigMap to ensure correctness.

Conclusion

Kustomize's patches feature provides a robust and flexible way to handle multi‑line ConfigMap data. By leveraging JSON Patch or Strategic Merge Patch, you can precisely parameterize configurations, improve maintainability, and make your Kubernetes deployments more efficient.