Orchestrator and orchestration services parameters

Use these parameters to configure and tune the orchestrator and orchestration services.

puppet_enterprise::profile::agent::pxp_enabled

Boolean used to enable or disable the Puppet Execution Protocol (PXP) service.

Set to true to enable the PXP service, which is required to use the orchestrator and run Puppet from the console.

Set to false to disable the PXP service. If false, you can’t use the orchestrator or the Run Puppet button in the console.

Must be true to Configure PXP agent parameters.

Default: true

puppet_enterprise::profile::bolt_server::concurrency

An integer that determines the maximum number of simultaneous task or plan requests the orchestrator can make to bolt-server.

This setting only limits task or plan executions on nodes with SSH or WinRM transport methods, because these are the only tasks and plans requiring requests to bolt-server.

Default: 100 requests

Do not set a concurrency limit that is higher than the bolt-server limit. This can cause timeouts that lead to failed task runs.

puppet_enterprise::profile::orchestrator::global_concurrent_compiles

An integer specifying how many concurrent compile requests can be outstanding to the primary server across all orchestrator jobs.

Default: 8 requests

puppet_enterprise::profile::orchestrator::job_prune_threshold

An integer of 2 or greater, which specifies the number of days to retain job reports.

This parameter sets the corresponding parameter job-prune-days-threshold.

While job_prune_threshold itself has no default value, job-prune-days-threshold has a default of 30 (30 days).

puppet_enterprise::profile::orchestrator::pcp_timeout

An integer representing how long, in seconds, an agent can spend attempting to connect to a PCP broker during a Puppet run triggered by the orchestrator. If the agent can’t connect to the broker in the specified time frame, the Puppet run times out.

Default: 30

puppet_enterprise::profile::orchestrator::run_service

A Boolean used to enable (true) or disable (false) orchestration services.

Default: true

puppet_enterprise::profile::orchestrator::task_concurrency

An integer representing the number of simultaneous task or plan actions that can run at the same time. All task and plan actions are limited by this concurrency limit regardless of transport type (WinRM, SSH, PCP).

If a task or plan action runs on multiple nodes, each node consumes one action. For example, if a task needs to run on 300 nodes, and your task_concurrency is set to 200, then the task can run on 200 nodes while the remaining 100 nodes wait in queue.

Default: 1000 actions

puppet_enterprise::pxp_agent::ping_interval

An integer specifying the frequency, in seconds, that PXP agents ping PCP brokers. If the broker doesn't respond, the agent tries to reconnect.

Default: 120

More information: Configure PXP agent parameters

puppet_enterprise::pxp_agent::pxp_logfile

The path, as a string, to the PXP agent log file. This file can be used to debug orchestrator issues.

The default value varies by OS.

  • *nix: "/var/log/puppetlabs/pxp-agent/pxp-agent.log"
  • Windows: "C:\Program Data\PuppetLabs\pxp-agent\var\log\pxp-agent.log"

More information: Configure PXP agent parameters

You might need to configure these parameters depending on your infrastructure. You can always tune them later if you find you need to make adjustments.

puppet_enterprise::profile::orchestrator::allowed_pcp_status_requests

An integer that defines how many times an orchestrator job allows status requests to time out before a job is considered failed. Status requests wait 12 seconds between timeouts, so multiply the value of the allowed_pcp_status_requests by 12 to determine how many seconds the orchestrator waits on targets that aren’t responding to status requests.

Default: 35 timeouts

puppet_enterprise::profile::orchestrator::default_plan_timeout

An integer specifying how long a plan can run before being force stopped. This represents a timeout limit for the entire plan, not individual plan jobs.

Force stopping plans can result in incomplete Puppet runs, partial configuration changes, and other issues. When setting the default timeout limit, consider average plan scope, run time, and your infrastructure's capacity (such as concurrency limits).

Default: 3600 (60 minutes)

Plans triggered by puppet infra commands always have a one year timeout limit, regardless of the value of default_plan_timeout.

puppet_enterprise::profile::orchestrator::default_task_node_timeout

An integer specifying how many seconds a task can run on a single node before being force stopped.

Force stopping tasks can result in incomplete Puppet runs, partial configuration changes, and other issues. When setting the default timeout limit, consider average task scope, run time, and your infrastructure's capacity (such as concurrency limits).

Default: 2400 (40 minutes)

Tasks triggered by puppet infra commands always have a one year timeout limit, regardless of the value of default_task_node_timeout.

puppet_enterprise::profile::orchestrator::java_args

Specifies the Java heap size, which is the amount of JVM memory that each Java process is allowed to request from the OS for orchestration services to use.

The value is formatted as a JSON hash, where the maximum and minimum are usually the same. For example: {"Xmx": "256m", "Xms": "256m"}

Default: 704 MB

puppet_enterprise::profile::orchestrator::jruby_max_active_instances

An integer that determines the maximum number of JRuby instances that the orchestrator creates to execute plans. Because each plan uses one JRuby to run, this value is effectively the maximum number of concurrent plans. Setting the orchestrator heap size (java_args) automatically sets the jruby_max_active_instances using the formula $java_args ÷ 1024. If the result is less than one, the default is one JRuby instance.

Default: 1 instance

The jruby_max_active_instances pool for the orchestrator is separate from the Puppet Server pool. Refer to JRuby max active instances for more information.

puppet_enterprise::profile::plan_executor::versioned_deploys

A Boolean used for Running plans alongside code deployments.

Set to true to enable versioned deployments of environment code.

Default: false

Setting this to true disables the file sync client's locking mechanism that usually enforces a consistent environment state for your plans. This can cause Puppet functions and plans that call other plans to behave unexpectedly if a code deployment occurs while a plan is running.

Related information