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"] + )