Add hint about related setting for REX concurrency by maximiliankolb · Pull Request #4239 · theforeman/foreman-documentation

maximiliankolb · 2025-09-11T12:35:27Z

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Fixes #38247 (Missing docs on how to REX batching works)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Untested!

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.16/Katello 4.18 (Satellite 6.18)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
We do not accept PRs for Foreman older than 3.9.

Review checklists

Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):

The PR documents a recommended, user-friendly path.
The PR removes steps that have been made unnecessary or obsolete.
Any steps introduced or updated in the PR have been tested to confirm that they lead to the documented end result.

Style review (by a Technical Writer who did not author the PR):

The PR conforms with the team's style guidelines.
The PR introduces documentation that describes a user story rather than a product feature.

maximiliankolb · 2025-09-11T12:37:56Z

guides/common/modules/ref_advanced-settings-in-the-job-wizard.adoc

 Defines the maximum number of jobs executed at once.
 This can prevent overload of system resources in a case of executing the job on a large number of hosts.
+
+If `foreman_proxy_ansible_batch_size` is set, {SmartProxies} run batches of concurrent remote execution jobs.


Does this only work for foreman_ansible, but not for foreman_remote_execution?

Does foreman_remote_execution "borrow" the setting from foreman-tasks? theforeman/foreman_remote_execution@8016206 & https://github.com/theforeman/foreman-tasks/blob/master/app/lib/actions/proxy_action.rb#L207

github-actions · 2025-09-11T12:40:53Z

The PR preview for 5383d34 is available at theforeman-foreman-documentation-preview-pr-4239.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

MartinSpiessl

I had a look again and left a few comments. What the foreman actually does is on a different page entirely, it might greatly deviate from what we can deduce from the help text of the settings!

MartinSpiessl · 2025-11-14T21:48:01Z

guides/common/modules/ref_advanced-settings-in-the-job-wizard.adoc

 Defines the maximum number of jobs executed at once.
 This can prevent overload of system resources in a case of executing the job on a large number of hosts.
+
+If a batch size is set, {SmartProxies} run batches of concurrent remote execution jobs.


The popup in the UI talks about "tasks", here we now seem to talk about number of "jobs". In foreman, one job can contain multiple hosts, and hence there can be multiple tasks per job, at least that is what I observed. I guess we should talk about "tasks" here in line 47 (and 45)! I just tried it by running a ansible command "uptime" on some hosts, with concurrency set to 3. It then shows me in the job the following info text:

Schedule
Concurrency level limited to: 3 tasks at a time

And I see how it starts the "uptime" command on at most 3 hosts at a time, making its way down the list of host names. These are the "tasks" corresponding to this "job", which are also listed separately on the foreman_tasks/tasks page.

Changed jobs to tasks.

MartinSpiessl · 2025-11-14T21:49:49Z

guides/common/modules/ref_advanced-settings-in-the-job-wizard.adoc

+
+If a batch size is set, {SmartProxies} run batches of concurrent remote execution jobs.
+For Ansible-based remote execution jobs, change the `foreman_ansible_proxy_batch_size` setting in the {ProjectWebUI} under *Administer* > *Settings* on the *Ansible* tab.
+For Script-based remote execution jobs, change the `foreman_tasks_proxy_batch_size` setting in the {ProjectWebUI} under *Administer* > *Settings* on the *Tasks* tab.


I finally found "foreman_tasks_proxy_batch_trigger", which is a boolean setting (default is true) which controls whether this feature is actually enabled. This information could be added here as well, as it is crucial that this is not set to false, otherwise these two options are claimed to have no effect.

This is correct based on "master" in foreman-tasks:

$ cat lib/foreman_tasks/engine.rb | sed -n "80,89p" setting('foreman_tasks_proxy_batch_trigger', type: :boolean, description: N_('Allow triggering tasks on the smart proxy in batches'), default: true, full_name: N_('Allow proxy batch tasks')) setting('foreman_tasks_proxy_batch_size', type: :integer, description: N_('Number of tasks which should be sent to the smart proxy in one request, if foreman_tasks_proxy_batch_trigger is enabled'), default: 100, full_name: N_('Proxy tasks batch size'))

However, I don't quite understand yet a) why we should mention/explain this if the default value is correct/sane and b) I still cannot reproduce the user story behind this.

MartinSpiessl · 2025-11-14T22:02:03Z

guides/common/modules/ref_advanced-settings-in-the-job-wizard.adoc

 This can prevent overload of system resources in a case of executing the job on a large number of hosts.
+
+If a batch size is set, {SmartProxies} run batches of concurrent remote execution jobs.
+For Ansible-based remote execution jobs, change the `foreman_ansible_proxy_batch_size` setting in the {ProjectWebUI} under *Administer* > *Settings* on the *Ansible* tab.


not quite, foreman_ansible_proxy_batch_size is empty by default. Then foreman_tasks_proxy_batch_size will be taken also for ansible-based remote execution jobs. If you set foreman_ansible_proxy_batch_size to some value, then this one overrides the batch size for ansible-based jobs.

This is correct based on "master" in foreman_ansible:

$ cat lib/foreman_ansible/register.rb | sed -n "78,84p" setting 'foreman_ansible_proxy_batch_size', type: :integer, description: N_('Number of tasks which should be sent to the smart proxy in one request, '\ 'if foreman_tasks_proxy_batch_trigger is enabled. '\ 'If set, overrides foreman_tasks_proxy_batch_size setting for Ansible jobs.'), default: nil, full_name: N_('Proxy tasks batch size for Ansible')

However, the downstream ticket does not mention using Ansible-based REX. I am trying to understand Script-based REX first.

The setting itself is explained under Administer > Settings > Ansible.

guides/common/modules/ref_advanced-settings-in-the-job-wizard.adoc

MartinSpiessl · 2025-11-16T10:29:25Z

@adamruzicka, could you help out here in explaining what actually happens when these options are set?

In theforeman/foreman_remote_execution@a5027ab#diff-a54f77c21c5cd2f600e20d3b2d82bb7bf6972ba0914916ecdae4ba48ad9d3698R102 you added the hint to the concurrency level option for remote execution hobs, stating:

Run at most N tasks at a time. If this is set and proxy batch triggering is enabled, then tasks are triggered on the smart proxy in batches of size 1.

In theforeman/foreman-tasks@b58b21d#diff-c8d459533136a218721813c3a97815f081d466276f1720410f092422eddd6e7dR14-R15 you elaborated on the proxy batching options:

set('foreman_tasks_proxy_batch_trigger', N_('Allow triggering tasks on the smart proxy in batches'), true),
set('foreman_tasks_proxy_batch_size', N_('Number of tasks which should be sent to the smart proxy in one request, if foreman_tasks_proxy_batch_trigger is enabled'), 1000)

Are these descriptions of how these 3 work still correct?
What is the difference between sending a task to a smart proxy and triggering it?
Is concurrency level really ignored if foreman_tasks_proxy_batch_trigger is not enabled? My tests would indicate otherwise

MartinSpiessl · 2025-11-16T10:43:24Z

Is concurrency level really ignored if foreman_tasks_proxy_batch_trigger is not enabled? My tests would indicate otherwise

I think I figured this part out:

If this is set and proxy batch triggering is enabled, then tasks are triggered on the smart proxy in batches of size 1.

This addition is meant as a hint that concurrency level will reduce the batch size to 1 as a side effect, but it will also work if proxy batch triggering is disabled.

adamruzicka · 2025-11-18T08:38:11Z

Are these descriptions of how these 3 work still correct?

proxy_batch_trigger, proxy_batch_size and what is the third?

What is the difference between sending a task to a smart proxy and triggering it?

None really

Is concurrency level really ignored if foreman_tasks_proxy_batch_trigger is not enabled?
This addition is meant as a hint that concurrency level will reduce the batch size to 1 as a side effect, but it will also work if proxy batch triggering is disabled.

Correct, although this behaviour might have changed since theforeman/foreman_remote_execution#827 . It won't be hard limited to 1, but it will be something a number from 1 to min($hosts_count, $concurrency_level, $proxy_batch_size), depending on timing.

Fixes #38247 (Missing docs on how to REX batching works)

Lennonka · 2026-01-27T18:23:05Z

guides/common/modules/proc_running-remote-execution-jobs-in-batches.adoc

+= Running remote execution jobs in batches
+
+[role="_abstract"]
+You can run remote execution jobs in batches.


Please elaborate on the "why" and "when" to enable this.

sbernhard · 2026-02-03T21:15:49Z

@MartinSpiessl can you please answer the last remaining questions.

pr-processor bot added the Not yet reviewed label Sep 11, 2025

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Sep 11, 2025

maximiliankolb commented Sep 11, 2025

View reviewed changes

pr-processor bot removed the Not yet reviewed label Sep 11, 2025

maximiliankolb force-pushed the proxy_batch_triggering branch from a784efe to 7407c29 Compare September 11, 2025 12:51

MartinSpiessl reviewed Nov 14, 2025

View reviewed changes

maximiliankolb added 3 commits January 14, 2026 11:14

Add hint about related setting for REX concurrency

3e7d86a

Fixes #38247 (Missing docs on how to REX batching works)

Rework just of fun

0b21124

Rework again just for fun

5383d34

maximiliankolb force-pushed the proxy_batch_triggering branch from 7407c29 to 5383d34 Compare January 14, 2026 10:20

maximiliankolb marked this pull request as ready for review January 14, 2026 10:24

Lennonka requested changes Jan 27, 2026

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Jan 27, 2026

Conversation

maximiliankolb commented Sep 11, 2025

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Review checklists

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MartinSpiessl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MartinSpiessl commented Nov 16, 2025

Uh oh!

MartinSpiessl commented Nov 16, 2025

Uh oh!

adamruzicka commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbernhard commented Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Sep 11, 2025 •

edited

Loading