(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 are using the username and password for authenticating with the device. 
+
+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,20 @@
+# Run a Bolt Task
+
+Use Bolt to connect to the firewall and run a task. The module comes with some tasks already available.
+
+1. Use the `panos::apikey` task to generate an API key. Run:
+
+`bolt task run panos::apikey -n pan --debug`. 
+
+Note that `-n` represents the nodes, `pan` is the alias you set in the `inventory.yaml` file and `--debug` provides a debug level output. If everything works, you will the task run successfully and return an api key. 
+
+Notice the following in the debug output:
+
+* Bolt used the details you added to the `inventory.yaml` file. For example, the task target is `pan`, which is the `remote target` you specified in the `inventory.yaml`. By default these tasks run on the `localhost` transport.
+* You can add additional parameters. For more information, see [Bolt reference material](https://puppet.com/docs/bolt/latest/bolt_command_reference.html).
+
+# Next steps
+
+Now you will 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,54 @@
+# Apply a manifest
+
+Apply a manifest against the Palo Alto firewall to create resources. This powerful Bolt feature allows you to use all the types and providers that are available in the module. 
+
+1. Create a manifest file called `manifest.pp` and add the following address ranges:
+
+```
+panos_address { 'newaddressrange':
+    ensure => 'present',
+    ip_range => '10.0.0.1-10.0.0.5',
+    tags => [],
+}
+```
+
+2. Apply the manifest using the `bolt apply` command:
+
+`bolt apply manifest.pp -n pan`
+
+This command uses the manifest to add the new address ranges above. You should see output similar to:
+
+```
+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 Palo Alto firewall web user interface and see the address ranges. 
+
+You have just used Bolt and a module to perform some basic automation!
+
+4. Lastly, if you want check what that manifest is going to do before running it full apply mode, you can the simulation mode `noop` - this highlights the idempotent capabilities of Puppet. To test with `noop`, update the previous manifest and set the ensure property of the address range as `absent` and run the following command: 
+
+`bolt apply manifest.pp -n pan --noop --debug`. 
+
+Check the output and notice that a corrective change was run in `noop` mode — this means that the address range would have been removed if you had run the command without `noop`. If you do want to remove the newly created address range, run the same command without `noop` mode: 
+
+`bolt apply manifest.pp -n pan`
+
+# Next steps
+
+That's it! You have now performed network automation with Bolt and a network device module. 
+
+There are many other network automation tasks you can perform with Bolt. To give you some ideas, take a look at the following resources:
+
+* 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.
+* 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 the [Bolt 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.
+* Check out the [Panos](https://forge.puppet.com/puppetlabs/panos/reference) on the Forge to see what else you can automate with Puppet and Bolt.

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

@@ -0,0 +1,9 @@
+# Lab overview
+
+This lab walks you through how to use the [Puppet Palo Alto firewall](https://forge.puppet.com/puppetlabs/panos) module with [Puppet Bolt](https://puppet.com/products/bolt). At the end of the lab, you will have used Bolt to run tasks and apply a manifest at the command line. No prior knowledge of 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,17 @@
+# Install prerequisites
+
+Before you begin, you need Ruby, Puppet and a Palo Alto firewall that you can test against. Open a terminal window and follow the steps below.
+
+1. To check whether you have Ruby installed, run `ruby --version`. This command prints out the version of Ruby installed. If you do not have Ruby installed, see [Ruby installer](https://rubyinstaller.org/downloads/) for instructions.
+
+2. Install the latest Puppet agent. See [Installing agents](https://puppet.com/docs/puppet/6.4/install_agents.html) for instructions. You can check that you have installed the agent correctly by running `puppet --version`. This command prints out the Puppet version number installed.
+
+3. 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. 
+
+4. 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 you will 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,26 @@
+# Download the Palo Alto module
+
+Download the Palo Alto module from the Puppet forge.
+
+1. First, check what modules you already have installed on your machine. Run `puppet module list` to see list. If you have just starting using Puppet on your workstation, you will not see any output from this command.
+
+2. Download the module from the Forge: 
+
+`puppet module install puppetlabs-panos`. 
+
+This command installs any associated dependencies that the module needs to run. 
+
+3. Check that the module and its dependencies are installed by running `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
+
+Now that you have installed the Palo Alto module, you will 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,42 @@
+# Configure Puppet device
+
+Puppet device is Puppet's 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 is used by Puppet module developers for agentless device management. For more information on its history at Puppet, see the [manual page](https://puppet.com/docs/puppet/6.4/man/device.html). Note that we are in the process of upgrading our agentless capabilities, using both [Bolt](https://puppet.com/products/bolt) and Agentless Catalog Executor(ACE) that we will release later in 2019.
+
+1. Firstly, you need to find the location of a file called `device.conf`, which contains a information about device specific configuration files. Run `puppet config print deviceconfig` to find the location of the `device.conf` file, this will look similar to `/etc/puppetlabs/puppet/device.conf`
+
+2. Check whether there is anything already in the `device.conf` file. To view the `device.conf` file, referred run `cat /etc/puppetlabs/puppet/device.conf`. If the file exists, you will see the contents displayed. If it does not exist, you will get a message stating that `No such file or directory exists`.
+
+3. The `device.conf` file needs to contain an alias, type and url to a credentials file:
+
+```
+[firewall.example.com]
+type panos
+url file:////etc/puppetlabs/puppet/devices/firewall.example.com.conf
+```
+
+4. You have told Puppet that there is a device for `puppet device` to manage. Now you need to enter credentials in the configuration file referenced above. Enter the following details inside the `/etc/puppetlabs/puppet/devices/firewall.example.com.conf` file:
+
+```
+host: 192.168.99.101
+user: admin
+password: admin
+ssl_fingerprint: <certificate SHA256 fingerprint>
+```
+
+The host is the IP address of the Palo Alto firewall you want to manage.
+
+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: The `host` needs 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. 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.
+
+# Next steps
+
+Before you can start interacting with the device, you need to sign the certificates.
+
+[Sign the Certificate](./../04-sign-the-cert/README.md)

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

@@ -0,0 +1,20 @@
+# Sign the certificate
+
+To manage a device with Puppet, you need to sign a certificate. This is normal for all server based infrastructure, and is also required for devices.
+
+1. From the command line on the host where you installed the module, run: 
+
+`puppet device --verbose --target firewall.example.com`.
+
+The `firewall.example.com` is the alias from the configuration files in the previous step. 
+
+If you receive errors at this stage, declare the panos module in a class and apply it to the proxy agent, and then run the previous command again. 
+
+> Note: Notice that the facts gathered are from your workstation and not the device under management. We are currently working on rectifying this and providing a simple way to gather facts from device nodes to include in your Puppet Enterprise deployment. Keep up-to-date on developments by checking the puppet.com/blog.
+
+
+# Next steps
+
+You are now all the set up! Next you will run the `--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,25 @@
+# Run Puppet device commands
+
+Now that you have set up your node as a proxy to the device, you can run the `puppet device` commands. If you are using Puppet Enterprise (PE), these commands are executed from here to being your device nodes under management. 
+
+1. From the command line of the node on which your device is configured, run `puppet device --resource address --target firewall.example.com` to return the addresses configured in the PANOS firewall. The output is Puppet code, similar to:
+
+```
+panos_address { 'newaddressrange':
+    ensure => 'present',
+    ip_range => '10.0.0.1-10.0.0.5',
+    tags => [],
+}
+```
+
+2. You can also apply changes using `puppet device --apply`. Create a manifest called `manifest.pp` and run `puppet device --apply manifest.pp --target panos`. This command applies the manifest to create the address range.
+
+> Note: Remember that you can use `noop` mode to simulate proposed changes before running in full apply mode.
+
+# Next steps
+
+That's it! You have configured a node to run `puppet device` to manage an agentless firewall. To take this workflow further, you can set up the node to work with PE. For more information, take a look at the following resources:
+
+* 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.

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

@@ -0,0 +1,9 @@
+# Lab overview
+
+This lab walks you through how to use the [Puppet Palo Alto firewall](https://forge.puppet.com/puppetlabs/panos) module with [puppet device](https://puppet.com/docs/puppet/6.4/puppet_device.html). At the end of this lab, you will have set up the module to work with `puppet device` for both getting and setting data. This can be extended to work with Puppet Enterprise using the [Device Manager](https://forge.puppet.com/puppetlabs/device_manager) module. No prior knowledge of Panos is required.
+
+# Get started
+
+OK, let's get into it.
+
+[Install prerequisites](./01-install-prerequisites/README.md)

docs/README.md

@@ -0,0 +1,8 @@
+# Palo Alto labs
+
+There are two Palo Alto labs available:
+
+1. [How to use the Palo Alto module with Bolt](./01-using-with-bolt/README.md)
+2. [How to use the Palo Alto module with Puppet device](./02-using-with-puppet-device/README.md). Note that this module extends to work with Puppet Enterprise (PE).
+
+These labs are intended for new users. Feedback and suggestions for improvement are welcome.