Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: Patches can't wildcard match within one resource #4250

Closed
wants to merge 1 commit into from
Closed

doc: Patches can't wildcard match within one resource #4250

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
36 changes: 36 additions & 0 deletions examples/patchMultipleObjects.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ a _target selector_:
[strategic merge patch]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md
[json patch]: jsonpatch.md

Note that a strategic merge patch must still have a `metadata.name` field even if the `patch`'s `target.name` overrides it. Its value will be ignored, but it must be present.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a sentence for what happens if it is not present?

> ```yaml
> patches:
> - path: <relative path to file containing patch>
Expand Down Expand Up @@ -55,6 +57,11 @@ Deployments that also have the _label_ `app=hello`
> labelSelector: app=hello
> ```

To apply the same patch to targets that match any of the
specifiers ("OR"-like), just add multiple patch list
entries with different targets that reference the same
patch file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you mind providing a short example of a patches field that achieves this?

### Demo

The example below shows how to inject a
Expand Down Expand Up @@ -216,3 +223,32 @@ diff $DEMO_HOME/out_actual.yaml $DEMO_HOME/out_expected.yaml

To see how to do this with JSON patches,
try the [JSON patch] demo.

### Limitations

Kustomize `patches` may be applied to multiple resources using
target-specifiers, but a single patch cannot apply to multiple
parts of the same resource's configuration. This is true for
both strategic merge patches and json patches.

For example, there is presently no way to express the operation
"append a new entry to the `env` list for every container in a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note that we would like to have the replacements transformer support this, if someone has bandwidth to contribute it, tracked here: #4561

It currently works as long as the field in question is already present (i.e. to overwrite the value). See the wildcard format toward the end of this section: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/replacements/#field-path-format. Since this doc is about how to patch multiple objects, I think discussion of the replacements transformer approach would be a valuable addition to it.

`Deployment`'s `spec.template.spec.containers` list" as a Kustomize
patch:
* A [JSON patch](http://jsonpatch.com/) must identify a single specific subject in a
json document using a [json pointer](http://tools.ietf.org/html/rfc6901),
e.g. `/spec/template/spec/containers/0/imagePullPolicy`. This is not
JSONPath expression. There is no wildcard or pattern match that can
replace the `/0/` path-component, and the target must already exist,
so it can't patch objects that appear within some target resources but
not others.
* A strategic merge patch does not have any support for applying a
subtree over multiple members of a list or the values of multiple
keys of an object. It can only append, delete, replace or merge.

If you need more powerful configuration transformations than are presently offered
by Kustomize patches then [transformers](transformerconfigs/README.md)
may be suitable. A number of built-in transformers already exist,
to e.g. rename and/or re-tag images referenced in Deployments, to change
name-references to a specific object type, to apply custom labels or annotations,
etc.