(FM-8079) Resource API and Transports Hands-on-Lab

Author: DavidS

docs/README.md

@@ -0,0 +1,7 @@
+# Resource API hands-on lab
+
+This lab will walk you through the basic steps of creating a native integration with puppet. After this you will have a fully functioning module to manage Philips HUE lights and have seen all the bits fall into place.
+
+These labs are intended for new and experienced developers alike. Please post feedback and suggestions for improvement in the [issues section](https://github.com/puppetlabs/puppet-resource_api/issues).
+
+Start with [installing the Puppet Development Kit](./hands-on-lab/01-installing-prereqs.md)

docs/hands-on-lab/01-installing-prereqs.md

@@ -0,0 +1,16 @@
+# Install the Puppet Development Kit and other tools
+
+To start out, install the Puppet Development Kit (PDK), which will provide all necessary tools and libraries to build and test modules. Additionally we recommend an emulator for the target device of this lab, a code editor with good ruby and puppet support, and GIT, a version control system to keep track of our progress.
+
+1. Choose your platform from https://puppet.com/download-puppet-development-kit; download and install the package
+
+2. If you do not have a Philips HUE hub available, you can download the [Hue-Emulator](https://github.com/SteveyO/Hue-Emulator/raw/master/HueEmulator-v0.8.jar). You will need to have Java installed to run this.
+
+3. To edit code, we recommend the cross-platform editor [VSCode](https://code.visualstudio.com/download), with the [Ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) and [Puppet](https://marketplace.visualstudio.com/items?itemName=jpogran.puppet-vscode) extensions. There are lots of other extensions that can help you with your development workflow.
+
+4. Git is a version control system that helps you keep track of changes and collaborate with others. In the course of the hands-on lab, we will show some integrations with cloud services that can help you. If you never used git before, skip this and all related steps for now.
+
+
+## Next up
+
+Having installed all of this, let's [light up a few](./02-connecting-to-the-lightbulbs.md).

docs/hands-on-lab/02-connecting-to-the-lightbulbs-emulator.png

@@ -0,0 +1,28 @@
+# Connecting to the Lightbulbs
+
+While there are no technical restrictions on the kinds of remote devices or APIs you can connect to with transports, for the purpose of this workshop we are connecting to a Philips HUE hub and make some colourful wireless lightbulbs light up. If you (understandably) do not have physical devices available, you can get going with the Hue Emulator.
+
+## Hue Emulator
+
+Download the [HueEmulator-v0.8.jar](https://github.com/SteveyO/Hue-Emulator/blob/master/HueEmulator-v0.8.jar) from [SteveyO/Hue-Emulator](https://github.com/SteveyO/Hue-Emulator).
+
+To run this emulator, you will need to have a Java Runtime installed. Once you have java installed, use `java -jar` with the emulator's filename to run it:
+
+```
+david@davids:~$ java -jar ~/Downloads/HueEmulator-v0.8.jar
+```
+
+It will not produce any output on the command line, but it will pop up a window with a hub and a few predefined lights:
+
+![](./02-connecting-to-the-lightbulbs-emulator.png)
+
+All you need now is to input a port (the default 8000 is usually fine) and press "Start" to activate the built-in server.
+
+## Connecting to your hub
+
+To connect to an actual hub, you will need be able to access the Hub on your network and get an API key. Follow the [Philips Developer docs](http://www.developers.meethue.com/documentation/getting-started) (registration required) for that.
+
+
+## Next up
+
+Once you have some lights up, head on to [create a new module](./03-creating-a-new-module.md).

docs/hands-on-lab/02-connecting-to-the-lightbulbs.md

@@ -0,0 +1,85 @@
+# Create a new module
+
+Depending on your preferences, you can use the VSCode/PDK integration or run the PDK from the command line in a terminal of your choice.
+
+## VSCode
+
+Hit up the Command Palette (⇧⌘P on the Mac or Ctrl+Shift+P on Windows and Linux) and search for the `Puppet: PDK New Module` task:
+
+![](./03-creating-a-new-module_vscode.png)
+
+Press Enter (↩) to execute this and follow the on-screen prompts.
+
+The module will open in a new VSCode window.
+
+## Command Line
+
+In your regular workspace (for example your home directory) run
+
+```
+pdk new module hue_workshop --skip-interview
+```
+
+This will create a new module `hue_workshop` in a directory of the same name, using all defaults. Output should look like the following:
+
+```
+david@davids:~/tmp$ pdk new module hue_workshop --skip-interview
+pdk (INFO): Creating new module: hue_workshop
+pdk (INFO): Module 'hue_workshop' generated at path '/home/david/tmp/hue_workshop', from template 'file:///opt/puppetlabs/pdk/share/cache/pdk-templates.git'.
+pdk (INFO): In your module directory, add classes with the 'pdk new class' command.
+david@davids:~/tmp$ ls hue_workshop/
+appveyor.yml  data      files    Gemfile.lock  manifests      Rakefile   spec   templates
+CHANGELOG.md  examples  Gemfile  hiera.yaml    metadata.json  README.md  tasks
+david@davids:~/tmp$
+```
+
+To read more about the different options when creating new modules see [the PDK docs](https://puppet.com/docs/pdk/1.x/pdk_creating_modules.html).
+
+Open the new directory in VSCode, or your coding editor of choice:
+
+```
+code -a hue_workshop
+```
+
+For this workshop, we'll active a few future defaults to make our lives easier down the line. Directly in the `hue_workshop` directory, create a file called `.sync.yml` and paste the following snippet:
+
+```
+# .sync.yml
+---
+Gemfile:
+  optional:
+    ':development':
+      - gem: 'puppet-resource_api'
+      - gem: 'faraday'
+      - gem: 'rspec-json_expectations'
+spec/spec_helper.rb:
+  mock_with: ':rspec'
+```
+
+Then run `pdk update` in the module's directory to deploy the changes into the module:
+
+```
+david@davids:~/tmp/hue_workshop$ pdk update
+pdk (INFO): Updating david-hue_workshop using the default template, from 1.10.0 to 1.10.0
+
+----------Files to be modified----------
+Gemfile
+spec/spec_helper.rb
+
+----------------------------------------
+
+You can find a report of differences in update_report.txt.
+
+Do you want to continue and make these changes to your module? Yes
+
+------------Update completed------------
+
+2 files modified.
+
+david@davids:~/tmp/hue_workshop$
+```
+
+
+## Next up
+
+Once you have the module ready, head on to [add a transport](./04-adding-a-new-transport.md).

docs/hands-on-lab/03-creating-a-new-module.md

@@ -0,0 +1,105 @@
+# Add a new transport
+
+[Eventually](https://github.com/puppetlabs/pdk/pull/666) there will be a `pdk new transport`, for now you'll need to copy in a few files for this workshop.
+
+Copy the files from [this directory](./04-adding-a-new-transport/) into your new module:
+
+* .sync.yml
+* lib/puppet/transport/hue.rb
+* lib/puppet/transport/schema/hue.rb
+* lib/puppet/util/network_device/hue/device.rb
+* spec/unit/puppet/transport/hue_spec.rb
+* spec/unit/puppet/transport/schema/hue_spec.rb
+
+Afterwards run `pdk update --force` to enable a few future defaults that are required for these templates:
+
+```
+david@davids:~/tmp/hue$ pdk update --force
+pdk (INFO): Updating david-hue using the default template, from master@c43fc26 to master@c43fc26
+
+----------Files to be modified----------
+Gemfile
+spec/spec_helper.rb
+
+----------------------------------------
+
+You can find a report of differences in update_report.txt.
+
+[✔] Resolving default Gemfile dependencies.
+
+------------Update completed------------
+
+2 files modified.
+
+david@davids:~/tmp/hue$
+```
+
+## Checkpoint
+
+To make sure that everything went well with creating the module and copying in the files you can run `pdk validate --parallel` and `pdk test unit`:
+
+```
+david@davids:~/tmp/hue$ pdk validate --parallel
+pdk (INFO): Running all available validators...
+pdk (INFO): Using Ruby 2.5.5
+pdk (INFO): Using Puppet 6.4.2
+┌ [✔] Validating module using 5 threads ┌
+├──[✔] Checking metadata syntax (metadat├──son tasks/*.json).
+├──[✔] Checking task names (tasks/**/*).├──
+└──[✔] Checking YAML syntax (["**/*.yaml├──"*.yaml", "**/*.yml", "*.yml"]).
+└──[/] Checking module metadata style (metadata.json).
+└──[✔] Checking module metadata style (metadata.json).
+info: puppet-syntax: ./: Target does not contain any files to validate (**/*.pp).
+info: task-metadata-lint: ./: Target does not contain any files to validate (tasks/*.json).
+info: puppet-lint: ./: Target does not contain any files to validate (**/*.pp).
+david@davids:~/tmp/hue$ pdk test unit
+pdk (INFO): Using Ruby 2.5.5
+pdk (INFO): Using Puppet 6.4.2
+[✔] Preparing to run the unit tests.
+[✔] Running unit tests in parallel.
+Run options: exclude {:bolt=>true}
+  Evaluated 6 tests in 2.405066937 seconds: 0 failures, 0 pending.
+david@davids:~/tmp/hue$
+```
+
+If you're working with a version control system, this would also be a good point to make the first commit to store away all the boilerplate code and later revisit the changes you made. Here I'm showing how to initialise a local git repository and storing all files in an initial commit:
+
+```
+david@davids:~/tmp/hue$ git init
+Initialized empty Git repository in ~/tmp/hue/.git/
+david@davids:~/tmp/hue$ git add -A
+david@davids:~/tmp/hue$ git commit -m 'initial commit'
+[master (root-commit) 67951dd] initial commit
+ 26 files changed, 887 insertions(+)
+ create mode 100644 .fixtures.yml
+ create mode 100644 .gitattributes
+ create mode 100644 .gitignore
+ create mode 100644 .gitlab-ci.yml
+ create mode 100644 .pdkignore
+ create mode 100644 .puppet-lint.rc
+ create mode 100644 .rspec
+ create mode 100644 .rubocop.yml
+ create mode 100644 .sync.yml
+ create mode 100644 .travis.yml
+ create mode 100644 .yardopts
+ create mode 100644 CHANGELOG.md
+ create mode 100644 Gemfile
+ create mode 100644 README.md
+ create mode 100644 Rakefile
+ create mode 100644 appveyor.yml
+ create mode 100644 data/common.yaml
+ create mode 100644 hiera.yaml
+ create mode 100644 lib/puppet/transport/hue.rb
+ create mode 100644 lib/puppet/transport/schema/hue.rb
+ create mode 100644 lib/puppet/util/network_device/hue/device.rb
+ create mode 100644 metadata.json
+ create mode 100644 spec/default_facts.yml
+ create mode 100644 spec/spec_helper.rb
+ create mode 100644 spec/unit/puppet/transport/hue_spec.rb
+ create mode 100644 spec/unit/puppet/transport/schema/hue_spec.rb
+david@davids:~/tmp/hue$
+```
+
+## Next up
+
+Once you have everything ready, head on to [implement the transport](./05-implementing-the-transport.md).

docs/hands-on-lab/03-creating-a-new-module_vscode.png

@@ -0,0 +1,9 @@
+# use future defaults
+---
+Gemfile:
+  optional:
+    ':development':
+      - gem: 'puppet-resource_api'
+spec/spec_helper.rb:
+  mock_with: ':rspec'
+

docs/hands-on-lab/04-adding-a-new-transport.md

@@ -0,0 +1,36 @@
+module Puppet::Transport
+  # The main connection class to a Hue endpoint
+  class Hue
+    # Initialise this transport with a set of credentials
+    def initialize(context, connection_info)
+      # because `password` is marked sensitive, we can log it here and it will be masked
+      context.debug("Connecting to #{connection_info[:user]}:#{connection_info[:password]}@#{connection_info[:host]}:#{connection_info[:port]}")
+      # store the credentials for later use
+      # alternatively, connect right here
+      @connection_info = connection_info
+    end
+
+    # Verifies that the stored credentials are valid, and that we can talk to the target
+    def verify(context)
+      context.debug("Checking connection to #{@connection_info[:host]}:#{@connection_info[:port]}")
+      # in a real world implementation, the password would be checked by connecting
+      # to the target device or checking that an existing connection is still alive
+      raise 'authentication error' if @connection_info[:password].unwrap == 'invalid'
+    end
+
+    # Retrieve facts from the target and return in a hash
+    def facts(context)
+      context.debug('Retrieving facts')
+      {
+        operatingsystem: 'example',
+        operatingsystemrelease: '1.2.3.4',
+      }
+    end
+
+    # Close the connection and release all resources
+    def close(context)
+      context.debug('Closing connection')
+      @connection_info = nil
+    end
+  end
+end

docs/hands-on-lab/04-adding-a-new-transport/.sync.yml

@@ -0,0 +1,28 @@
+require 'puppet/resource_api'
+
+Puppet::ResourceApi.register_transport(
+  name: 'hue',
+  desc: <<-DESC,
+      This transport provides Puppet with the capability to connect to hue targets.
+    DESC
+  features: [],
+  connection_info: {
+    host: {
+      type: 'String',
+      desc: 'The hostname or IP address to connect to for this target.',
+    },
+    port: {
+      type: 'Optional[Integer]',
+      desc: 'The port to connect to. Defaults to ...',
+    },
+    user: {
+      type: 'String',
+      desc: 'The name of the user to authenticate as.',
+    },
+    password: {
+      type:      'String',
+      desc:      'The password for the user.',
+      sensitive: true,
+    },
+  },
+)