Add --target-host parameter for multi-host management

[jeremylenz]

Summary

Adds a --target-host argument to all 8 production foremanctl commands (deploy, features, health, migrate, backup, pull-images, certificate-bundle, checks), allowing users to specify which host to run against instead of the hardcoded quadlet default.

This is a first step toward multi-host management — running commands against different targets such as external proxies or remote servers. Full multi-host workflows will additionally require per-host state isolation (#630), since today all commands share a single parameters.yaml.

The parameter defaults to quadlet when not specified, preserving existing behavior. The value is persisted between runs and can be cleared with --reset-target-host.

For remote hosts, the specified host must be present in the Ansible inventory.

Changes

• New shared metadata fragment _target_host included by all 8 commands
• Playbook hosts: directives use {{ target_host | default('quadlet') }}
• Updated docs/user/parameters.md with a Global Parameters section

Test plan

• foremanctl <command> --help shows --target-host for all 8 commands
• ansible-lint passes
• All playbook tests pass

[ianballou]

I think you might also need to ensure the host is in the Ansible inventory. If so, perhaps it's worth a small docs line.

[ehelms]

This brings feature parity between the forge deploy-dev command and the 8 production foremanctl commands. Previously, only forge deploy-dev supported the --target-host parameter, which allows targeting a host other than the default 'quadlet'.

For me this change is not about parity, it's about the need to run these commands against multiple hosts in some cases such as deploying multiple external proxies or executing a backup of a server vs. a proxy. That's my way of saying can you update the commit message and description to speak more to this idea?

Additionally, while this will unlock the ability to run commands against more targets, this will be limited by #630

@evgeni what do you think? I'm generally in favor of this target-host idea. Is there any more "ansible" way to do it that fits in with our CLI design?

[jeremylenz]

@ehelms Updated the description and commit message. 👍

[ianballou]

What is the intended end state for where we recommend users run foremanctl, if there is one? Do we want users to be able to do every foremanctl action against any reachable host? For example, if setting up smart proxies, will it be totally legit for users to deploy the Foreman and the proxy from some exterior controller machine?

I just want to understand if this target-host option fits in with the end game plan, or if it's a helpful intermediate workaround for the current "quadlet" assumptions.

[jeremylenz]

I will defer to @ehelms to answer this

[ianballou]

I will defer to @ehelms to answer this

Whatever the answer ends up being, I like this 👍

[evgeni]

Why except deploy-proxy? (This is not a "I think you're wrong", more a "I want to understand your trail of thought")

[evgeni]

I like this, but I also think it's dangerous in the current state, so not sure I'd like to expose it to users just yet.

Right now this allows setting up multiple Foreman instances, with the same set of features/configs. I don't think that's terribly useful in most cases? Unless you have a prod and a test box that should be identical and you can manage them from the same controller.

The PR description says that can be used to deploy multiple proxies, but it's not used in deploy-proxy. (And even if we'd expose it there, they would end up having the same config all over, maybe even the same as the main server if you run it from there)

Overall I think I'd like to understand more which user workflows this enables now, without #630 being solved.

[jeremylenz]

Overall I think I'd like to understand more which user workflows this enables now, without #630 being solved.

The one workflow that started it for me is that I was unable to run foremanctl pull-images in a development environment, to update my images.

[jeremylenz]

The PR description says that can be used to deploy multiple proxies, but it's not used in deploy-proxy.

Good catch — deploy-proxy was omitted because it uses hosts: proxy rather than hosts: quadlet, so it wasn't part of the "replace hardcoded quadlet" scope. But if we want to support multi-proxy workflows, adding --target-host there would be the same pattern, just defaulting to proxy instead of quadlet. Happy to add that if we think it's worth including.

Overall I think I'd like to understand more which user workflows this enables now, without #630 being solved.

Agreed that without #630, this is limited to single-target workflows where you're only ever pointing at one host at a time — just not one called quadlet. The immediate motivation was being unable to run commands like foremanctl pull-images in environments where the target host has a different name in the inventory.