From 6b85c71fdde94be0f66ca27095979dc56a69022e Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 9 Aug 2023 14:16:37 +0300 Subject: [PATCH 1/3] Update github.com/fluxcd/pkg/ssa to v0.30.0 Signed-off-by: Stefan Prodan --- go.mod | 4 ++-- go.sum | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/go.mod b/go.mod index 4649d5cc..5bbf5694 100644 --- a/go.mod +++ b/go.mod @@ -31,7 +31,7 @@ require ( github.com/fluxcd/pkg/http/fetch v0.5.2 github.com/fluxcd/pkg/kustomize v1.3.4 github.com/fluxcd/pkg/runtime v0.41.0 - github.com/fluxcd/pkg/ssa v0.29.0 + github.com/fluxcd/pkg/ssa v0.30.0 github.com/fluxcd/pkg/tar v0.2.0 github.com/fluxcd/pkg/testserver v0.4.0 github.com/fluxcd/source-controller/api v1.0.0 @@ -226,5 +226,5 @@ require ( k8s.io/kubectl v0.27.1 // indirect sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect sigs.k8s.io/kustomize/kyaml v0.14.2 // indirect - sigs.k8s.io/structured-merge-diff/v4 v4.2.3 // indirect + sigs.k8s.io/structured-merge-diff/v4 v4.3.0 // indirect ) diff --git a/go.sum b/go.sum index 5f4a1863..d56a691b 100644 --- a/go.sum +++ b/go.sum @@ -196,8 +196,8 @@ github.com/fluxcd/pkg/runtime v0.41.0 h1:hjWUwVRCKDuGEUhovWrygt/6PRry4p278yKuJNg github.com/fluxcd/pkg/runtime v0.41.0/go.mod h1:1GN+nxoQ7LmSsLJwjH8JW8pA27tBSO+KLH43HpywCDM= github.com/fluxcd/pkg/sourceignore v0.3.4 h1:0cfS2Pj7xp2qpaerMjYqOBr82LC+/mGHl6v6pRbi5hs= github.com/fluxcd/pkg/sourceignore v0.3.4/go.mod h1:ejLx+/uIrPUgqVzMTR5JiWuUnzs+zTkoEf9gS92LqaE= -github.com/fluxcd/pkg/ssa v0.29.0 h1:s2M6507YlYRLsPuXuGhXez/EqA5LFLhI13TZe31sm10= -github.com/fluxcd/pkg/ssa v0.29.0/go.mod h1:wvmBGQC47669GqhOvi0Ec0HTMziqMSNkPIsyIPBtGTQ= +github.com/fluxcd/pkg/ssa v0.30.0 h1:SYf8EBXevbTNwdHoKqRuU00YdnmqqUuR5xcciRrIi0E= +github.com/fluxcd/pkg/ssa v0.30.0/go.mod h1:eUcni/amc2fM9rJ3ZR3oPeAW/ZYk3mOGO1TW9RFmAuI= github.com/fluxcd/pkg/tar v0.2.0 h1:HEUHgONQYsJGeZZ4x6h5nQU9Aox1I4T3bOp1faWTqf8= github.com/fluxcd/pkg/tar v0.2.0/go.mod h1:w0/TOC7kwBJhnSJn7TCABkc/I7ib1f2Yz6vOsbLBnhw= github.com/fluxcd/pkg/testserver v0.4.0 h1:pDZ3gistqYhwlf3sAjn1Q8NzN4Qe6I1BEmHMHi46lMg= @@ -737,7 +737,7 @@ sigs.k8s.io/kustomize/api v0.13.4 h1:E38Hfx0G9R9v7vRgKshviPotJQETG0S2gD3JdHLCAsI sigs.k8s.io/kustomize/api v0.13.4/go.mod h1:Bkaavz5RKK6ZzP0zgPrB7QbpbBJKiHuD3BB0KujY7Ls= sigs.k8s.io/kustomize/kyaml v0.14.2 h1:9WSwztbzwGszG1bZTziQUmVMrJccnyrLb5ZMKpJGvXw= sigs.k8s.io/kustomize/kyaml v0.14.2/go.mod h1:AN1/IpawKilWD7V+YvQwRGUvuUOOWpjsHu6uHwonSF4= -sigs.k8s.io/structured-merge-diff/v4 v4.2.3 h1:PRbqxJClWWYMNV1dhaG4NsibJbArud9kFxnAMREiWFE= -sigs.k8s.io/structured-merge-diff/v4 v4.2.3/go.mod h1:qjx8mGObPmV2aSZepjQjbmb2ihdVs8cGKBraizNC69E= +sigs.k8s.io/structured-merge-diff/v4 v4.3.0 h1:UZbZAZfX0wV2zr7YZorDz6GXROfDFj6LvqCRm4VUVKk= +sigs.k8s.io/structured-merge-diff/v4 v4.3.0/go.mod h1:N8hJocpFajUSSeSJ9bOZ77VzejKZaXsTtZo4/u7Io08= sigs.k8s.io/yaml v1.3.0 h1:a2VclLzOGrwOHDiV8EfBGhvjHvP46CtW5j6POvhYGGo= sigs.k8s.io/yaml v1.3.0/go.mod h1:GeOyir5tyXNByN85N/dRIT9es5UQNerPYEKK56eTBm8= From 6d32b082f728797b1ea4beb6052468abfb67c568 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 9 Aug 2023 14:17:17 +0300 Subject: [PATCH 2/3] Add IfNotPresent and Ignore SSA policies Signed-off-by: Stefan Prodan --- api/v1/kustomization_types.go | 4 +++- internal/controller/kustomization_controller.go | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/api/v1/kustomization_types.go b/api/v1/kustomization_types.go index 13537ebb..c3f3e98a 100644 --- a/api/v1/kustomization_types.go +++ b/api/v1/kustomization_types.go @@ -30,7 +30,9 @@ const ( MaxConditionMessageLength = 20000 EnabledValue = "enabled" DisabledValue = "disabled" - MergeValue = "merge" + MergeValue = "Merge" + IfNotPresentValue = "IfNotPresent" + IgnoreValue = "Ignore" ) // KustomizationSpec defines the configuration to calculate the desired state diff --git a/internal/controller/kustomization_controller.go b/internal/controller/kustomization_controller.go index e402920a..883d3319 100644 --- a/internal/controller/kustomization_controller.go +++ b/internal/controller/kustomization_controller.go @@ -658,6 +658,10 @@ func (r *KustomizationReconciler) apply(ctx context.Context, applyOpts.Force = obj.Spec.Force applyOpts.ExclusionSelector = map[string]string{ fmt.Sprintf("%s/reconcile", kustomizev1.GroupVersion.Group): kustomizev1.DisabledValue, + fmt.Sprintf("%s/ssa", kustomizev1.GroupVersion.Group): kustomizev1.IgnoreValue, + } + applyOpts.IfNotPresentSelector = map[string]string{ + fmt.Sprintf("%s/ssa", kustomizev1.GroupVersion.Group): kustomizev1.IfNotPresentValue, } applyOpts.ForceSelector = map[string]string{ fmt.Sprintf("%s/force", kustomizev1.GroupVersion.Group): kustomizev1.EnabledValue, From 743cb798b1aa8fe5e7f2aea069756d77623432f6 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 9 Aug 2023 14:19:00 +0300 Subject: [PATCH 3/3] Document the apply behavior of resources Signed-off-by: Stefan Prodan --- docs/spec/v1/kustomizations.md | 127 ++++++++++++++++++++++----------- 1 file changed, 85 insertions(+), 42 deletions(-) diff --git a/docs/spec/v1/kustomizations.md b/docs/spec/v1/kustomizations.md index c6fc1290..dd7aa4c4 100644 --- a/docs/spec/v1/kustomizations.md +++ b/docs/spec/v1/kustomizations.md @@ -1044,6 +1044,79 @@ cd apps/my-app kustomize create --autodetect --recursive ``` +### Controlling the apply behavior of resources + +To change the apply behaviour for specific Kubernetes resources, you can annotate them with: + +| Annotation | Default | Values | Role | +|-------------------------------------|------------|----------------------------------------------------------------|-----------------| +| `kustomize.toolkit.fluxcd.io/ssa` | `Override` | - `Override`
- `Merge`
- `IfNotPresent`
- `Ignore` | Apply policy | +| `kustomize.toolkit.fluxcd.io/force` | `Disabled` | - `Enabled`
- `Disabled` | Recreate policy | +| `kustomize.toolkit.fluxcd.io/prune` | `Enabled` | - `Enabled`
- `Disabled` | Delete policy | + +**Note:** These annotations should be set in the Kubernetes YAML manifests included +in the Flux Kustomization source (Git, OCI, Bucket). + +#### `kustomize.toolkit.fluxcd.io/ssa` + +##### Override + +The `Override` policy instructs the controller to reconcile the Kubernetes resources +with the desired state (YAML manifests) defined in the Flux source (Git, OCI, Bucket). + +If you use `kubectl` to edit a Kubernetes resource managed by Flux, all changes will be +reverted when the controller reconciles a Flux Kustomization containing that resource. +In order to preserve fields added with `kubectl`, you have to specify +a field manager named `flux-client-side-apply` e.g.: + +```sh +kubectl apply --field-manager=flux-client-side-apply +``` + +##### Merge + +The `Merge` policy instructs the controller to preserve the fields added by other tools to the +Kubernetes resources managed by Flux. + +The fields defined in the manifests applied by the controller will always be overridden, +the `Merge` policy works only for adding new fields that don’t overlap with the desired +state. + +For lists fields which are atomic (e.g. `.spec.tolerations` in PodSpec), Kubernetes +doesn't allow different managers for such fields, therefore any changes to these +fields will be reverted. For more context, please see the Kubernetes enhancement document: +[555-server-side-apply](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/555-server-side-apply/README.md#lists). + +##### IfNotPresent + +The `IfNotPresent` policy instructs the controller to only apply the Kubernetes resources +if they are not present on the cluster. + +This policy can be used for Kubernetes Secrets and ValidatingWebhookConfigurations managed by cert-manager, +where Flux creates the resources with fields that are later on mutated by other controllers. + +##### Ignore + +The `Ignore` policy instructs the controller to skip applying Kubernetes resources +even if they are included in a Flux source (Git, OCI, Bucket). + +#### `kustomize.toolkit.fluxcd.io/force` + +When set to `Enabled`, this policy instructs the controller to recreate the Kubernetes resources +with changes to immutable fields. + +This policy can be used for Kubernetes Jobs to rerun them when their container image changes. + +**Note:** Using this policy for StatefulSets may result in potential data loss. + +#### `kustomize.toolkit.fluxcd.io/prune` + +When set to `Disabled`, this policy instructs the controller to skip the deletion of +the Kubernetes resources subject to [garbage collection](#prune). + +This policy can be used to protect sensitive resources such as Namespaces, PVCs and PVs +from accidental deletion. + ### Role-based access control By default, a Kustomization apply runs under the cluster admin account and can @@ -1502,48 +1575,6 @@ Using `flux`: flux reconcile kustomization ``` -### Customizing reconciliation - -You can configure the controller to ignore in-cluster resources by labelling or -annotating them with: - -```yaml -kustomize.toolkit.fluxcd.io/reconcile: disabled -``` - -**Note:** When the `kustomize.toolkit.fluxcd.io/reconcile` annotation is set to -`disabled`, the controller will no longer apply changes from the source, nor -will it prune the resource. To resume reconciliation, set the annotation to -`enabled` in the source or remove it from the in-cluster object. - -If you use `kubectl` to edit an object managed by Flux, all changes will be -reverted when the controller reconciles a Flux Kustomization containing that -object. In order to preserve fields added with `kubectl`, you have to specify -a field manager named `flux-client-side-apply` e.g.: - -```sh -kubectl apply --field-manager=flux-client-side-apply -``` - -Another option is to annotate or label objects with: - -```yaml -kustomize.toolkit.fluxcd.io/ssa: merge -``` - -**Note:** The fields defined in manifests will always be overridden, the above -procedure works only for adding new fields that don’t overlap with the desired -state. - -For lists fields which are atomic (e.g. `.spec.tolerations` in PodSpec), Kubernetes -doesn't allow different managers for such fields, therefore any changes to these -fields will be undone, even if you specify a manager. For more context, please -see the Kubernetes enhancement document: -[555-server-side-apply](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/555-server-side-apply/README.md#lists). - -To learn how to handle patching failures due to immutable field changes, refer -to [`.spec.force`](#force). - ### Waiting for `Ready` When a change is applied, it is possible to wait for the Kustomization to reach @@ -1558,6 +1589,18 @@ kubectl wait kustomization/ --for=condition=ready --timeout= When you find yourself in a situation where you temporarily want to pause the reconciliation of a Kustomization, you can suspend it using [`.spec.suspend`](#suspend). +To pause the reconciliation of a specific Kubernetes resource managed by a Flux Kustomization, +you can annotate or label the resource in-cluster with: + +```yaml +kustomize.toolkit.fluxcd.io/reconcile: disabled +``` + +**Note:** When the `kustomize.toolkit.fluxcd.io/reconcile` annotation is set to +`disabled`, the controller will no longer apply changes, nor +will it prune the resource. To resume reconciliation, set the annotation to +`enabled` in the source or remove it from the in-cluster object. + #### Suspend a Kustomization In your YAML declaration: