@@ -1044,6 +1044,79 @@ cd apps/my-app
10441044kustomize create --autodetect --recursive
10451045` ` `
10461046
1047+ # ## Controlling the apply behavior of resources
1048+
1049+ To change the apply behaviour for specific Kubernetes resources, you can annotate them with :
1050+
1051+ | Annotation | Default | Values | Role |
1052+ |-------------------------------------|------------|----------------------------------------------------------------|-----------------|
1053+ | `kustomize.toolkit.fluxcd.io/ssa` | `Override` | - `Override`<br/>- `Merge`<br/>- `IfNotPresent`<br/>- `Ignore` | Apply policy |
1054+ | `kustomize.toolkit.fluxcd.io/force` | `Disabled` | - `Enabled`<br/>- `Disabled` | Recreate policy |
1055+ | `kustomize.toolkit.fluxcd.io/prune` | `Enabled` | - `Enabled`<br/>- `Disabled` | Delete policy |
1056+
1057+ **Note:** These annotations should be set in the Kubernetes YAML manifests included
1058+ in the Flux Kustomization source (Git, OCI, Bucket).
1059+
1060+ # ### `kustomize.toolkit.fluxcd.io/ssa`
1061+
1062+ # #### Override
1063+
1064+ The `Override` policy instructs the controller to reconcile the Kubernetes resources
1065+ with the desired state (YAML manifests) defined in the Flux source (Git, OCI, Bucket).
1066+
1067+ If you use `kubectl` to edit a Kubernetes resource managed by Flux, all changes will be
1068+ reverted when the controller reconciles a Flux Kustomization containing that resource.
1069+ In order to preserve fields added with `kubectl`, you have to specify
1070+ a field manager named `flux-client-side-apply` e.g. :
1071+
1072+ ` ` ` sh
1073+ kubectl apply --field-manager=flux-client-side-apply
1074+ ` ` `
1075+
1076+ # #### Merge
1077+
1078+ The `Merge` policy instructs the controller to preserve the fields added by other tools to the
1079+ Kubernetes resources managed by Flux.
1080+
1081+ The fields defined in the manifests applied by the controller will always be overridden,
1082+ the `Merge` policy works only for adding new fields that don’t overlap with the desired
1083+ state.
1084+
1085+ For lists fields which are atomic (e.g. `.spec.tolerations` in PodSpec), Kubernetes
1086+ doesn't allow different managers for such fields, therefore any changes to these
1087+ fields will be reverted. For more context, please see the Kubernetes enhancement document :
1088+ [555-server-side-apply](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/555-server-side-apply/README.md#lists).
1089+
1090+ # #### IfNotPresent
1091+
1092+ The `IfNotPresent` policy instructs the controller to only apply the Kubernetes resources
1093+ if they are not present on the cluster.
1094+
1095+ This policy can be used for Kubernetes Secrets and ValidatingWebhookConfigurations managed by cert-manager,
1096+ where Flux creates the resources with fields that are later on mutated by other controllers.
1097+
1098+ # #### Ignore
1099+
1100+ The `Ignore` policy instructs the controller to skip applying Kubernetes resources
1101+ even if they are included in a Flux source (Git, OCI, Bucket).
1102+
1103+ # ### `kustomize.toolkit.fluxcd.io/force`
1104+
1105+ When set to `Enabled`, this policy instructs the controller to recreate the Kubernetes resources
1106+ with changes to immutable fields.
1107+
1108+ This policy can be used for Kubernetes Jobs to rerun them when their container image changes.
1109+
1110+ **Note:** Using this policy for StatefulSets may result in potential data loss.
1111+
1112+ # ### `kustomize.toolkit.fluxcd.io/prune`
1113+
1114+ When set to `Disabled`, this policy instructs the controller to skip the deletion of
1115+ the Kubernetes resources subject to [garbage collection](#prune).
1116+
1117+ This policy can be used to protect sensitive resources such as Namespaces, PVCs and PVs
1118+ from accidental deletion.
1119+
10471120# ## Role-based access control
10481121
10491122By default, a Kustomization apply runs under the cluster admin account and can
@@ -1502,48 +1575,6 @@ Using `flux`:
15021575flux reconcile kustomization <kustomization-name>
15031576` ` `
15041577
1505- # ## Customizing reconciliation
1506-
1507- You can configure the controller to ignore in-cluster resources by labelling or
1508- annotating them with :
1509-
1510- ` ` ` yaml
1511- kustomize.toolkit.fluxcd.io/reconcile: disabled
1512- ` ` `
1513-
1514- **Note:** When the `kustomize.toolkit.fluxcd.io/reconcile` annotation is set to
1515- ` disabled` , the controller will no longer apply changes from the source, nor
1516- will it prune the resource. To resume reconciliation, set the annotation to
1517- ` enabled` in the source or remove it from the in-cluster object.
1518-
1519- If you use `kubectl` to edit an object managed by Flux, all changes will be
1520- reverted when the controller reconciles a Flux Kustomization containing that
1521- object. In order to preserve fields added with `kubectl`, you have to specify
1522- a field manager named `flux-client-side-apply` e.g. :
1523-
1524- ` ` ` sh
1525- kubectl apply --field-manager=flux-client-side-apply
1526- ` ` `
1527-
1528- Another option is to annotate or label objects with :
1529-
1530- ` ` ` yaml
1531- kustomize.toolkit.fluxcd.io/ssa: merge
1532- ` ` `
1533-
1534- **Note:** The fields defined in manifests will always be overridden, the above
1535- procedure works only for adding new fields that don’t overlap with the desired
1536- state.
1537-
1538- For lists fields which are atomic (e.g. `.spec.tolerations` in PodSpec), Kubernetes
1539- doesn't allow different managers for such fields, therefore any changes to these
1540- fields will be undone, even if you specify a manager. For more context, please
1541- see the Kubernetes enhancement document :
1542- [555-server-side-apply](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/555-server-side-apply/README.md#lists).
1543-
1544- To learn how to handle patching failures due to immutable field changes, refer
1545- to [`.spec.force`](#force).
1546-
15471578# ## Waiting for `Ready`
15481579
15491580When a change is applied, it is possible to wait for the Kustomization to reach
@@ -1558,6 +1589,18 @@ kubectl wait kustomization/<kustomization-name> --for=condition=ready --timeout=
15581589When you find yourself in a situation where you temporarily want to pause the
15591590reconciliation of a Kustomization, you can suspend it using [`.spec.suspend`](#suspend).
15601591
1592+ To pause the reconciliation of a specific Kubernetes resource managed by a Flux Kustomization,
1593+ you can annotate or label the resource in-cluster with :
1594+
1595+ ` ` ` yaml
1596+ kustomize.toolkit.fluxcd.io/reconcile: disabled
1597+ ` ` `
1598+
1599+ **Note:** When the `kustomize.toolkit.fluxcd.io/reconcile` annotation is set to
1600+ ` disabled` , the controller will no longer apply changes, nor
1601+ will it prune the resource. To resume reconciliation, set the annotation to
1602+ ` enabled` in the source or remove it from the in-cluster object.
1603+
15611604# ### Suspend a Kustomization
15621605
15631606In your YAML declaration :
0 commit comments