Tasks in Puppet Enterprise

Running tasks in Puppet Enterprise

The user can use the orchestrator to set up the jobs in the console or on the command line and then run the Bolt tasks across systems in their infrastructure.

Puppet configuration does not get updated by running a task. Suppose the state of a resource that is being managed by Puppet is changed due to a task that is running. In that case, a subsequent Puppet run will change the state of that resource back to its original configuration as defined in the Pupper configuration.

• Running tasks from the console: the user can run ad-hoc tasks on the target machines in order to upgrade packages, restart services, or to perform any kind of single-action execution on the node.
• Running tasks from the command line: in order to run tasks on the agent nodes, use the puppet task run command.
• Stop a task in progress: the user can stop a running task.
• Inspecting tasks: the user can view the tasks that have been installed and have permission to run.

Running tasks from the console

The user can run ad-hoc tasks on the target machines in order to upgrade packages, restart services, or to perform any kind of single-action execution on the node.

When the user sets up a job to run a task from the console, then the orchestrator creates a job ID in order to track the job, it shows all the nodes that are included in the job and also runs the tasks on these nodes in an appropriate order. The Puppet compiles a new catalog for each and every node included in the job.

The user can specify the job in three different ways:

• Static Node list
• PQL (Puppet Query Language)
• Node group

The user can't combine these methods, and if in case the user switches from one to another, then the target list clears and starts over. 

Run a task on the node list

The user needs to create a list of target nodes when the user needs to run a task on a particular set of nodes that aren't easily defined by a PQL query.

• Click on Tasks, which is present in the Orchestration section inside the console.
• Click on Run a task which is present in the top right corner of the Tasks page.
• Choose the environment where the module containing the task that is to be run is installed in the Code environment field.
• In the Task field, choose a task that is to be run.
• In the Task parameters, add the optional parameters and enter the values for the optional as well as required parameters on the list. In order to view information about the required and optional parameters for a task, click on the View task metadata option, which is below the Task field.
• Choose the Node list from the list of target types.
• Create the node list
  • Click and expand the inventory nodes target.
  • Input the name of the node that you want to find, and then click on Search.
  • Select the nodes that are to be added to the list from the results list.
  • Repeat the search to add other nodes since users can select nodes from multiple searches.
• Click on Run tasks or Schedule job.
• The task run appears on the Tasks page.

Run a task over SSH

The user can use the SSH protocol to run tasks on the target nodes that do not have Puppet agent installed. 

• Click on Tasks, which is present in the Orchestration section inside the console.
• Click on Run a task which is present in the top right corner of the Tasks page.
• Choose the environment where the module containing the task that is to be run is installed in the Code environment field.
• In the Task field, choose a task that is to be run.
• In the Task parameters, add the optional parameters and also enter the values for the optional as well as required parameters on the list. In order to view information about the required and optional parameters for a task, click on the View task metadata option, which is below the Task field.
• Choose the Node list from the list of target types.
• Create the node list
  • Click and expand the SSH nodes target.
  • Enter the target's host names as well as the credentials that are required to access them.
  • Click on Add nodes.
  • Repeat the above steps in order to add other nodes since the user can add SSH nodes with different credentials in order to create the node list.
• Click on Run tasks or Schedule job.
• The task run appears on the Tasks page.

Run a task on the PQL query

The user can create a PQL query in order to run tasks on nodes which meet specific conditions.

• Click on Tasks, which is present in the Orchestration section inside the console.
• Click on Run a task which is present in the top right corner of the Tasks page.
• Choose the environment where the module containing the task that is to be run is installed in the Code environment field.
• In the Task field, choose a task that is to be run.
• In the Task parameters, add the optional parameters and also enter the values for the optional as well as required parameters on the list. In order to view information about the required and optional parameters for a task, click on the View task metadata option, which is below the Task field.
• Choose the PQL query from the list of target types.
• Do the following in order to specify a target:
  • Enter a query as per the desired target.
  • Click on Common queries, choose any one of the queries, and replace the defaults in the braces with values that specify the desired target.
• Click on Submit query and then click Refresh in order to update the node results.
• If the user makes any changes to the query after it runs, then the user needs to click on Submit query again.
• Click on Run tasks or Schedule job.
• The task run appears on the Tasks page.

Add custom PQL queries to the console

The user can add their own PQL queries to the console in order to quickly access them when running jobs.

• Copy the custom_pql_queries.json.example file, and remove the .example suffix on the primary server.
• Edit the file contents as per need to either include your own PQL queries or to remove any existing queries.
• Refresh the console UI.

Running tasks from the command line

The user can run tasks on agent nodes using the puppet task run command.

The user can use the puppet task tool and relevant modules in order to make changes arbitrarily. 

The user can run tasks on a single node, on nodes that are identified in a static list, on nodes that are retrieved by PQL query, or on nodes in a node group.

The user can use the orchestrator command puppet task in order to trigger the task runs.

Run a task on a list of nodes or a single node

The user can use a node list target when they need to run a job on a set of nodes that does not resolve to a PQL query.

The user needs to log into their primary server or client tools workstation and then run any one of the following commands:

• In order to run a task job on a single node, use the following:

puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes <NODE NAME> <OPTIONS>

• In order to run a task job on a list of nodes, use the following:

puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes <NODE NAME>,<NODE NAME>,<NODE NAME>,<NODE NAME> <OPTIONS>

Note: Spaces are not allowed in the list of nodes

• In order to run a task job on a node list from a file, use the following:

puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes @/path/to/file.txt

Note: Put each node on a separate line in the text file.

Run a task on the PQL query

The user needs to create a PQL query in order to run tasks on nodes which meet certain conditions.

The user needs to log into their primary server or client tools workstation and then run any one of the following commands:

• In order to specify the query on the command line, use the following:

puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --query '<QUERY>' <OPTIONS>

• In order to pass the query in a text file, use the following:

puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --query @/path/to/file.txt

The below table shows examples of PQL queries that the user might use for any particular node targets:

Stop a task in progress

The user has the ability to stop a task that is running. There are three different ways in which the user can stop a task:

• In the Tasks page, locate the task that is to be stopped and then click on Stop job.
• Press CTRL + C on the command line.
• Use the POST /command/stop.

Whenever a task is stopped, any Puppet runs that are already underway finish, but no new runs start on that node unless that task is initiated again. While in-progress runs finish, the server keeps on producing events for the job. The status of the job changes to “stopped” once all the in-progress runs finish.

Inspecting tasks

The user can view tasks that have been installed and have permission to run.

The user needs to log into their primary server or client tools workstation and then run any one of the following commands:

• If the user wants to check the documentation of a specific task: puppet task show <TASK>. The command will return the following:
  • Command format of the running task
  • Parameters that are available for use with the task.
• In order to view the list of permitted tasks:

puppet task show

• In order to see the list of all the installed tasks:

puppet task show --all

Writing tasks

Since bolt tasks are kept in modules and have metadata, therefore, they can be shared and reused. The user can write tasks in any programming language in which the target nodes run, like Bash, Python, etc. The user needs to place the task in the ./tasks directory of the module and then add a metadata file in order to describe the parameters and configure task behavior.

For any task to run on a remote *nix system, there must be a shebang line at the top of the file to specify the interpreter.

Secure coding practices for tasks

Users should follow secure coding practices while writing tasks and help protect their system.

One of the many ways through which attackers gain access to a user's system is through remote code execution, whereby running an allowed script, the attackers gain access to other parts of the system and thereby can make arbitrary changes. Since Bolt executes scripts across the user's infrastructure, therefore it is very important to be aware of some vulnerabilities and to code the tasks in such a way that guards against remote code execution.

One way to reduce vulnerability is by adding task metadata that validates the input. Whenever the user requires an enum or other non-string types, the user prevents improper data from being entered. 

PowerShell

In this, the code injection exploits call that specifically evaluate code. The user should not call Invoke-Expression or Add-Type with the user's input. Since these commands evaluate strings as C# code.

Overwriting critical files or reading sensitive files can be less obvious. If the user plans on allowing other users to specify either a file name or path, then use Resolve-Path in order to verify that the path doesn't go outside the locations that the user expects the task to access. The user can use the Split-Path -Parent $path in order to check whether the resolved path has the desired path as the parent or not.

Python

Commands such as eval, exec, os.system, os.popen, and subprocess.call with shell=True can introduce malicious code in Python. The user should use subprocess.call with shell=False whenever including user input in the command.

Ruby

Commands like eval, exec, system, %x() execution, or the Open3 module introduces command injection in Ruby. The user can safely call these above functions with user input by simply passing the input as an additional argument instead of a single string.

Naming tasks

The names of the tasks are based on the filename of the task, the name of the module, and the path to the task within the module. 

The user can write tasks in any programming language that runs on the target nodes. The user needs to give the tasks files appropriate extensions as per the language they are written in and then place them in the top level of the module's ./tasks directory.

The task names have one or two name segments, which indicate:

• Name of the module where the task is located.
• Name of the task file.

The task filename init is special because the task it defines can be referenced using the module name only. 

Each and every task or plan name segment:

• Starts with a lowercase letter.
• Can have digits and underscores.
• The namespace segments must match the regular expression: \A[a-z][a-z0-9_]*\Z
• Reserved extensions such as .md or .json must not be used for file extensions.

Specifying parameters

The user can pass parameters for tasks to the bolt command as CLI arguments or as JSON hash.

If the user wants to pass the parameters individually to the task or plan, then the user can specify the parameter value on the command line using the format parameter=value. The user can pass multiple parameters as a space-separated list. If the parsed value matches the type, then it is used else the original string is used.

In order to specify the parameters as JSON, use the parameters flag, which the JSON follows: --params' {"name": "openssl"}'

Frequently Asked Questions

Mention some pre-installed tasks in the Puppet Enterprise.

Some pre-installed tasks in the Puppet Enterprise are the package, service, and facter_task.

What are the ways to specify the job target?

There are three ways to specify the job target: Static node list, PQL, and Node group.

Mention a way to stop a task that is running.

A running task can be stopped by pressing CTRL + C on the command line.

Conclusion

In this article, we have extensively discussed about Tasks in Puppet Enterprise.

After reading about the Tasks in Puppet Enterprise, are you not feeling excited to read/explore more articles on Augmented Reality? Don't worry; Coding Ninjas has you covered. To learn about what Augmented Reality is, what are the applications of Augmented Reality, and what is the use of Augmented reality in the Medical industry.  

If you wish to enhance your skills in Data Structures and Algorithms, Competitive Programming, JavaScript, etc., you should check out our Guided path column at Coding Ninjas Studio. We at Coding Ninjas Studio organize many contests in which you can participate. You can also prepare for the contests and test your coding skills by giving the mock test series available. In case you have just started the learning process, and your dream is to crack major tech giants like Amazon, Microsoft, etc., then you should check out the most frequently asked problems and the interview experiences of your seniors that will help you in landing a job in your dream company. 

Do upvote if you find the blogs helpful.

Happy Learning!