(FM-7973) Adding hands on labs for bolt and puppet device #80
Conversation
Codecov Report
@@ Coverage Diff @@
## master #80 +/- ##
=========================================
+ Coverage 99.15% 99.26% +0.1%
=========================================
Files 39 40 +1
Lines 948 1084 +136
=========================================
+ Hits 940 1076 +136
Misses 8 8
Continue to review full report at Codecov.
|
DavidS
changed the title
|
This supersedes #79 |
|
|
||
| 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. |
|
|
||
| 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' |
There was a problem hiding this comment.
This forge directive shouldn't be necessary and may confuse users who already have a Puppetfile
|
|
||
| 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`. |
There was a problem hiding this comment.
I think it's better for users to just start with a project directory in an arbitrary spot. That seems to be more common than using this path.
There was a problem hiding this comment.
@adreyer this has been updated to point them in using https://puppet.com/docs/bolt/latest/bolt_project_directories.html#local-project-directory rather than the .puppetlabs/bolt directory - if you could have a look over the change to see if it makes sense.
|
|
||
| 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. |
There was a problem hiding this comment.
Do we have examples of how to setup the ssl certificate?
There was a problem hiding this comment.
The setup of SSL certificates would be on the firewall itself, and I believe is covered in the docs (https://docs.paloaltonetworks.com/pan-os/8-0/pan-os-admin/certificate-management.html)
For using self signed certs we have a document on confluence (https://confluence.puppetlabs.com/display/ECO/Using+self+signed+certs+on+Palo+Alto+VMPooler+Images) for our own testing.
There was a problem hiding this comment.
In the first step we're talking about setting up a VM for testing. I would not be surprised if a significant portion of users will try running this against their actual devices (hopefully in a test lab).
To make sure that this reflects a production setup and to show that it doesn't break the bank to enable SSL verification, this section needs to describe how to retrieve the fingerprint from the browser or target system and how to set it up here.
|
|
||
| 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. |
There was a problem hiding this comment.
This is incorrect. The target is pan which is a remote target. By default tasks for remote targets run on localhost. By setting run-as proxy to something else the task can run elsewhere. I think it's probably better to avoid that level of detail at this point.
| @@ -0,0 +1,38 @@ | |||
| # Execute a Manifest | |||
There was a problem hiding this comment.
This should probably be "applying a manifest"
DavidS
changed the title
Thomas-Franklin
force-pushed
the
addingpuppetdevicelab
branch
from
b4fa671
to
8c9c943
Compare
Thomas-Franklin
force-pushed
the
addingpuppetdevicelab
branch
from
8c9c943
to
5628fdb
Compare
|
Tagging @clairecadman - if you get a moment could you check over these docs? :-) |
|
@Thomas-Franklin Sure! I'll take a look at this either later today or tomorrow morning. :) |
|
Can we get a link to the |
| @@ -0,0 +1,16 @@ | |||
| # Install Prerequisites | |||
|
|
|||
| Before you begin, you need a Ruby, Bolt and a Palo Alto firewall that you can test against. Open a terminal window and follow the steps below. | |||
There was a problem hiding this comment.
@DavidS You give instructions on downloading Bolt and Palo Alto, but not Ruby. Is this something they will already have? If so, do you need mention it here when you don't talk about it again?
There was a problem hiding this comment.
installing the bolt package, like the AIO and the PDK packages, already gives you a ruby install.
There was a problem hiding this comment.
... so this sentence needs to be fixed to not say ruby.
| @@ -27,12 +21,22 @@ nodes: | |||
| ssl_fingerprint: <certificate SHA256 fingerprint> | |||
| ``` | |||
|
|
|||
| *Note*: The `name` 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 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. | |||
| The `name` needs to match the `Common Name (CN)` of the certificate of the firewall. In this example, we have combined username and password. | |||
There was a problem hiding this comment.
@clairecadman I am not sure of this sentence as it seems to combine different things.
The sentence about name matching the CN is fine, but for the second part, maybe In this example, we are using the username and password for authenticating with the device. since the module accepts a user/password combination or an apikey
There was a problem hiding this comment.
@DavidS I've finished editing, please review before merging. I think you should be consistent with the name of the module, either call it the "panos module" or "palo alto module". These are used interchangeably, which makes it seem like there is two different modules. Thanks!
|
|
||
| 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: |
There was a problem hiding this comment.
This should be --resource panos_address vs --resource address
No description provided.