Legacy Controller Migration
Older versions of Kluctl (pre v2.20.0) relied on a legacy version of the Kluctl controller, named
. If you upgraded from such an older
version and were already using
KluctlDeployments from the
flux.kluctl.io API group, you must migrate these
deployments to the new
To do this, follow the following steps:
- Upgrade the legacy flux-kluctl-controller to at least v0.16.0. This version will introduce a special marker field
into the legacy
KluctlDeploymentstatus and set it to true. This marker field is used to inform the new Kluctl Controller that the legacy controller is now aware of the existence of the new controller.
- If not already done, install the new Kluctl Controller.
- To be on the safe side, disable
for all legacy
KluctlDeploymentobjects. Don’t forget to deploy/apply these changes before continuing with the next step.
- Modify your
KluctlDeploymentmanifests to use the
apiVersion. It’s important to use the same name and namespace as used in the legacy resources. Also read the breaking changes section.
- Deploy/Apply the modified
- At this point, the legacy controller will detect that the
KluctlDeploymentexists twice, once for the legacy API group/version and once for the new group/version. Based on that knowledge, the legacy controller will stop reconciling the legacy
- At the same time, the new controller will detect that the legacy
KluctlDeploymenthas the marker field set, which means that the legacy controller is known to honor the new controller’s existence.
- This will lead to the new controller taking over and reconciling the new
- If you disabled deletion/pruning in step 3., you should undo this on the new
After these steps, the legacy
KluctlDeployment resources will be excluded from reconciliation by the legacy controller.
This means, you can safely remove/prune the legacy resources.
There exist some breaking changes between the legacy
resources and controllers. These are:
Only deploy when resources change
The legacy controller did a full deploy on each reconciliation, following the Flux way of reconciliations. This
behaviour was configurable by allowing you to set
spec.deployInterval: never, which disabled full deployments and
caused the controller to only deploy when the resulting rendered resources actually changed.
The new controller will behave this way by default, unless you explicitly set
spec.deployInterval to some interval
This means, you will have to introduce
spec.deployInterval in case you expect the controller to behave as before or
spec.deployInterval: never if you already used the Kluctl specific behavior.
renameContexts has been removed
spec.renameContexts field is not available anymore. Use
status will not contain full result anymore
The legacy controller wrote the full command result (with objects, diffs, …) into the status field. The new controller will instead only write a summary of the result.
Why no fully automated migration?
I have decided against a fully automated migration as the move of the API group causes resources to have a different identity. This can easily lead to unexpected behaviour and does not play well with GitOps.