document types and providers puppetserver known issues

NATIVE_TYPES_AND_PROVIDERS.md

@@ -1,6 +1,29 @@
 Experimental native types and providers
 ==
 
+**The semantics and API of these types should be considered _unstable_ and
+almost certainly will change based on feedback.  It is currently unclear if
+these types will be considered part of the public API or treated as private to
+the module.**
+
+
+#### Table of Contents
+
+1. [Configuration](#configuration)
+    * [`puppetserver`](#puppetserver)
+2. [Types](#types)
+    * [`jenkins_authorization_strategy`](#jenkins_authorization_strategy)
+    * [`jenkins_credentials`](#jenkins_credentials)
+    * [`jenkins_job`](#jenkins_job)
+    * [`jenkins_num_executors`](#jenkins_num_executors)
+    * [`jenkins_security_realm`](#jenkins_security_realm)
+    * [`jenkins_slaveagent_port`](#jenkins_slaveagent_port)
+    * [`jenkins_user`](#jenkins_user)
+3. [TODO](#todo)
+
+
+Configuration
+--
 This family of types and providers that manages jenkins via the `cli` jar take
 common configuration from the parameters of a class named
 `jenkins::cli::config`.  The implementation of this class may be empty.
@@ -45,8 +68,46 @@ export FACTER_jenkins_ssh_private_key=/home/vagrant/insecure_private_key
 puppet resource --modulepath=/tmp/vagrant-puppet/modules-998ea1817cb4dea9c136a57fd18781c5/ jenkins_user --debug --trace
 ```
 
+All providers presently require `java`, the jenkins CLI jar, and the jenkins
+master service to be running.  Most require the presence of
+`puppet_helper.groovy`.  The following puppet code snippet will prepare a node
+sufficiently for all providers to function.
+
+```
+class { '::jenkins':
+  install_java => true,
+  cli          => true,
+}
+include ::jenkins::cli_helper
+```
+
 The ruby gem `retries` is presently required by all providers.
 
+### `puppetserver`
+
+There is a known issue with `puppetserver` being unable to load code from
+modules outside of `./lib/puppet`.  This effects all modules using the
+recommended `PuppetX::<vendor>` namespace.
+
+The work around (only required to use these new native types) is to edit
+`/etc/puppetlabs/puppetserver/conf.d/puppetserver.conf` and add the "cache" dir to the `ruby-load-path` entry.  Eg.,
+
+```
+jruby-puppet: {
+    ruby-load-path: [/opt/puppetlabs/puppet/lib/ruby/vendor_ruby, /opt/puppetlabs/puppet/cache/lib]
+    ...
+}
+```
+
+See [SERVER-973](https://tickets.puppetlabs.com/browse/SERVER-973)
+
+Additionally, the `retries` gem is required.  This may be installed on the master by running:
+
+```
+/opt/puppetlabs/bin/puppetserver gem install retries
+```
+
+
 Types
 --
 

README.md

@@ -4,6 +4,27 @@ This is intended to be a re-usable
 [Puppet](http://www.puppetlabs.com/puppet/introduction/) module that you can
 include in your own tree.
 
+# Experimental Types and Providers
+
+_The experimental types/providers are **not for the faint of heart**. If you are
+starting out with this module you probably want to skip directly to [Getting
+Started](#getting-started)._
+
+A family of experimental native types and providers has been added to this
+module, in parallel to the existing classes and defined types, with the goal of
+soliciting feedback.  One of the primary benefits of these new types is not
+requiring manifest changes to manage jenkins with or without "security"
+enabled.  The goal is to eventually replace the functionality of the existing
+classes/defines with the new types.  _Usage feedback (positive and negative),
+bug reports and/or PRs would be greatly welcomed._
+
+**The semantics and API of these types should be considered _unstable_ and
+almost certainly will change based on feedback.  It is currently unclear if
+these types will be considered part of the public API or treated as private to
+the module.**
+
+See [NATIVE_TYPES_AND_PROVIDERS.md](NATIVE_TYPES_AND_PROVIDERS.md)
+
 # Using puppet-jenkins
 
 ## Getting Started