diff --git a/proposals/22-03-value-in-the-structured-data.md b/proposals/22-03-value-in-the-structured-data.md new file mode 100644 index 000000000..18731501a --- /dev/null +++ b/proposals/22-03-value-in-the-structured-data.md @@ -0,0 +1,256 @@ + + +# Replacements and Patch value in the structured data. + +**Authors**: +- koba1t + +**Reviewers**: +- natasha41575 +- knverey + +**Status**: implementable + + +## Summary + +This proposal decides the interfaces to change values in the structured data (like json,yaml) inside a Kubernetes objects' field value and implements changing function target a few formats (mainly json). + + +## Motivation + + + +Fields in Kubernetes objects sometimes include values formatted by structured data like json and yaml. +kustomize can strong patch with Kubernetes objects, but kustomize can't manipulate one value on structured, formatted data in the Kubernetes object's yaml field. + +Example, kustomize can't change value `"REPLACE_TARGET_HOSTNAME"` in this yaml file. +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: target-configmap +data: + config.json: |- + {"config": { + "id": "42", + "hostname": "REPLACE_TARGET_HOSTNAME" + }} +``` + +This function has been wanted for a long time. +- https://github.com/kubernetes-sigs/kustomize/issues/680 +- https://github.com/kubernetes-sigs/kustomize/issues/3787 +- https://github.com/kubernetes-sigs/kustomize/issues/4517 + +This function can be an alternative deprecated [vars](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/vars/) function in many use cases. + +**Goals:** + + +1. Provide the way to update values in the structured data like kubernetes objects with many formats. +1. Be able to add replacement able format after. + + +**Non-goals:** + + +1. Do not provide to perfectly alternative for deprecated [vars](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/vars/). + +## Proposal + + + +I propose to add options for replacing the value in structured data to replacements function. My sample implementation is [here](https://github.com/kubernetes-sigs/kustomize/pull/4518). +This idea is add two parameter `format` and `formatPath` to [options](https://github.com/kubernetes-sigs/kustomize/blob/8668691ade05bc17b3c6f44bcd4723735033196e/api/types/replacement.go#L67-L80) in replacement [TargetSelector](https://github.com/kubernetes-sigs/kustomize/blob/8668691ade05bc17b3c6f44bcd4723735033196e/api/types/replacement.go#L52-L64). The `format` option is used by select to structured data format like "json" or yaml, and The `formatPath` option is "path" to target to change values in structured data with selected format from `format` option. + + +Example. + +```yaml +## source +apiVersion: v1 +kind: ConfigMap +metadata: + name: source-configmap +data: + HOSTNAME: www.example.com +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: target-configmap +data: + config.json: |- + {"config": { + "id": "42", + "hostname": "REPLACE_TARGET_HOSTNAME" + }} +``` + +```yaml +## replacement +replacements: +- source: + kind: ConfigMap + name: source-configmap + fieldPath: data.HOSTNAME + targets: + - select: + kind: ConfigMap + name: target-configmap + fieldPaths: + - data.config\.json + options: + format: 'json' + formatPath: '/config/hostname' +``` + +```yaml +## expected +apiVersion: v1 +kind: ConfigMap +metadata: + name: source-configmap +data: + HOSTNAME: www.example.com +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: target-configmap +data: + config.json: '{"config":{"hostname":"www.example.com","id":"42"}}' +``` + + +### User Stories + + +#### Story 1 + +Scenario summary: As a [end user, extension developer, ...], I want to [...] + + +#### Story 2 + +Scenario summary: As a [end user, extension developer, ...], I want to [...] + + +### Risks and Mitigations + + +### Dependencies + + +### Scalability + + +## Drawbacks + + +## Alternatives + + +## Rollout Plan + + +### Alpha + + +- Will the feature be gated by an "alpha" flag? Which one? +- Will the feature be available in `kubectl kustomize` during alpha? Why or why not? + +### Beta + + +### GA +