(FM-7973) Adding hands on labs for bolt and puppet device

README.md

@@ -95,7 +95,9 @@ Test your setup and get the certificate signed:
 
 This will sign the certificate and set up the device for Puppet.
 
-See the [`puppet device` documentation](https://puppet.com/docs/puppet/5.5/puppet_device.html)
+For more information, see the [`puppet device` documentation](https://puppet.com/docs/puppet/5.5/puppet_device.html)
+
+To get more practice using PANOS, try out the [hands-on labs](./docs/README.md). 
 
 ### SSL Certificate Verification
 

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

@@ -0,0 +1,16 @@
+# Install Prerequisites
+
+Before you begin, you need Bolt and a Palo Alto firewall that you can test against. Open a terminal window and follow the steps below.
+
+1. Install the latest version of Bolt. See [Installing Bolt
+](https://puppet.com/docs/bolt/latest/bolt_installing.html) for instuctions. To check that Bolt has been installed, run `bolt --version`, which shows you the Bolt version number.
+
+2. Download a Palo Alto VM. If you are a Palo Alto customer, you may have 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 get an image from vmpooler. 
+
+3. You need to be able to connect to the firewall from the host that you are running. You can check this by entering the Palo machine details in a browser to access the web user interface of PANOS. Type `https://1.1.1.1` where 1.1.1.1 is the IP address of the Palo VM. If the web management interface of the firewall opens, you are ready to start the lab.
+
+# Next steps
+
+You are now set to start the lab. Next up we will 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,40 @@
+# Download the Puppet Panos module
+
+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. In this lab, you will create a [local project directory](https://puppet.com/docs/bolt/latest/bolt_project_directories.html#local-project-directory).
+
+1. Create a folder in your preferred location and navigate to it.
+
+2. Inside the new folder, create a `bolt.yaml` file and a `Puppetfile` file.
+
+3. Edit the `Puppetfile` file to tell Bolt where to look for the module, which module to retrieve, and the version of the module:
+
+```
+mod 'puppetlabs-panos', '1.0.0'
+```
+
+> Note: If you are familiar with Puppet, notice that it uses the same format as Puppet files.
+
+4. From the command line, install the module with Bolt:
+
+`bolt puppetfile install`
+
+Once the module has been installed, you should get the following message: 
+
+`Successfully synced modules from $(pwd)/Puppetfile to $(pwd)/modules`
+
+6. To verify that the module has been installed correctly, look for a `modules` folder in your Bolt working directory. Run `ls $(pwd)/modules` and you should see a folder called `panos` containing the downloaded Puppet Palo Alto module from the Forge.
+
+7. To see a list of the tasks that Bolt can access on your local machine, run `bolt task show`. You should see 4 tasks in the Palo Alto module:
+
+```
+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
+
+Now that you have installed the Palo Alto module, you will configure the Palo Alto firewall in an `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,42 @@
+# Update the Bolt inventory file
+
+Add the Palo Alto firewall details to the Bolt inventory file.
+
+1. Navigate to the directory you created in [Download Puppet Palo Alto Module](./../02-download-panos-module/README.md).
+
+2. Create a file called `inventory.yaml`.
+
+3. Edit the `inventory.yaml` file to provide details of the Palo Alto firewall you want to manage, including the hostname or IP of the Palo Alto firewall, username, password or api key: 
+
+```
+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_fingerprint: <certificate SHA256 fingerprint>
+```
+
+The `name` needs to match the `Common Name (CN)` of the certificate of the firewall. In this example, we have combined username and password. 
+
+By default, the module performs SSL verification. To disable this, put `ssl: false` in the remote section of the `inventory.yaml` file. 
+
+In this lab, we use the SHA256 fingerprint of the certificate for verification. To get the certificate's fingerprint, see the certificate in a browser, or for Linux users, use the `openssl` command.
+
+```
+echo | openssl s_client -connect <hostname of IP of Palo Alto firewall>:443 |& openssl x509 -fingerprint -noout -sha256
+```
+
+> Note: For Puppet employees using VMPooler images, the CN name may be a generated string that does not match the FQDN. We advise you to edit the hosts file in this instance, or to replace `ssl_fingerprint: <certificate SHA256 fingerprint>` with `ssl: false` so that it does not perform SSL validation.
+
+Now you can refer to your Palo Alto firewall with the alias in the above `inventory.yaml` file.
+
+# Next steps
+
+Next, you will run a 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 pan, which we know is a `remote target` as specified in our `inventory.yaml` and by default these tasks will run on the `localhost` transport.
+
+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 apply a manifest.
+
+[Applying a manifest](./../05-applying-a-manifest/README.md)

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

@@ -0,0 +1,38 @@
+# Applying a Manifest
+
+Finally, we'll apply 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)

docs/02-using-with-puppet-device/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, Puppet 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 Puppet Agent. Follow the instructions [here](https://puppet.com/docs/puppet/6.4/install_agents.html) for your chosen operating system. You can check that it is installed correctly by typing `puppet --version` and it will print out the Puppet 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 install the Puppet Palo Alto module from the [Forge](https://forge.puppet.com/).
+
+[Install the Puppet Palo Alto Module](./../02-install-panos-module/README.md)

docs/02-using-with-puppet-device/02-install-panos-module/README.md

@@ -0,0 +1,32 @@
+# Install Palo Alto Module
+
+OK, now we're ready to install the module.
+
+1. Check if any modules are currently installed on your machine. Type `puppet module list` and this will output a list of modules that are installed. If you have just starting using Puppet on your workstation you will not see any output from this command.
+
+2. Install the module from the Forge. You will need internet connectivity to run this command. Type `puppet module install puppetlabs-panos`. This will bring down and install any associated dependencies that the module needs to run. Once complete, if you type `puppet module list` again, you will see output similar to that below:
+```
+[root@localhost]# puppet module install puppetlabs-panos
+Notice: Preparing to install into /etc/puppetlabs/code/modules ...
+Notice: Created target directory /etc/puppetlabs/code/modules
+Notice: Downloading from https://forgeapi.puppet.com ...
+Notice: Installing -- do not interrupt ...
+/etc/puppetlabs/code/modules
+└─┬ puppetlabs-panos (v1.0.0)
+  └─┬ puppetlabs-resource_api (v1.0.0)
+    └── puppetlabs-puppetserver_gem (v1.1.0)
+```
+
+3. You can check that the module and its dependencies are installed by typing `puppet module list` and you will receive output similar to that which is below:
+```
+[root@localhost bolt]# puppet module list
+/etc/puppetlabs/code/modules
+├── puppetlabs-panos (v1.0.0)
+├── puppetlabs-puppetserver_gem (v1.1.0)
+└── puppetlabs-resource_api (v1.0.0)
+```
+# Next steps
+
+OK, next up we're going to configure `puppet device`
+
+[Configure Puppet Device](./../03-configure-puppet-device/README.md)

docs/02-using-with-puppet-device/03-configure-puppet-device/README.md

@@ -0,0 +1,39 @@
+# Configure Puppet Device
+
+Puppet device is Puppet's current agentless catalog execution service. It executes a catalog on an agent node, and applies the catalog via a module to a remote and agentless device. This approach has typically been used by Puppet module developers for agentless device management over the years, for a history lesson see the date stamp on the [manual page](https://puppet.com/docs/puppet/6.4/man/device.html)! Note that Puppet is in the process of upgrading our agentless capabilities, using both [bolt](https://puppet.com/products/bolt) and another agentless construct (ACE) that we're releasing later in 2019.
+
+1. Firstly, we need to find the location of a file entitled `device.conf` as it contains a pointer to the device specific configuration files. On your work station type `puppet config print deviceconfig`. This will return the location of the file, on my CentOS VM it's located here: `/etc/puppetlabs/puppet/device.conf`
+
+2. Check if the file and if there's anything already in it. View the file referred to above, this can be done by typing: `cat /etc/puppetlabs/puppet/device.conf`. If the file exists the contents will be displayed on screen, if it doesn't exist then you'll get a message stating that `No such file or directory exists`.
+
+3. We need to enter valid details into this file. The file needs to contain an alias, type and url to a credentials file. To make this easy, enter the following details into the device.conf file.
+```
+[firewall.example.com]
+type panos
+url file:////etc/puppetlabs/puppet/devices/firewall.example.com.conf
+```
+
+4. OK, so now you've told Puppet that there's a device to be managed by `puppet device`. Now we need to enter credentials in the configuration file referenced by the above. Do this by entering the following details in the file `/etc/puppetlabs/puppet/devices/firewall.example.com.conf`. The host should be the IP address of the Palo Alto firewall you want to manage.
+
+By default the module performs SSL verification, this can be disabled by putting `ssl: false` in the `/etc/puppetlabs/puppet/devices/firewall.example.com.conf` file. 
+
+For the purpose of this lab we will use the SHA256 fingerprint of the certificate for verification. In order to get the certificate's fingerprint, this can retrieved from inspecting the certificate in a browser, or *nix users can use the openssl command:
+
+```
+echo | openssl s_client -connect <hostname of IP of Palo Alto firewall>:443 |& openssl x509 -fingerprint -noout -sha256
+```
+
+```
+host: 192.168.99.101
+user: admin
+password: admin
+ssl_fingerprint: <certificate SHA256 fingerprint>
+```
+
+*Note*: The `host` will need to match the `Common Name (CN)` of the certificate of the firewall, for Puppet employees using VMPooler images the CN name may be a generated string that does not match the FQDN, it is advisable to edit the `/etc/hosts` file in this instance, or if this does not suit simply replace `ssl_fingerprint: <certificate SHA256 fingerprint>` with `ssl: false` which will mean that no SSL validation is performed.
+
+# Next steps
+
+OK, next up we're going to do the final step before interacting with the device, by signing the certificate.
+
+[Sign the Certificate](./../04-sign-the-cert/README.md)

docs/02-using-with-puppet-device/04-sign-the-cert/README.md

@@ -0,0 +1,11 @@
+# Sign the Certificate
+
+In order to manage a device with Puppet it is necessary to sign a certificate. This is normal for all server based infrastructure, and is required for devices also.
+
+1. At the command line on your host that you installed the module, type: `puppet device --verbose --target firewall.example.com` where `firewall.example.com` is the alias from the configuration files in the previous step. If you receive some errors at this stage it will be necessary to declare the panos module in a class and apply to the proxy agent, and then rerun the previous command. You will notice that the facts that are gathered are those of your work station and not the device under management. We are currently working to rectify this and give a simple way to gather facts from device nodes for inclusion in your Puppet Enterprise deployment. Please keep watching puppet.com/blog for announcements regarding this.
+
+# Next steps
+
+So, that's all the set up done! Now we'll run some --resource and --apply commands to see `puppet device` in action.
+
+[Run Puppet Device Commands](./../05-run-puppet-device-commands/README.md)

docs/02-using-with-puppet-device/05-run-puppet-device-commands/README.md

@@ -0,0 +1,24 @@
+# Run Puppet Device Commands
+
+Now that you've set up your node as a proxy to the device you will be able to run `puppet device` commands. These commands are those which are executed by Puppet Enterprise if you're using it to being your device nodes under management
+
+1. At the command line of the node on which your device is configured type `puppet device --resource address --target firewall.example.com` and it will return all the addresses that are configured in the PANOS firewall. The output will appear as Puppet code, similar to what is below:
+```
+panos_address { 'newaddressrange':
+    ensure => 'present',
+    ip_range => '10.0.0.1-10.0.0.5',
+    tags => [],
+}
+```
+
+2. It is also possible to apply changes using `puppet device --apply`. To do this create a manifest entitled manifest.pp, similar to that which is below, and then run the command `puppet device --apply manifest.pp --target panos` and it will apply the manifest to create the address range.
+
+3. Remember that it's possible use `noop` mode to simulate proposed changes if desired.
+
+# Next steps
+
+That's the end of this tutorial. You have now configured a node to run `puppet device` in order to manage an agentless firewall. The obvious next step is to set up this node to work with Puppet Enterprise. The links below are suggested next steps.
+
+* Use the [Device Manager module](https://forge.puppet.com/puppetlabs/device_manager) to set up `puppet device` nodes to work with Puppet Enterprise
+* Try using `puppet device` with the [Cisco IOS module](https://forge.puppet.com/puppetlabs/cisco_ios).
+* Watch Rick Sherman speaking at [Puppetize Live 2018](https://www.youtube.com/watch?v=yQH11ngrxuQ) using `puppet device` for agentless management of Cisco Nexus and Cisco IOS devices.