Added a tutorial on using the module with bolt

docs/01-using-with-bolt/01-install-prerequisites/README.md

@@ -0,0 +1,15 @@
+# Install Prerequisites
+
+Before doing any of this you're doing to need a few things to be set up: Ruby, bolt and a Palo Alto firewall that you can test against. Open a terminal window and follow the steps below.
+
+1. Check if Ruby is installed by typing `ruby --version`. This will print out the version of Ruby that is installed. If it's not installed follow the instructions [here](https://rubyinstaller.org/downloads/) to install it.
+
+2. Install the latest version of bolt. Follow the instructions [here](https://puppet.com/docs/bolt/latest/bolt_installing.html) for your chosen operating system. You check that it installed correctly by typing `bolt --version` and it will print out the bolt version number.
+
+3. Grab a Palo Alto VM. If you are a Palo Alto customer you may have some VMs that you can run in [Virtual Box](https://www.virtualbox.org/). Alternatively, you can get a free trial on the [AWS marketplace](https://aws.amazon.com/marketplace/seller-profile?id=0ed48363-5064-4d47-b41b-a53f7c937314). If you are a Puppet employee we have licenses for VMs that you can run in Virtual Box, or you can just grab an image from vmpooler. In order for this lab to work you will need to be able to connect to the firewall from the host that you're running on. Typically you can check this by entering the Palo machine details in a browser to access the web user interface of PANOS - try typing `https://1.1.1.1` where 1.1.1.1 is the IP address of the Palo VM. This should open the web management interface of the firewall - if that works then the lab will also work.
+
+# Next steps
+
+OK, you're now all set to start the lab. Next up we'll use bolt to download the Puppet Palo Alto module
+
+[Download Puppet Palo Alto Module](./../02-download-panos-module/README.md)

docs/01-using-with-bolt/02-download-panos-module/README.md

@@ -0,0 +1,29 @@
+# Download Puppet Panos Module
+
+OK, so now we're going to use bolt to download the [Puppet Palo Alto module](https://forge.puppet.com/puppetlabs/panos) from [the Forge](https://forge.puppet.com/) to your local workstation. This can be done by creating a [Puppetfile](https://puppet.com/docs/bolt/latest/installing_tasks_from_the_forge.html#task-8928) and adding a link to the Forge module.
+
+1. Go to your bolt working directory. This is `$HOME/.puppetlabs/bolt`.
+
+2. Create a file called `Puppetfile`.
+
+3. Edit the file to tell bolt where to get the module, the module to retrieve and the version of the module. Those of your already familiar with Puppet will see that it uses the same format as existing Puppetfiles. For this purpose of this tutorial, enter the following details in the Puppetfile:
+```
+forge 'http://forge.puppetlabs.com'
+mod 'puppetlabs-panos', '1.0.0'
+```
+
+4. Now install the module using bolt by typing `bolt puppetfile install` from the command line. When complete you should get a message which states that the modules were successfully synced, something like: `Successfully synced modules from $HOME/.puppetlabs/bolt/Puppetfile to $HOME/.puppetlabs/bolt/modules`
+
+5. To verify that this worked you should now see a `modules` folder in your bolt working directory. Within that folder you should see a folder entitled `panos` which contains the downloaded Puppet Palo Alto module from the Forge. Type `ls $HOME/.puppetlabs/bolt/modules` and should see a folder entitled `panos` which contains the downloaded module. Now, type `bolt task show` and it will list all the tasks that bolt can access on your local machine. This should include 4 tasks in the Palo Alto module, as follows:
+```
+panos::apikey            Retrieve a PAN-OS apikey
+panos::commit            Commit a candidate configuration to a firewall.
+panos::set_config        upload and/or apply a configuration to a firewall.
+panos::store_config      Retrieve the configuration running on the firewall.
+```
+
+# Next steps
+
+OK, now we've got the module installed we'll configure the Palo Alto firewall in the inventory.yaml file.
+
+[Update bolt Inventory](./../03-update-bolt-inventory/README.md)

docs/01-using-with-bolt/03-update-bolt-inventory/README.md

@@ -0,0 +1,29 @@
+# Update bolt Inventory
+
+Now we're going to add the Palo Alto firewall to the bolt inventory. Doing this allows us to enter the firewall details in the bolt inventory and avoids having to pass them at the command line.
+
+1. Go to your bolt working directory. This is `$HOME/.puppetlabs/bolt`.
+
+2. Create a file called `inventory.yaml`.
+
+3. Edit the file to provide details about the Palo Alto firewall you want to manage. The following details will needed: hostname or IP of the Palo Alto firewall, user name, password or api key. For this tutorial I'm using a username and password combination. I've also chosen to set SSL to false. By default this is set to true meaning that the SSL certificate needs to be verified before you can connect to the firewall - I've set this to false for this demo.
+```
+nodes:
+  - name: <hostname or IP of your Palo Alto firewall>
+    alias: pan
+    config:
+      transport: remote
+      remote:
+        remote-transport: panos
+        user: <username to access your Palo Alto VM>
+        password: <password for the above username>
+        ssl: false
+```
+
+Now you will be able to refer to your Palo Alto firewall via the alias in the above `inventory.yaml` file.
+
+# Next steps
+
+Next up is running a simple task.
+
+[Running a Task](./../04-running-a-task/README.md)

docs/01-using-with-bolt/04-running-a-task/README.md

@@ -0,0 +1,17 @@
+# Running a Task
+
+We're all set to use bolt to connect to the firewall and run a task. The module comes with some tasks already available out of the box. For this tutorial we will use the `panos::apikey` task to generate an API key.
+
+Type `bolt task run panos::apikey -n pan --debug` where -n represents the nodes, with `pan` the alias we set in the `inventory.yaml` file and `--debug` represents that we want to get debug level output. If everything is working as planned you should be able to see that the task runs successfully and returns an apikey as expected. Examining the debug output you will notice a few interesting things:
+
+1. The task target is localhost, meaning it ran on your localhost machine. It is possible for bolt to execute on [remote targets](https://puppet.com/docs/bolt/latest/bolt_configuration_options.html#remote-transport-configuration-options) for infrastructure that is located on a different network segment to your localhost.
+
+2. The details from inventory.yaml are used by the task.
+
+3. Additional parameters can be used, as outlined in the [bolt reference material](https://puppet.com/docs/bolt/latest/bolt_command_reference.html).
+
+# Next steps
+
+Now we'll execute a manifest.
+
+[Executing a manifest](./../05-execute-a-manifest/README.md)

docs/01-using-with-bolt/05-execute-a-manifest/README.md

@@ -0,0 +1,38 @@
+# Execute a Manifest
+
+Finally, we'll execute a manifest against the Palo Alto firewall to create some resources. This is a particularly powerful feature of bolt because it allows you to use all the types and providers that are available in a module. In this example we'll create some simple address ranges.
+
+1. Create a manifest file, let's just name is as `manifest.pp` with the following details
+```
+panos_address { 'newaddressrange':
+    ensure => 'present',
+    ip_range => '10.0.0.1-10.0.0.5',
+    tags => [],
+}
+```
+
+2. Apply the manifest using `bolt apply` by running the following command: `bolt apply manifest.pp -n pan`. This will use the manifest we just created to add the new address ranges above. You should see output similar to that which is below:
+```
+Starting: install puppet and gather facts on <hostname or IP of Palo Alto device>
+Finished: install puppet and gather facts with 0 failures in 2.51 sec
+Starting: apply catalog on <hostname or IP of Palo Alto device>
+Finished: apply catalog with 0 failures in 6.51 sec
+Finished on <hostname or IP of Palo Alto device>:
+  changed: 1, failed: 0, unchanged: 0 skipped: 0, noop: 0
+Successful on 1 node: <hostname or IP of Palo Alto device>
+Ran on 1 node
+```
+
+3. Navigate to the user interface of the Palo Alto firewall web user interface and check that the address range has been created. Well done, you've used bolt and a module to perform some basic automation!
+
+4. One last feature we'll show you is `noop` - this is simulation mode, where you can check what a manifest would do if it was run in full apply mode - this highlights the idempotent capabilities of Puppet. Update the previous manifest to set the ensure property of the address range to be `absent`. Once that's done execute the following command: `bolt apply manifest.pp -n pan --noop --debug`. Examine the output and you will notice that a corrective change was run in `noop` mode, which means that the address range would be removed if the command was run without `noop`. To actually remove the newly created address range run the command without noop, so: `bolt apply manifest.pp -n pan` and it will actually remove the address range.
+
+# Next steps
+
+Well done, you've used bolt with a network device module to perform some network automation! There's a huge amount of other things that can be done, some of which are listed below. I encourage you to have a go at these additional items.
+
+* Run bolt on a jumphost to access devices on different network segments to your localhost using the [run-on](https://puppet.com/docs/bolt/latest/bolt_configuration_options.html#remote-transport-configuration-options) option.
+* Check out all the [other resources](https://forge.puppet.com/puppetlabs/panos/reference) that you can automate with Puppet and bolt.
+* Use a bolt plan with the Puppet Palo Alto module by looking at Cas's [GitHub gist](https://gist.github.com/donoghuc/8a51243b809ebe5651ff15ae24cc4969).
+* Learn more about tasks and bolt using this [hands-on-lab](https://github.com/puppetlabs/tasks-hands-on-lab).
+* Try some [Cisco IOS](https://github.com/DavidS/cisco_ios/tree/device-task-poc) automation with bolt.

docs/01-using-with-bolt/README.md

@@ -0,0 +1,9 @@
+# Lab Overview
+
+This lab will walk you through how to use the [Puppet Palo Alto firewall](https://forge.puppet.com/puppetlabs/panos) module with [bolt](https://puppet.com/products/bolt). At the end of this lab you will have used bolt to run tasks and apply a manifest at the command line. This is a basic lab, no prior knowledge of either Panos or bolt is required.
+
+# Get Started
+
+OK, let's get into it.
+
+[Install prerequisites](./01-install-prerequisites/README.md)