Specifying plan parameters

Specify plan parameters to do things like determine which targets to run different parts of your plan on. You can pass a parameter as a single target name, comma-separated list of target names, Target data type, or array. The target names can be either certnames or inventory node names.

The example plan below shows the target parameters $load_balancers and $webservers specified as data type TargetSpec. The plan then calls the run_task function to specify which targets to run the tasks on. The Target names are collected and stored in $webserver_names by iterating over the list of Target objects returned by get_targets. Task parameters are serialized to JSON format so that extracting the names into an array of strings ensures that the webservers parameter is in a format that can be converted to JSON.

plan mymodule::my_plan(
  TargetSpec $load_balancer,
  TargetSpec  $webservers,
) {

  # Extract the Target name from $webservers
  $webserver_names = get_targets($webservers).map |$n| { $n.name }
  
  # process webservers
  run_task('mymodule::lb_remove', $load_balancer, webservers => $webserver_names)
  run_task('mymodule::update_frontend_app', $webservers, version => '1.2.3')
  run_task('mymodule::lb_add', $load_balancer, webservers => $webserver_names)
 }

To execute this plan from the command line, pass the parameters as parameter=value. The Targetspec accepts either an array as JSON or a comma separated string of target names.

puppet plan run mymodule::myplan 
load_balancer=lb.myorg.com 
webservers='["kermit.myorg.com","gonzo.myorg.com"]'

Alternatively, here is an example of the same plan, run on the same targets, using the Orchestrator API POST /command/plan_run endpoint:

curl -k -X POST -H "Content-Type: application/json" \
-H "X-Authentication:$TOKEN" \
-d '{ "environment": "$ENV", "plan_name": "mymodule::myplan", \
"params": {"targets": "$TARGET_NAME", "load_balancer": "lb.myorg.com", \
"webservers": ["kermit.myorg.com", "gonzo.myorg.com"]} }' \
"https://$PRIMARY_HOST:8143/orchestrator/v1/command/plan_run"

Parameters that are passed to the run_* plan functions are serialized to JSON. For example, in the plan below, the default value of $example_nul is undef. The plan calls the test::demo_undef_bash with the example_nul parameter.

plan test::parameter_passing (
  TargetSpec $targets,
  Optional[String[1]] $example_nul = undef,
) {
  return run_task('test::demo_undef_bash', $targets, example_nul => $example_nul)
     }

The implementation of the demo_undef_bash.sh task is:

#!/bin/bash
example_env=$PT_example_nul
echo "Environment: $PT_example_nul"
echo "Stdin:" 
     cat -

By default, the task expects parameters passed as a JSON string on stdin to be accessible in prefixed environment variables.

Additionally, you can use the Orchestrator API POST /command/plan_run endpoint with token authentication, such as:

curl -k -X POST -H "Content-Type: application/json" -H 
"X-Authentication:$TOKEN" -d '{ "environment": "$ENV", 
"plan_name": "test::parameter_passing", "params": {"targets": 
"$TARGET_NAME"} }'
"https://$PRIMARY_HOST:8143/orchestrator/v1/command/plan_run"