mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-05-17 18:25:26 +00:00
add mini-Kep 'Replacements and Patch value in the structured data'
This commit is contained in:
koba1t
256
proposals/22-03-value-in-the-structured-data.md
Normal file
256
proposals/22-03-value-in-the-structured-data.md
Normal file
@@ -0,0 +1,256 @@
|
||||
<!--
|
||||
**Note:** When your proposal is complete, all of these comment blocks should be removed.
|
||||
|
||||
To get started with this template:
|
||||
|
||||
- [ ] **Make a copy of this file.**
|
||||
Name it `YY-MM-short-descriptive-title.md` (where `YY-MM` is the current year and month).
|
||||
- [ ] **Fill out this file as best you can.**
|
||||
At minimum, you should fill in the "Summary" and "Motivation" sections.
|
||||
- [ ] **Create a PR.**
|
||||
Ping `@kubernetes-sigs/kustomize-admins` and `@kubernetes-sigs/kustomize-maintainers`.
|
||||
-->
|
||||
|
||||
# Replacements and Patch value in the structured data.
|
||||
|
||||
**Authors**:
|
||||
- koba1t
|
||||
|
||||
**Reviewers**:
|
||||
- natasha41575
|
||||
- knverey
|
||||
|
||||
**Status**: implementable
|
||||
<!--
|
||||
In general, all proposals made should be merged for the record, whether or not they are accepted.
|
||||
Use the status field to record the results of the latest review:
|
||||
- implementable: The default for this repo. If the proposal is merged, you can start working on it.
|
||||
- deferred: The proposal may be accepted in the future, but it has been shelved for the time being.
|
||||
A new PR must be opened to update the proposal and gain reviewer consensus before work can begin.
|
||||
- withdrawn: The author changed their mind and no longer wants to pursue the proposal.
|
||||
A new PR must be opened to update the proposal and gain reviewer consensus before work can begin.
|
||||
- rejected: This proposal should not be implemented.
|
||||
- replaced: If you submit a new proposal that supersedes an older one,
|
||||
update the older one's status to "replaced by <link>".
|
||||
-->
|
||||
|
||||
## 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
|
||||
|
||||
<!--
|
||||
If this proposal is an expansion of an existing GitHub issue, link to it here.
|
||||
-->
|
||||
|
||||
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:**
|
||||
<!--
|
||||
List the specific goals of the proposal. What is it trying to achieve? How will we
|
||||
know that this has succeeded?
|
||||
-->
|
||||
|
||||
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:**
|
||||
<!--
|
||||
What is out of scope for this proposal? Listing non-goals helps to focus discussion
|
||||
and make progress.
|
||||
-->
|
||||
|
||||
1. Do not provide to perfectly alternative for deprecated [vars](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/vars/).
|
||||
|
||||
## Proposal
|
||||
|
||||
<!--
|
||||
This is where we get down to the specifics of what the proposal actually is.
|
||||
Include enough information to illustrate your proposal, but try not to
|
||||
overwhelm reviewers with details. Focus on APIs and interfaces rather than implementation details,
|
||||
e.g.:
|
||||
- Does this proposal require new kinds, fields or CLI flags?
|
||||
- Will this feature require extending the public interface of Kustomize's Go packages?
|
||||
(it's ok if you're not sure yet)
|
||||
|
||||
A proof of concept PR is NOT required but is preferable to including large amounts of code
|
||||
inline here, if you feel such implementation details are required to adequately explain your design.
|
||||
If you have a PR, link to it at the top of this section.
|
||||
-->
|
||||
|
||||
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
|
||||
<!--
|
||||
Describe what people will be able to do if this KEP is implemented. If different user personas
|
||||
will use the feature differently, consider writing separate stories for each.
|
||||
Include as much detail as possible so that people can understand the "how" of the system.
|
||||
The goal here is to make this feel real for users without getting bogged down.
|
||||
-->
|
||||
|
||||
#### Story 1
|
||||
|
||||
Scenario summary: As a [end user, extension developer, ...], I want to [...]
|
||||
<!--
|
||||
A walkthrough of what it will look like for a user to take advantage of the new feature.
|
||||
Include the the steps the user will take and samples of the commands they'll run
|
||||
and config they'll use.
|
||||
-->
|
||||
|
||||
#### Story 2
|
||||
|
||||
Scenario summary: As a [end user, extension developer, ...], I want to [...]
|
||||
<!--
|
||||
A walkthrough of what it will look like for a user to take advantage of the new feature.
|
||||
Include the the steps the user will take and samples of the commands they'll run
|
||||
and config they'll use.
|
||||
-->
|
||||
|
||||
### Risks and Mitigations
|
||||
<!--
|
||||
What are the risks of this proposal, and how do we mitigate? Think broadly.
|
||||
For example, consider both security, end-user privacy, and how this will
|
||||
impact the larger Kubernetes ecosystem.
|
||||
-->
|
||||
|
||||
### Dependencies
|
||||
<!--
|
||||
Kustomize tightly controls its Go dependencies in order to remain approved for
|
||||
integration into kubectl. It cannot depend directly on kubectl or apimachinery code.
|
||||
Identify any new Go dependencies this proposal will require Kustomize to pull in.
|
||||
If any of them are large, is there another option?
|
||||
-->
|
||||
|
||||
### Scalability
|
||||
<!--
|
||||
Is this feature expected to have a performance impact?
|
||||
Explain to what extent and under what conditions.
|
||||
-->
|
||||
|
||||
## Drawbacks
|
||||
<!--
|
||||
Why should this proposal _not_ be implemented?
|
||||
-->
|
||||
|
||||
## Alternatives
|
||||
<!--
|
||||
What other approaches did you consider, and why did you rule them out? Be concise,
|
||||
but do include enough information to express the idea and why it was not acceptable.
|
||||
-->
|
||||
|
||||
## Rollout Plan
|
||||
<!--
|
||||
Depending on the scope of the features and the risks enabling it implies,
|
||||
you may need to use a formal graduation process. If you don't think this is
|
||||
necessary, explain why here, and delete the alpha/beta/GA headings below.
|
||||
-->
|
||||
|
||||
### Alpha
|
||||
<!--
|
||||
New Kinds should be introduced with an alpha group version.
|
||||
New major features should often be gated by an alpha flag at first.
|
||||
New transformers can be introduced for use in the generators/validators/transformers fields
|
||||
before they get their own top-level field in Kustomization.
|
||||
-->
|
||||
|
||||
- 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
|
||||
<!--
|
||||
If the alpha was not available in `kubectl kustomize`, you need a beta phase where it is.
|
||||
Full parity with `kubectl kustomize` is required at this stage.
|
||||
-->
|
||||
|
||||
### GA
|
||||
<!--
|
||||
You should generally wait at least two `kubectl` release cycles before promotion to GA,
|
||||
to ensure that the broader user base has time to try the feature and provide feedback.
|
||||
For example, if your feature first appears in kubectl 1.23, promote it in 1.25 or later.
|
||||
-->
|
||||
Reference in New Issue
Block a user