github.com/fluxcd/kustomize-controller

Changelog

v1.9.4 changelog

Container images

• docker.io/fluxcd/kustomize-controller:v1.9.4
• ghcr.io/fluxcd/kustomize-controller:v1.9.4

Supported architectures: linux/amd64, linux/arm64 and linux/arm/v7.

The container images are built on GitHub hosted runners and are signed with cosign and GitHub OIDC.
To verify the images and their provenance (SLSA level 3), please see the security documentation.

Release date: 2026-07-23

This patch release fixes a spec.images entry that sets only some of the image fields discarding the remaining fields already declared for the same image in the kustomization.yaml at spec.path, e.g. overriding only newName produced an untagged image reference.

Fixes:

• Update fluxcd/pkg dependencies #1714

Changelog

v1.9.3 changelog

Container images

• docker.io/fluxcd/kustomize-controller:v1.9.3
• ghcr.io/fluxcd/kustomize-controller:v1.9.3

Supported architectures: linux/amd64, linux/arm64 and linux/arm/v7.

The container images are built on GitHub hosted runners and are signed with cosign and GitHub OIDC.
To verify the images and their provenance (SLSA level 3), please see the security documentation.

Release date: 2026-07-13

This patch release fixes a regression introduced in v1.9.2 where a Kustomization with openapi.path pointing to a URL failed to reconcile with failed to read OpenAPI schema.

Fixes:

• Update fluxcd/pkg dependencies #1703

Changelog

v1.9.2 changelog

Container images

• docker.io/fluxcd/kustomize-controller:v1.9.2
• ghcr.io/fluxcd/kustomize-controller:v1.9.2

Supported architectures: linux/amd64, linux/arm64 and linux/arm/v7.

The container images are built on GitHub hosted runners and are signed with cosign and GitHub OIDC.
To verify the images and their provenance (SLSA level 3), please see the security documentation.

Release date: 2026-07-07

This patch release fixes three bugs. Flux variable substitution is now disabled on the Kustomization CRD by annotating it with kustomize.toolkit.fluxcd.io/substitute: disabled, preventing post-build substitution from corrupting the CRD schema when it contains ${...} sequences. The SOPS dependency was updated to fix decryption of .ini files. Finally, the fluxcd/pkg dependencies were updated to fix a dry-run error where applying a resource with a strategic merge patch could fail with <resource> is invalid.

Fixes:

• Fix CRD going through variable substitution #1694
• Update SOPS dependency to fix .ini file decryption #1699
• Update fluxcd/pkg dependencies #1697

Changelog

v1.9.1 changelog

Container images

• docker.io/fluxcd/kustomize-controller:v1.9.1
• ghcr.io/fluxcd/kustomize-controller:v1.9.1

Supported architectures: linux/amd64, linux/arm64 and linux/arm/v7.

The container images are built on GitHub hosted runners and are signed with cosign and GitHub OIDC.
To verify the images and their provenance (SLSA level 3), please see the security documentation.

Release date: 2026-06-30

This patch release updates Kubernetes to 1.36.2 and the fluxcd/pkg dependencies, adds kubectl categories to the Kustomization CRD and documents the controller's command-line options.

Improvements:

• Add categories to the Kustomization CRD #1682
• Document controller options #1685
• Update fluxcd/pkg dependencies #1683

Changelog

v1.9.0 changelog

Container images

• docker.io/fluxcd/kustomize-controller:v1.9.0
• ghcr.io/fluxcd/kustomize-controller:v1.9.0

Supported architectures: linux/amd64, linux/arm64 and linux/arm/v7.

The container images are built on GitHub hosted runners and are signed with cosign and GitHub OIDC.
To verify the images and their provenance (SLSA level 3), please see the security documentation.

Release date: 2026-06-17

This minor release comes with new features for post-build variable substitution, drift detection, SOPS decryption and Kustomize build metadata, along with various bug fixes and dependency updates.

Kustomization

Post-build substitutions are now stricter by default: the controller fails the reconciliation when a variable without a default value is referenced in the manifests but is missing from the input vars. This behavior is controlled by the StrictPostBuildSubstitutions feature gate, which is now enabled by default and can be opted out of. In addition, a new .spec.postBuild.substituteStrategy: Always option was introduced to always perform substitutions even when no variables are defined, which is useful when the substitution expressions all carry defaults (e.g. ${var:=default}).

Drift detection can now be fine-tuned with ignore rules. The new .spec.ignore field accepts a list of rules selecting JSON pointer paths (optionally scoped to specific targets) to exclude from both drift detection and the apply process.

A new .spec.buildMetadata field allows enabling Kustomize build metadata annotations per Kustomization, supporting the originAnnotations and transformerAnnotations options.

The controller now keeps resources that failed to be pruned in the .status.inventory, ensuring they remain tracked and can be retried on the next reconciliation instead of becoming untracked orphans.

SOPS decryption

SOPS decryption now supports generic Kubernetes workload identity for the OpenBao/Vault transit engine, allowing the controller to authenticate to OpenBao by exchanging a Kubernetes ServiceAccount token for a short-lived OpenBao token through a JWT-backed auth method, instead of using a static token. This is purely additive and non-breaking: the existing sops.vault-token Secret and VAULT_TOKEN environment variable paths are unchanged and take precedence.

Age and SOPS have also been updated to support Age hybrid post-quantum encryption.

General updates

In addition, the Kubernetes dependencies have been updated to v1.36, the controller is now built with Go 1.26 and the source-controller API has been upgraded to v1.9.0. The shared DependencyReference type was migrated to the apis/meta package, preserving backward compatibility through a type alias.

Fixes:

• Keep failed-to-prune resources in .status.inventory #1665

Improvements:

• Enable StrictPostBuildSubstitutions by default #1671
• Introduce substituteStrategy: Always #1672
• Add support for drift detection ignore rules #1627
• Add .spec.buildMetadata optional field to Kustomization API #1632
• Introduce generic Kubernetes workload identity for SOPS OpenBao/Vault #1659
• Update Age and SOPS for Age post-quantum cypher #1601
• Migrate DependencyReference to shared apis/meta type #1656
• Update to Kubernetes 1.36 and Go 1.26 #1660
• Upgrade source-controller API to v1.9.0 #1674
• Various dependency updates #1661 #1662 #1666 #1667 #1668 #1669

Release date: 2026-05-12

This patch release fixes a regression in the management of objects annotated with kustomize.toolkit.fluxcd.io/ssa: IfNotPresent where non-namespaced resources were being deleted and recreated on each reconciliation.

Fixes:

• Fix management of skipped objects #1651

Improvements:

• Update fluxcd/pkg dependencies #1648

Release date: 2026-04-21

This patch release introduces the MigrateAPIVersion feature gate for migrating the API version of resources in managed field entries, which fixes errors like dry-run failed: .spec.accessPolicy: field not declared in schema.

Improvements:

• Introduce support for migrating API version #1639
• Update fluxcd/pkg dependencies #1637

Release date: 2026-04-07

This patch release fixes a race condition where a cancelled reconciliation could leave stale data in the cache, causing Kustomizations to get stuck.

Fixes:

• Requeue on cancellation to avoid stale cache race condition #1625

Release date: 2026-03-12

This patch release fixes reconciliation queue behavior for source watch events while a Kustomization is already reconciling the watched revision.

Fixes:

• Fix enqueing the same revision while reconciling #1614

Improvements:

• Fix docs typo #1609
• Update fluxcd/pkg dependencies #1616

Release date: 2026-02-27

This patch release fixes health check logic for StatefulSets during rolling updates when the Pods are Pending/Unschedulable.

Fixes:

• Fix health check logic for StatefulSets during rolling updates #1602

Improvements:

• Improve docs for .spec.force #1597
• Remove no longer needed workaround for Flux 2.8 #1595

Release date: 2026-02-17

This minor release comes with various bug fixes and improvements.

⚠️ The v1beta2 APIs were removed. Before upgrading the CRDs, Flux users must run flux migrate to migrate the cluster storage off v1beta2.

Kustomization

The controller now cancels in-progress health checks when a new reconciliation request is received, reducing the mean time to recovery (MTTR) in case of failed deployments. This is available through the CancelHealthCheckOnNewRevision feature gate, that previously worked only for new source revisions but now also works for any watch events that trigger a new reconciliation.

A custom SSA stage has been introduced, allowing Role and RoleBinding objects to be applied in the same call even when the impersonated ServiceAccount does not have a ClusterRoleBinding for cluster-admin. This can be specified with the flag --custom-apply-stage-kinds=rbac.authorization.k8s.io/Role.

Health checks now handle Jobs with TTL set to zero seconds that are deleted before or during health checking.

A DirectSourceFetch feature gate has been added to bypass cache for source objects, enabling immediate consistency for source object reads.

General updates

In addition, the Kubernetes dependencies have been updated to v1.35.0, Kustomize has been updated to v5.8.1 and the controller is now built with Go 1.26.

Fixes:

• Fix decryptor copy of auth.Option slices (avoid overrides) #1570

Improvements:

• Reduce the mean time to recovery (MTTR) in case of failed deployments #1536
• Introduce custom SSA stage #1571
• Handle Jobs with TTL in health checks #1578
• Add DirectSourceFetch feature gate to bypass cache for source objects #1586
• Remove deprecated APIs in group kustomize.toolkit.fluxcd.io/v1beta2 #1584
• Various dependency updates #1566 #1572 #1575 #1581 #1585 #1588 #1589

Release date: 2025-11-19

This patch release comes with a series of bug fixes, including Azure Workload Identity in Azure China Cloud. It also adds a feature gate to disable the ConfigMap and Secret watchers, DisableConfigWatchers.

Fixes:

• Fix: skip trying to decrypt remote patches as local #1548
• Add GVK to error message #1547

Improvements:

• Add feature gate for disabling config watchers #1553
• Upgrade k8s to 1.34.2 and c-r to 0.22.4 #1551

Release date: 2025-10-28

This patch release allows running kustomize-controller on the same loopback interface as source-watcher.

Improvements:

• Allow fetching artifacts from a local source-watcher #1539

Release date: 2025-10-08

This patch release comes with various dependency updates.

The controller is now built with Go 1.25.2 which includes fixes for vulnerabilities in the Go stdlib: CVE-2025-58183, CVE-2025-58188 and many others. The full list of security fixes can be found here.

Improvements:

• Update dependencies to Kubernetes v1.34.1 and Go 1.25.2 #1530

Release date: 2025-09-24

This minor release comes with various bug fixes and improvements.

⚠️ The v1beta1 APIs were removed. Before upgrading the CRDs, Flux users must run flux migrate to migrate the cluster storage off v1beta1.

The Kustomization API now supports reconciling content from external storage systems through the new ExternalArtifact CRD. This feature is controlled by the ExternalArtifact feature gate and enables reconciliation of artifacts stored outside of Git repositories.

Kustomizations now track their reconciliation history in .status.history, providing visibility into past reconciliation attempts and their outcomes.

Dependencies can now be evaluated using CEL expressions through the new readyExpr field in dependsOn. This feature is controlled by the AdditiveCELDependencyCheck feature gate and allows for more flexible dependency readiness checks.

The controller now supports global SOPS Age key decryption, allowing centralized management of decryption keys.

Support for workload identity authentication has been added for remote clusters. This is support both at the controller and object levels. For object-level, enable the feature gate ObjectLevelWorkloadIdentity.

The new .spec.ignoreMissingComponents field allows Kustomizations to continue reconciliation even when referenced components are missing, providing more resilient deployments.

A feature gate CancelHealthCheckOnNewRevision has been added to cancel ongoing health checks when a new revision is detected.

In addition, the Kubernetes dependencies have been updated to v1.34, Kustomize has been updated to v5.7 and various other controller dependencies have been updated to their latest version. The controller is now built with Go 1.25.

Fixes:

• Fix skipped entries from SSA being stored in the inventory #1513

Improvements:

• [RFC-0010] Add workload identity authentication for remote clusters #1476
• [RFC-0010] Add multi-tenancy lockdown for decryption and kubeconfig #1495
• [RFC-0010] Add object-level configuration validation #1497
• [RFC-0010] Add support for all Azure clouds for remote cluster authentication #1488
• [RFC-0012] Add support for ExternalArtifact source type #1508
• Add reconciliation history tracking in Kustomization status #1502
• Add CEL expressions for dependency readiness evaluation #1491
• Add .spec.ignoreMissingComponents field to Kustomization API #1507
• Add global SOPS Age key decryption support #1481
• Add label selector for watching ConfigMaps and Secrets #1486
• Add feature gate to cancel health checks on new revisions #1520
• Refactor reconciler to use staged server-side apply #1484
• Remove deprecated APIs in group kustomize.toolkit.fluxcd.io/v1beta1 #1494
• CI improvements with fluxcd/gha-workflows #1512 #1514
• Various dependency updates #1470 #1505 #1511 #1515

Release date: 2025-07-08

This patch release fixes a bug introduced in v1.6.0 that causes SOPS decryption with US Government KMS keys to fail with the error:

STS: AssumeRoleWithWebIdentity, https response error\n   StatusCode: 0, RequestID: ,
request send failed, Post\n \"https://sts.arn.amazonaws.com/\": dial tcp:
lookupts.arn.amazonaws.com on 10.100.0.10:53: no such host

Fixes:

• Fix regression in STS endpoint for SOPS decryption with AWS KMS in US Gov partition #1478

Release date: 2025-05-28

This minor release comes with various bug fixes and improvements.

Kustomization API now supports object-level workload identity by setting .spec.decryption.serviceAccountName to the name of a service account in the same namespace that has been configured with appropriate cloud permissions. For this feature to work, the controller feature gate ObjectLevelWorkloadIdentity must be enabled. See a complete guide here.

Kustomization API now supports the value WaitForTermination for the .spec.deletionPolicy field. This instructs the controller to wait for the deletion of all resources managed by the Kustomization before allowing the Kustomization itself to be deleted. See docs here.

In addition, the Kubernetes dependencies have been updated to v1.33 and various other controller dependencies have been updated to their latest version. The controller is now built with Go 1.24.

Fixes:

• Fix performance regression due to using client without cache #1436
• Fix secret value showing up in logs #1372

Improvements:

• [RFC-0010] Introduce KMS provider decryption with service account #1426 #1449 #1456
• Add WaitForTermination option to DeletionPolicy #1444
• Skip emitting events for suspended Kustomizations #1396
• Various dependency updates #1458 #1448 #1433 #1435 #1429 #1414 #1410 #1401

Release date: 2025-02-25

This patch release fixes a bug introduced in v1.5.0 that was causing spurious logging for deprecated API versions and sometimes failures on health checks.

In addition, all error logs resulting from SOPS decryption failures have been sanitised.

Fixes:

• Fix secret value showing up in logs #1372
• Use lazy restmapper vendored from controller-runtime v0.19 #1377

Release date: 2025-02-18

This minor release comes with various bug fixes and improvements.

The controller has been updated to Kustomize v5.6, please see the kubernetes-sigs/kustomize changelog for more details.

The Kustomization API now supports custom health checks for Custom Resources through Common Expression Language (CEL) expressions. See docs.

The controller now sends an origin revision from OCI artifact annotations to notification-controller on events, which is useful for updating commit statuses on the notification providers that support this feature. See docs.

It is now also possible to control whether or not kustomize-controller will orphan resources when a Kustomization is deleted. See docs.

In addition, the Kubernetes dependencies have been updated to v1.32.1 and various other controller dependencies have been updated to their latest version.

Fixes:

• Clarify precedence in Kustomization substituteFrom #1301
• Remove deprecated object metrics from controllers #1305

Improvements:

• Enable decryption of secrets generated by Kustomize components #1283
• Added decryption of Kustomize patches and refactor SOPS tests #1286
• Allow control of finalization garbage collection #1314
• Add OCI revision to events #1338
• [RFC-0009] Add CEL custom healthchecks #1344
• Add GroupChangeLog feature gate to fix es indexing cardinality #1361
• Various dependency updates #1302 #1304 #1310 #1313 #1318 #1320 #1330 #1348 #1352 #1354 #1359 #1362 #1364 #1358

Release date: 2024-09-27

This minor release comes with various bug fixes and improvements.

kustomize-controller in sharded deployment configuration now supports cross-shard dependency check. This allows a Kustomization to depend on other Kustomizations managed by different controller shards.

In addition, the Kubernetes dependencies have been updated to v1.31.1 and various other controller dependencies have been updated to their latest version. The controller is now built with Go 1.23.

Fixes:

• Fix incorrect use of format strings with the conditions package. #1198

Improvements:

• Update Bucket API to v1 #1253
• Allow cross-shard dependency check #1248
• docs: Clarify .spec.decryption.secretRef usage #1242
• Build with Go 1.23 #1230
• Various dependency updates #1165 #1181 #1212 #1228 #1229 #1233 #1239 #1240 #1243 #1249 #1250 #1251