From 10584acdbb5415ce48bb3329416519094cf6ed40 Mon Sep 17 00:00:00 2001 From: Yuriy Novostavskiy Date: Wed, 16 Sep 2026 12:25:48 +0200 Subject: [PATCH] fix(helm): validate reuse_values against reset_values and replace (#1230) * fix(helm): validate reuse_values against reset_values and replace reset_values defaults to true and helm ignores --reuse-values whenever --reset-values is passed, so the documented reuse_values example was a no-op. Warn rather than flip the default, which would silently change what existing playbooks deploy. helm install accepts neither --reuse-values nor --reset-then-reuse-values, so pairing either with replace could only ever make helm report an unknown flag. Fail up front instead, and keep both flags inside the upgrade branch. Fixes #1229 * fix(docstring): neither nor replacing Co-authored-by: Don Naro * fix(helm): warn instead of failing on replace + reuse_values reuse_values has been accepted since 3.0.0, and a converged release never reaches deploy(), so these combinations pass in playbooks today. Failing in main() would turn them red on upgrade. The flags are already dropped from the install path, so warning leaves a valid command behind. Splits the changelog fragment per user-visible change, and covers the helm diff path, whose 'not replace' guards the hard failure had made unreachable. Changes based on the @abikouo's feedback --------- Co-authored-by: Don Naro --- .../20260826-helm-value-reuse-options.yaml | 6 + plugins/modules/helm.py | 113 +++++- tests/unit/modules/test_module_helm.py | 335 ++++++++++++++++++ 3 files changed, 435 insertions(+), 19 deletions(-) create mode 100644 changelogs/fragments/20260826-helm-value-reuse-options.yaml diff --git a/changelogs/fragments/20260826-helm-value-reuse-options.yaml b/changelogs/fragments/20260826-helm-value-reuse-options.yaml new file mode 100644 index 00000000..b84a1b20 --- /dev/null +++ b/changelogs/fragments/20260826-helm-value-reuse-options.yaml @@ -0,0 +1,6 @@ +--- +bugfixes: + - helm - fix the ``reuse_values`` example, which set only ``reuse_values=true``. ``reset_values`` defaults to ``true`` and helm ignores ``--reuse-values`` whenever ``--reset-values`` is passed, so following the example reset the release values instead of reusing them (https://github.com/ansible-collections/kubernetes.core/pull/1230). + - helm - do not pass the upgrade-only ``--reuse-values`` and ``--reset-then-reuse-values`` flags to ``helm install``, which rejected them with ``unknown flag`` whenever ``reuse_values`` or ``reset_then_reuse_values`` was combined with ``replace`` (https://github.com/ansible-collections/kubernetes.core/pull/1230). +minor_changes: + - helm - warn when ``reuse_values`` or ``reset_then_reuse_values`` is requested in a combination helm ignores, which happens by default because ``reset_values`` defaults to ``true``, and whenever either is combined with ``replace``. The option descriptions and the examples now state that ``reset_values`` has to be set to ``false`` for either option to take effect (https://github.com/ansible-collections/kubernetes.core/pull/1230). diff --git a/plugins/modules/helm.py b/plugins/modules/helm.py index f00ecf35..88cb9ab4 100644 --- a/plugins/modules/helm.py +++ b/plugins/modules/helm.py @@ -132,15 +132,19 @@ options: version_added: 2.4.0 reuse_values: description: - - When upgrading package, specifies wether to reuse the last release's values and merge in any overrides from parameters I(release_values), - I(values_files) or I(set_values). - - If I(reset_values) is set to C(True), this is ignored. + - When upgrading package, specifies whether to reuse the last release's values and merge in any overrides from parameters O(release_values), + O(values_files) or O(set_values). + - Helm ignores this when C(--reset-values) is passed. Since O(reset_values) defaults to V(true), it has to be set to V(false) + for this option to take any effect. + - C(helm install) does not accept C(--reuse-values), so this option is ignored when O(replace) is set. + - The module warns whenever one of those combinations makes this option a no-op. type: bool required: false version_added: 3.0.0 reset_values: description: - When upgrading package, reset the values to the ones built into the chart. + - Defaults to V(true), which makes helm ignore O(reuse_values) and O(reset_then_reuse_values). Set it to V(false) to use either of them. type: bool required: false default: True @@ -149,7 +153,10 @@ options: description: - When upgrading package, reset the values to the ones built into the chart, apply the last release's values and merge in any overrides from parameters O(release_values), O(values_files) or O(set_values). - - If O(reset_values) or O(reuse_values) is set to V(True), this is ignored. + - Helm ignores this when C(--reset-values) or C(--reuse-values) is passed. Since O(reset_values) defaults to V(true), it has to be + set to V(false), and O(reuse_values) left unset or V(false), for this option to take any effect. + - C(helm install) does not accept C(--reset-then-reuse-values), so this option is ignored when O(replace) is set. + - The module warns whenever one of those combinations makes this option a no-op. - This feature requires helm diff >= 3.9.12. type: bool required: false @@ -426,15 +433,30 @@ EXAMPLES = r""" enabled: True # Deploy latest version +# 'reset_values' defaults to true and helm ignores '--reuse-values' when it is set, +# so it has to be turned off explicitly. - name: Deploy latest version of Grafana chart using reuse_values kubernetes.core.helm: name: test chart_ref: stable/grafana release_namespace: monitoring reuse_values: true + reset_values: false values: replicas: 2 version: 3e8ec0b2dffa40fb97d5342e4af887de95faa8c61a62480dd7f8aa03dffcf533 + +# Same for 'reset_then_reuse_values', which helm ignores when either +# '--reset-values' or '--reuse-values' is set. +- name: Deploy latest version of Grafana chart using reset_then_reuse_values + kubernetes.core.helm: + name: test + chart_ref: stable/grafana + release_namespace: monitoring + reset_then_reuse_values: true + reset_values: false + values: + replicas: 2 """ RETURN = r""" @@ -624,6 +646,51 @@ def fetch_chart_info( return yaml.safe_load(strip_registry_progress(out)) +def validate_value_options( + module, replace, reuse_values, reset_values, reset_then_reuse_values +): + """ + Check the value-reuse options against each other and against 'replace'. + + 'helm install' accepts none of these flags, so 'replace' drops all three. The rest + are precedence rules helm applies silently: '--reset-values' wins over + '--reuse-values', and both win over '--reset-then-reuse-values'. Since 'reset_values' + defaults to true, requesting either of the other two on its own is a no-op. + + Warn rather than fail throughout. Every one of these combinations is accepted by + playbooks today: 'reuse_values' has existed since 3.0.0, and a release that is + already converged never reaches deploy(), so the invalid command was never built. + Failing here would turn tasks that pass today into tasks that fail. + """ + if replace: + for name, requested in ( + ("reuse_values", reuse_values is not None), + ("reset_then_reuse_values", reset_then_reuse_values), + ): + if requested: + module.warn( + "{0} is ignored because replace=true deploys through 'helm install'," + " which does not accept the flag.".format(name) + ) + return + + if reset_values: + for name, requested in ( + ("reuse_values", reuse_values), + ("reset_then_reuse_values", reset_then_reuse_values), + ): + if requested: + module.warn( + "{0} is ignored because reset_values is true. " + "Set reset_values=false to make it take effect.".format(name) + ) + elif reuse_values and reset_then_reuse_values: + module.warn( + "reset_then_reuse_values is ignored because reuse_values is true. " + "Set reuse_values=false to make it take effect." + ) + + def deploy( module, command, @@ -666,24 +733,28 @@ def deploy( deploy_command += " --dependency-update" else: deploy_command = command + " upgrade -i" # install/upgrade - if reset_values: - deploy_command += " --reset-values" if take_ownership: deploy_command += " --take-ownership" - if reuse_values is not None: - deploy_command += " --reuse-values=" + str(reuse_values) + # '--reset-values', '--reuse-values' and '--reset-then-reuse-values' are all + # upgrade-only flags, so they must not leak into the 'replace' branch above. + # validate_value_options() has already warned about that combination. + if reset_values: + deploy_command += " --reset-values" - if reset_then_reuse_values: - helm_version = module.get_helm_version() - if LooseVersion(helm_version) < LooseVersion("3.14.0"): - module.fail_json( - msg="reset_then_reuse_values requires helm >= 3.14.0, current version is {0}".format( - helm_version + if reuse_values is not None: + deploy_command += " --reuse-values=" + str(reuse_values) + + if reset_then_reuse_values: + helm_version = module.get_helm_version() + if LooseVersion(helm_version) < LooseVersion("3.14.0"): + module.fail_json( + msg="reset_then_reuse_values requires helm >= 3.14.0, current version is {0}".format( + helm_version + ) ) - ) - else: - deploy_command += " --reset-then-reuse-values" + else: + deploy_command += " --reset-then-reuse-values" if wait: deploy_command += " --wait" @@ -918,10 +989,10 @@ def helmdiff_check( if set_value_args: cmd += " " + set_value_args - if reuse_values: + if not replace and reuse_values: cmd += " --reuse-values" - if reset_then_reuse_values: + if not replace and reset_then_reuse_values: helm_diff_version = get_plugin_version("diff") helm_version = module.get_helm_version() fail_msg = "" @@ -1176,6 +1247,10 @@ def main(): ) changed = True elif release_state == "present": + validate_value_options( + module, replace, reuse_values, reset_values, reset_then_reuse_values + ) + if chart_version is not None: helm_cmd += " --version=" + chart_version diff --git a/tests/unit/modules/test_module_helm.py b/tests/unit/modules/test_module_helm.py index 495942cf..2a25b8c3 100644 --- a/tests/unit/modules/test_module_helm.py +++ b/tests/unit/modules/test_module_helm.py @@ -66,6 +66,37 @@ def deploy_command_for_version(args, helm_version): raise AssertionError("helm.main() did not exit successfully") +def diff_command_for_version(args, helm_version="3.17.0", helm_diff_version="3.14.0"): + """Run helm.main() against an existing release and return the 'helm diff' command. + + The release is reported as deployed and helm diff as installed, so main() takes the + idempotency branch. The diff output is empty, so nothing is deployed afterwards and + the first command run is the one helmdiff_check() built. + """ + set_module_args(args) + helm.get_release_status = MagicMock( + return_value={ + "status": "deployed", + "values": {}, + "release_values": {}, + "chart": "{0}-{1}".format(CHART_INFO["name"], CHART_INFO["version"]), + "app_version": CHART_INFO["appVersion"], + } + ) + helm.fetch_chart_info = MagicMock(return_value=CHART_INFO) + helm.get_plugin_version = MagicMock(return_value=helm_diff_version) + 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, "", "") + try: + helm.main() + except AnsibleExitJson: + return mock_run_command.call_args_list[0][0][0] + raise AssertionError("helm.main() did not exit successfully") + + class TestDependencyUpdateWithoutChartRepoUrlOption(unittest.TestCase): def setUp(self): self.mock_module_helper = patch.multiple( @@ -890,3 +921,307 @@ class TestCleanupOnFail(unittest.TestCase): }, "3.17.0", ) + + +class TestValueReuseOptions(unittest.TestCase): + """reset_values wins over reuse_values, and both are upgrade-only (issue #1229).""" + + def setUp(self): + patch_ansible_module(self) + + def test_reuse_values_alone_is_overridden_by_the_reset_values_default(self): + # What the pre-fix example in the docs produced: helm ignores '--reuse-values'. + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + }, + "3.17.0", + ) + assert "--reset-values" in command + assert "--reuse-values=True" in command + + def test_reuse_values_with_reset_values_disabled(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "reset_values": False, + }, + "3.17.0", + ) + assert "--reset-values" not in command + assert "--reuse-values=True" in command + + def test_reset_then_reuse_values_with_reset_values_disabled(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "reset_values": False, + }, + "3.17.0", + ) + assert "--reset-values" not in command + assert "--reset-then-reuse-values" in command + + def test_reuse_values_with_replace_is_dropped_and_warns(self): + # 'replace' deploys via 'helm install', which has no '--reuse-values'. + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "replace": True, + }, + "3.17.0", + ) + assert " install" in command + assert "--reuse-values" not in command + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reuse_values is ignored because replace=true" in warning + for warning in warnings + ) + + def test_reuse_values_false_with_replace_is_dropped_and_warns(self): + # Even 'reuse_values: false' used to emit '--reuse-values=False' on install. + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": False, + "replace": True, + }, + "3.17.0", + ) + assert "--reuse-values" not in command + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reuse_values is ignored because replace=true" in warning + for warning in warnings + ) + + def test_reset_then_reuse_values_with_replace_is_dropped_and_warns(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "replace": True, + }, + "3.17.0", + ) + assert "--reset-then-reuse-values" not in command + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reset_then_reuse_values is ignored because replace=true" in warning + for warning in warnings + ) + + def test_replace_alone_keeps_working(self): + command = deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "replace": True, + }, + "3.17.0", + ) + assert " install" in command + assert "--reuse-values" not in command + assert "--reset-values" not in command + + def test_reuse_values_alone_warns(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + }, + "3.17.0", + ) + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any("reuse_values is ignored" in warning for warning in warnings) + + def test_reset_then_reuse_values_alone_warns(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + }, + "3.17.0", + ) + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reset_then_reuse_values is ignored" in warning for warning in warnings + ) + + def test_reset_then_reuse_values_warns_when_reuse_values_wins(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "reset_then_reuse_values": True, + "reset_values": False, + }, + "3.17.0", + ) + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reset_then_reuse_values is ignored because reuse_values is true" in warning + for warning in warnings + ) + + def test_no_warning_when_options_are_combined_correctly(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + deploy_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "reset_values": False, + }, + "3.17.0", + ) + assert mock_warn.call_args_list == [] + + +class TestValueReuseOptionsWithHelmDiff(unittest.TestCase): + """The same options on the idempotency path, where 'helm diff' builds the command.""" + + def setUp(self): + patch_ansible_module(self) + + def test_reuse_values_alone_is_overridden_by_the_reset_values_default(self): + # helm diff is handed both flags and applies helm's precedence, which is why + # 'reuse_values' on its own still reports a change (issue #1229). + command = diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + } + ) + assert "--reset-values=True" in command + assert "--reuse-values" in command + + def test_reuse_values_with_reset_values_disabled(self): + command = diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "reset_values": False, + } + ) + assert "--reset-values=False" in command + assert "--reuse-values" in command + + def test_reset_then_reuse_values_with_reset_values_disabled(self): + command = diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "reset_values": False, + } + ) + assert "--reset-values=False" in command + assert "--reset-then-reuse-values" in command + + def test_reuse_values_with_replace_is_dropped_and_warns(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + command = diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reuse_values": True, + "replace": True, + } + ) + assert "--reuse-values" not in command + assert "--reset-values" not in command + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reuse_values is ignored because replace=true" in warning + for warning in warnings + ) + + def test_reset_then_reuse_values_with_replace_is_dropped_and_warns(self): + with patch.object(basic.AnsibleModule, "warn") as mock_warn: + command = diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "replace": True, + } + ) + assert "--reset-then-reuse-values" not in command + warnings = [call.args[0] for call in mock_warn.call_args_list] + assert any( + "reset_then_reuse_values is ignored because replace=true" in warning + for warning in warnings + ) + + def test_reset_then_reuse_values_requires_helm_3_14(self): + with self.assertRaises(AnsibleFailJson) as result: + diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "reset_values": False, + }, + helm_version="3.13.0", + ) + assert ( + "reset_then_reuse_values requires helm >= 3.14.0" + in result.exception.args[0]["msg"] + ) + + def test_reset_then_reuse_values_requires_helm_diff_3_9_12(self): + with self.assertRaises(AnsibleFailJson) as result: + diff_command_for_version( + { + "release_name": "test", + "release_namespace": "test", + "chart_ref": "chart1", + "reset_then_reuse_values": True, + "reset_values": False, + }, + helm_diff_version="3.9.0", + ) + assert ( + "reset_then_reuse_values requires helm diff >= 3.9.12" + in result.exception.args[0]["msg"] + )