diff --git a/changelogs/fragments/20260807-helm-cleanup-on-fail.yaml b/changelogs/fragments/20260807-helm-cleanup-on-fail.yaml new file mode 100644 index 00000000..1876aa3d --- /dev/null +++ b/changelogs/fragments/20260807-helm-cleanup-on-fail.yaml @@ -0,0 +1,3 @@ +--- +minor_changes: + - helm - add the ``cleanup_on_fail`` option, mapping to the ``--cleanup-on-fail`` flag, to allow deletion of new resources created during a failed upgrade. It complements ``atomic`` and can be combined with it, but cannot be used with ``replace``, since that deploys through ``helm install`` which does not accept the flag (https://github.com/ansible-collections/kubernetes.core/pull/1206). diff --git a/docs/kubernetes.core.helm_module.rst b/docs/kubernetes.core.helm_module.rst index 09a6c824..f5a4838e 100644 --- a/docs/kubernetes.core.helm_module.rst +++ b/docs/kubernetes.core.helm_module.rst @@ -157,6 +157,29 @@ Parameters
Chart version to install. If this is not specified, the latest version is installed.
+ + +
+ cleanup_on_fail + +
+ boolean +
+
added in 6.6.0
+ + + + + +
Allow deletion of new resources created during a failed upgrade.
+
Maps to the --cleanup-on-fail flag, which is available since helm 3.0.0 and was not renamed in Helm v4.
+
Complements O(atomic) rather than replacing it, and the two can be combined so that a rollback also drops resources orphaned by the failed upgrade.
+
Helm only accepts this flag on helm upgrade, so it cannot be used together with O(replace), which deploys through helm install.
+ +
diff --git a/plugins/modules/helm.py b/plugins/modules/helm.py index 536165aa..df21b95a 100644 --- a/plugins/modules/helm.py +++ b/plugins/modules/helm.py @@ -207,6 +207,18 @@ options: O(atomic) option works the same way regardless of the installed Helm version. type: bool default: False + cleanup_on_fail: + description: + - Allow deletion of new resources created during a failed upgrade. + - Maps to the C(--cleanup-on-fail) flag, which is available since helm 3.0.0 and + was not renamed in Helm v4. + - Complements O(atomic) rather than replacing it, and the two can be combined so + that a rollback also drops resources orphaned by the failed upgrade. + - Helm only accepts this flag on C(helm upgrade), so it cannot be used together + with O(replace), which deploys through C(helm install). + type: bool + default: False + version_added: 6.6.0 server_side: description: - Control Helm v4 server-side apply when installing or upgrading a release. @@ -607,6 +619,7 @@ def deploy( values_files, history_max, atomic=False, + cleanup_on_fail=False, create_namespace=False, replace=False, post_renderer=None, @@ -667,6 +680,17 @@ def deploy( else: deploy_command += " --atomic" + if cleanup_on_fail: + # '--cleanup-on-fail' is only accepted by 'helm upgrade', so it cannot be + # combined with 'replace', which deploys through 'helm install'. The flag + # exists since helm 3.0.0 and kept its name in v4, so no version gate is + # needed on top of the module-wide helm >= 3.0.0 requirement. + if replace: + module.fail_json( + msg="cleanup_on_fail is only supported by 'helm upgrade' and cannot be used with replace=true" + ) + deploy_command += " --cleanup-on-fail" + if timeout: deploy_command += " --timeout " + timeout @@ -962,6 +986,7 @@ def argument_spec(): wait_timeout=dict(type="str"), timeout=dict(type="str"), atomic=dict(type="bool", default=False), + cleanup_on_fail=dict(type="bool", default=False), server_side=dict(type="str", choices=["auto", "true", "false"]), force_conflicts=dict(type="bool", default=False), create_namespace=dict(type="bool", default=False), @@ -1027,6 +1052,7 @@ def main(): wait = module.params.get("wait") wait_timeout = module.params.get("wait_timeout") atomic = module.params.get("atomic") + cleanup_on_fail = module.params.get("cleanup_on_fail") server_side = module.params.get("server_side") force_conflicts = module.params.get("force_conflicts") create_namespace = module.params.get("create_namespace") @@ -1157,6 +1183,7 @@ def main(): False, values_files=values_files, atomic=atomic, + cleanup_on_fail=cleanup_on_fail, server_side=server_side, force_conflicts=force_conflicts, create_namespace=create_namespace, @@ -1243,6 +1270,7 @@ def main(): force, values_files=values_files, atomic=atomic, + cleanup_on_fail=cleanup_on_fail, server_side=server_side, force_conflicts=force_conflicts, create_namespace=create_namespace, diff --git a/tests/unit/modules/test_module_helm.py b/tests/unit/modules/test_module_helm.py index 3b219bdf..495942cf 100644 --- a/tests/unit/modules/test_module_helm.py +++ b/tests/unit/modules/test_module_helm.py @@ -23,6 +23,48 @@ from ansible_collections.kubernetes.core.tests.unit.utils.ansible_module_mock im set_module_args, ) +CHART_INFO = { + "apiVersion": "v2", + "appVersion": "default", + "description": "A chart used in molecule tests", + "name": "test-chart", + "type": "application", + "version": "0.1.0", +} + + +def patch_ansible_module(test_case): + """Patch AnsibleModule's exit/fail/bin-path hooks for the duration of test_case.""" + mock_module_helper = patch.multiple( + basic.AnsibleModule, + exit_json=exit_json, + fail_json=fail_json, + get_bin_path=get_bin_path, + ) + mock_module_helper.start() + test_case.addCleanup(mock_module_helper.stop) + + +def deploy_command_for_version(args, helm_version): + """Run helm.main() against a mocked helm of helm_version and return its command. + + Only the fresh-install path is mocked, so the caller sees the command built by + deploy(). Failures raised by the module (AnsibleFailJson) propagate to the test. + """ + set_module_args(args) + helm.get_release_status = MagicMock(return_value=None) + helm.fetch_chart_info = MagicMock(return_value=CHART_INFO) + with patch.object( + helm.AnsibleHelmModule, "get_helm_version", return_value=helm_version + ): + with patch.object(basic.AnsibleModule, "run_command") as mock_run_command: + mock_run_command.return_value = (0, "configuration updated", "") + try: + helm.main() + except AnsibleExitJson as exc: + return exc.args[0]["command"] + raise AssertionError("helm.main() did not exit successfully") + class TestDependencyUpdateWithoutChartRepoUrlOption(unittest.TestCase): def setUp(self): @@ -716,39 +758,10 @@ class TestAtomicFlagHelmVersion(unittest.TestCase): """Helm v4 renamed '--atomic' to '--rollback-on-failure' (issue #1143).""" def setUp(self): - self.mock_module_helper = patch.multiple( - basic.AnsibleModule, - exit_json=exit_json, - fail_json=fail_json, - get_bin_path=get_bin_path, - ) - self.mock_module_helper.start() - self.addCleanup(self.mock_module_helper.stop) - - self.chart_info = { - "apiVersion": "v2", - "appVersion": "default", - "description": "A chart used in molecule tests", - "name": "test-chart", - "type": "application", - "version": "0.1.0", - } - - def _run_with_version(self, args, helm_version): - set_module_args(args) - helm.get_release_status = MagicMock(return_value=None) - helm.fetch_chart_info = MagicMock(return_value=self.chart_info) - with patch.object( - helm.AnsibleHelmModule, "get_helm_version", return_value=helm_version - ): - with patch.object(basic.AnsibleModule, "run_command") as mock_run_command: - mock_run_command.return_value = (0, "configuration updated", "") - with self.assertRaises(AnsibleExitJson) as result: - helm.main() - return result.exception.args[0]["command"] + patch_ansible_module(self) def test_atomic_uses_atomic_flag_on_helm_v3(self): - command = self._run_with_version( + command = deploy_command_for_version( { "release_name": "test", "release_namespace": "test", @@ -761,7 +774,7 @@ class TestAtomicFlagHelmVersion(unittest.TestCase): assert "--rollback-on-failure" not in command def test_atomic_uses_rollback_on_failure_on_helm_v4(self): - command = self._run_with_version( + command = deploy_command_for_version( { "release_name": "test", "release_namespace": "test", @@ -775,7 +788,7 @@ class TestAtomicFlagHelmVersion(unittest.TestCase): def test_atomic_with_replace_uses_rollback_on_failure_on_helm_v4(self): # 'replace' uses 'helm install', where '--atomic' is removed in v4. - command = self._run_with_version( + command = deploy_command_for_version( { "release_name": "test", "release_namespace": "test", @@ -788,3 +801,92 @@ class TestAtomicFlagHelmVersion(unittest.TestCase): assert " install " in command assert "--rollback-on-failure" in command assert "--atomic" not in command + + +class TestCleanupOnFail(unittest.TestCase): + """'--cleanup-on-fail' is upgrade-only and unchanged in Helm v4 (issue #1198).""" + + def setUp(self): + patch_ansible_module(self) + + def test_cleanup_on_fail_not_set_by_default(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + }, + "3.17.0", + ) + assert "--cleanup-on-fail" not in command + + def test_cleanup_on_fail_on_helm_v3(self): + # '--cleanup-on-fail' exists since helm 3.0.0, the module-wide minimum. + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "cleanup_on_fail": True, + }, + "3.0.0", + ) + assert " upgrade -i" in command + assert "--cleanup-on-fail" in command + + def test_cleanup_on_fail_keeps_same_flag_on_helm_v4(self): + # Unlike '--atomic', the flag was not renamed in Helm v4. + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "cleanup_on_fail": True, + }, + "4.0.0", + ) + assert "--cleanup-on-fail" in command + + def test_cleanup_on_fail_combines_with_atomic_on_helm_v3(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "atomic": True, + "cleanup_on_fail": True, + }, + "3.17.0", + ) + assert "--atomic" in command + assert "--rollback-on-failure" not in command + assert "--cleanup-on-fail" in command + + def test_cleanup_on_fail_combines_with_atomic_on_helm_v4(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "atomic": True, + "cleanup_on_fail": True, + }, + "4.0.0", + ) + assert "--rollback-on-failure" in command + assert "--atomic" not in command + assert "--cleanup-on-fail" in command + + def test_cleanup_on_fail_with_replace_fails(self): + # 'replace' deploys via 'helm install', which has no '--cleanup-on-fail'. + with self.assertRaises(AnsibleFailJson): + deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "cleanup_on_fail": True, + "replace": True, + }, + "3.17.0", + )