Automating Windows targets

First, we’ll use Bolt to run the script as-is on a single target.

1. Create a Bolt project directory to work in, called bolt-guide.

2. Copy the restart_service.ps1 script into bolt-guide.

3. In the bolt-guide directory, run the restart_service.ps1 script:

   bolt script run .\restart_service.ps1 W32Time --targets winrm://<HOSTNAME> -u Administrator -p 

   
   
   

   Note: The -p option prompts you to enter a password.

   By running this command, you’ve brought your script under Bolt control and have run it on a remote target. When you ran your script with Bolt, the script was transferred into a temporary directory on the remote target, it ran on that target, and then it was deleted from the target.

To run Bolt commands against multiple targets at once, you need to provide information about the environment by creating an inventory file. The inventory file is a YAML file that contains a list of targets and target specific data.

1. Inside the bolt-guide directory, use a text editor to create an inventory.yaml file and a bolt-project.yaml file. The inventory.yaml file is where connection information is stored, while bolt-project.yaml tells Bolt that the directory is a project and that it should load the inventory file from the directory.

2. Inside the new inventory.yaml file, add the following content, listing the fully qualified domain names of the targets you want to run the script on, and replacing the credentials in the winrm section with those appropriate for your target:

   groups:
     - name: windows
       targets:
         - <ADD WINDOWS SERVERS' FQDN>
         - <example.mycompany.com>
       config:
         transport: winrm
         winrm:
           user: Administrator
           password: <ADD PASSWORD>

   Note: To have Bolt securely prompt for a password, use the --password-prompt command-line option without supplying any value. This prevents the password from appearing in a process listing or on the console. Alternatively you can use the prompt plugin to set configuration values via a prompt.

   You now have an inventory file where you can store information about your targets.

   You can also configure a variety of options for Bolt in bolt-project.yaml. For more information about configuration see Configuring Bolt. For more information about Bolt projects see Bolt projects.

To convert the restart_service.ps1 script to a task, giving you the ability to reuse and share it, create a task metadata file. Task metadata files describe task parameters, validate input, and control how the task runner executes the task.

Note: This guide shows you how to convert the script to a task by manually creating the .ps1 file in a directory called tasks. Alternatively, you can use Puppet Development Kit (PDK), to create a task by using the pdk new task command. If you’re going to be creating a lot of tasks, using PDK is worth getting to know. For more information, see the PDK documentation.

1. In the bolt-guide directory, create the following subdirectories:

   bolt-guide/
   └── modules
       └── gsg
           └── tasks

2. Move the restart_service.ps1 script into the tasks directory.

3. In the tasks directory, use your text editor to create a task metadata file — named after the script, but with a .json extension, in this example, restart_service.json.

4. Add the following content to the new task metadata file:

   {
     "puppet_task_version": 1,
     "supports_noop": false,
     "description": "Stop or restart a service or list of services on a target.",
     "parameters": {
       "service": {
         "description": "The name of the service, or a list of service names to stop.",
         "type": "Variant[Array[String],String]"
       },
       "norestart": {
         "description": "Immediately restart the services after start.",
         "type": "Optional[Boolean]"
       }
     }
   }

5. Save the task metadata file and navigate back to the bolt-guide directory.

   You now have two files in the gsg module’s tasks directory: restart_service.ps1 and restart_service.json -- the script is officially converted to a Bolt task. Now that it’s converted, you no longer need to specify the file extension when you call it from a Bolt command.

6. Validate that Bolt recognizes the script as a task:

   bolt task show gsg::restart_service

   
   
   

   Congratulations! You’ve successfully converted the restart_service.ps1 script to a Bolt task.

7. Execute your new task:

   bolt task run gsg::restart_service service=W32Time --targets windows

   
   
   

   Note: --targets windows refers to the name of the group of targets that you specified in your inventory file. For more information, see Specify targets.