Documentation and release prep (#41)

* readme updates * readme updates * update readme * uprelease prep * uprelease prep * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * upreference file * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update docs * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * Doc Review * Formatting new line outside of ' tag * Update README.md Co-authored-by: Jarret Lavallee <[email protected]> * formatting Co-authored-by: Jarret Lavallee <[email protected]>
puppetlabs · Jan 15, 2021 · 58e5085 · 58e5085
1 parent 65a8669
commit 58e5085
Show file tree

Hide file tree

Showing 8 changed files with 304 additions and 64 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ All notable changes to this project will be documented in this file.
 
 **Features**
 
+Initial Release
+
 **Bugfixes**
 
 **Known Issues**
diff --git a/README.md b/README.md
@@ -30,43 +30,168 @@ Software required for the proper functioning of the RSAN will be deployed on the
 
 
 ### Setup Requirements 
-Dependencies
 
-derdanne/nfs (>= 2.1.5)
-puppetlabs/postgresql (>= 6.6.0)
-puppetlabs/puppet_metrics_dashboard (>= 2.3.0)
-puppetlabs/stdlib (>= 4.5.0 < 7.0.0)
-puppetlabs/concat (>= 1.1.2 < 7.0.0)
-puppetlabs/transition (>= 0.1.0 < 1.0.0)
-herculesteam/augeasproviders_core (>= 2.1.5 < 4.0.0)
-herculesteam/augeasproviders_shellvar (>= 1.2.0 < 5.0.0)
-puppetlabs/apt (>= 2.0.0 < 8.0.0)
-puppet-grafana (>= 3.0.0 < 7.0.0)
-puppet-telegraf (>= 2.0.0 < 4.0.0)
-puppetlabs-apt (>= 4.3.0 < 8.0.0)
-puppetlabs-inifile (>= 2.0.0 < 5.0.0)
-puppetlabs-puppetserver_gem (>= 1.1.1 < 3.0.0)
-puppet/openvpn (>= 8.3.0)
+#### Module Dependencies
 
+- derdanne/nfs (>= 2.1.5)
+- puppetlabs/postgresql (>= 6.6.0)
+- puppetlabs/puppet_metrics_dashboard (>= 2.3.0)
+- puppetlabs/stdlib (>= 4.5.0 < 7.0.0)
+- puppetlabs/concat (>= 1.1.2 < 7.0.0)
+- puppetlabs/transition (>= 0.1.0 < 1.0.0)
+- herculesteam/augeasproviders_core (>= 2.1.5 < 4.0.0)
+- herculesteam/augeasproviders_shellvar (>= 1.2.0 < 5.0.0)
+- puppetlabs/apt (>= 2.0.0 < 8.0.0)
+- puppet-grafana (>= 3.0.0 < 7.0.0)
+- puppet-telegraf (>= 2.0.0 < 4.0.0)
+- puppetlabs-apt (>= 4.3.0 < 8.0.0)
+- puppetlabs-inifile (>= 2.0.0 < 5.0.0)
+- puppetlabs-puppetserver_gem (>= 1.1.1 < 3.0.0)
 
 
+#### Minimum Hardware requirements
+
+
+| AWS EC2|Cores| RAM |Disk|
+| --- | ----------- | --| --|
+| m1.medium | 2 CPU | 4GB Memory | 40GB Disk 
+
+#### OS Restrictions
+
+RSAN will support RHEL / Debian / Ubuntu however due to the additional of PE Client tools in the installation, you are restricted to installing it on a platform with the same OS as the Primary PE Server.
 
 ### Beginning with rsan
 
-RSAN has Two Classes:
+RSAN has two main classes for use in the installation:
 
  - rsan::exporter - to be applied to all Puppet infrastructure agents - Console node group "PE Infrastructure Agent"
- - rsan::importer - to be applied to a single node which will be come the Remote Support Access Node
+ - rsan::importer - to be applied to a single node which will be come the Remote Support Access Node(RSAN)
+
+Following the application of these clases to the infrastructure, Puppet Will need to be run on the corresponding agents in the following order:
 
-Adding these two classes will set up all applications and configurations to run  RSAN
+Infrastructure Agent(s)->RSAN Agent->Infrastrcture Agent(s)->RSAN Agent
 
 ## Usage
+The following outlines the main features of RSAN and how to consume them
+### Live Telemetry Display
+
+The Rsan node will host an instance of the [Puppet Metrics Dashboard](https://forge.puppet.com/modules/puppetlabs/puppet_metrics_dashboard)
+
+The Dashboard can be accessed on
+
+**URL:** http://<RSAN-ip\>:3000\
+**User:** admin\
+**Password:** admin
+
+For advanced configuration and documentation please see [Puppet Metrics Dashboard](https://forge.puppet.com/modules/puppetlabs/puppet_metrics_dashboard)
+
+### Infrastructure node file and log access	
+
+The RSAN node will, by default, mount `/var/log/`, `/opt/puppetlabs` and `/etc/puppetlabs` from each of the Puppet Enterprise Infrastructure nodes on the RSAN platform in the following location, as read-only file systems.
+
+`/var/pesupport/<FQDN of Infrastructure node\>/var/log`\
+`/var/pesupport/<FQDN of Infrastructure node\>/opt/puppetlabs`\
+`/var/pesupport/<FQDN of Infrastructure node\>/etc/puppetlabs`
+
+#### Optional Configuration
+
+The RSAN Class assumes the RSAN server will mount the shared partitions using the IP address Source designated by the "ipaddress" fact. In any deployment should this assertion not be true, it is nessary to set the following parameter to the source IP address of the RSAN Host:
+
+In Hiera 
+
+```
+rsan::exporter::rsan_importer_ips:
+  - 1.2.3.4
+  ```
+
+Console Class Declaration
+
+```
+["1.2.3.4"]
+```
+
+### PE Client tools
+
+The RSAN node will deploy Puppet Client tools for use by Puppet Enterprise on the RSAN platform, For More information please see the Puppet Enterprise Documentation:
+
+[PE Client tools](https://puppet.com/docs/pe/2019.8/installing_pe_client_tools.html)
+
+A supplementary task is available to generate an RBAC user and role, so that the credentials may be used provided to Puppet Enterprise Support personnel.  
+<br>
+#### Creating Support User  
+<br>
+Run the following task against the Primary Puppet Enterprise Server\
+For information on executing PE tasks see the [Puppet Enterprise Documentation](https://puppet.com/docs/pe/2019.8/tasks_in_pe.html)\
+RSAN::supportuser\
+When successful the task will return a password, this should be delivered to Puppet Enterprise Support personnel.
+<br>
+<br>
+The Task creates the following user and role:
+<br>
+<br>
+**User:** pesupport 
+
+**Role:** PE Suport Role 
+
+The role is intentonally left without permissions, and should be given only the permissions the installing organisation are authorised to grant to Puppet Enterprise Support personnel. For more information on RBAC permissions please see the [Puppet Enterprise Documentation](https://puppet.com/docs/pe/2019.8/rbac_permissions_intro.html)
+
+### Puppet Enterprise Database Access	
+
+The RSAN Platform has a Postgresql client installed, and is granted certificate based access to all Puppet Enterprise Databases on any pe_postgresl node within the current deployment. The access is limited to the [SELECT](https://www.postgresql.org/docs/11/sql-grant.html) privilege and is therefore READONLY in nature.
+
+To use this function execute the following command from the CLI of the RSAN host
+
+```
+psql "host=$(puppet config print server) port=5432 user=rsan sslmode=verify-full sslcert=$(puppet config print hostcert) sslkey=$(puppet config print hostprivkey) sslrootcert=$(puppet config print localcacert) dbname=<pe_db_name>"
+```
+
+Where valid options for <pe_db_name> are:
+
+- pe-rbac 
+- pe-puppetdb 
+- pe-orchestrator 
+- pe-inventory 
+- pe-classifier 
+- pe-activity
+
+## Uninstallation 
+
+To Uninsuall RSAN from your Puppet Enterprise Infrastructure.
+
+ - Remove the following Classification:
+rsan::exporter\
+rsan::importer
+
+ - Add the following classification to the "PE Infrastructure Agent" node group
+ rsan::remove_exporter
+
+  - Remove the following classification to the "PE Infrastructure Agent" node group
+ rsan::remove_exporter
+
+  - Run Puppet on all nodes in "PE Infrastructure Agent" node group
+
+   - Decommission the RSAN platform 
 
-TBC - detailed description of feature switches and configurable parameters
 
 ## Limitations
+ - The RSAN importer class should only be applied one agent node
+ - All features are currently enabled and can not be individually disabled, this will be addressed in future releases
+
+## Known Issues
+
+- When accessing the database from the RSAN node for the first time, an error message will be presented: [#40](https://github.com/MartyEwings/RSAN/issues/40)
+
+```psql: private key file "/etc/puppetlabs/puppet/ssl/private_keys/rsan-target.platform9.puppet.net.pem" has group or world access; permissions should be u=rw (0600) or less```
+
+ To workaround change the private key file to 0600 or less, Puppet will manage this file back to incorrect permissions, for long term access making a copy of the key with the correct permissions is the best course of action. 
+
+ - PuppetDB Metric Collection fails due to CVE-2020-7943  [27](https://github.com/MartyEwings/RSAN/issues/27)
 
+Please refer to the documenation of Puppet Metrics collector for recommended work arounds
 
+ - RSAN NFS volumes are mounted RW, but exported RO  [26](https://github.com/MartyEwings/RSAN/issues/26)
+
+ There is no impact to the end user
 
 ## Contributions
 

diff --git a/REFERENCE.md b/REFERENCE.md
@@ -0,0 +1,155 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Classes
+
+* [`rsan::exporter`](#rsanexporter)
+* [`rsan::importer`](#rsanimporter): Class to consume the resources provided by the exporter class. when applied to a node, all tooling agttributed to RSAN will be set up
+* [`rsan::remove_exporter`](#rsanremove_exporter): A short summary of the purpose of this class
+
+### Functions
+
+* [`rsan::get_postgres_hosts`](#rsanget_postgres_hosts)
+* [`rsan::get_puppet_servers`](#rsanget_puppet_servers)
+* [`rsan::get_puppetdb_hosts`](#rsanget_puppetdb_hosts)
+* [`rsan::get_rsan_importer_ips`](#rsanget_rsan_importer_ips)
+* [`rsan::license_uuid`](#rsanlicense_uuid): return the uuid from a Puppet license file supplied in $content If no $content parameter specified, tries to read the license file from /etc/
+
+### Tasks
+
+* [`supportuser`](#supportuser): Creates pesupport user and PE Support Role, generated password should be shared with Puppet Enterprise Support personnel
+
+## Classes
+
+### `rsan::exporter`
+
+The rsan::exporter class.
+
+#### Parameters
+
+The following parameters are available in the `rsan::exporter` class.
+
+##### `rsan_importer_ips`
+
+Data type: `Array`
+
+
+
+Default value: `rsan::get_rsan_importer_ips()`
+
+##### `rsan_host`
+
+Data type: `Optional[String]`
+
+
+
+Default value: ``undef``
+
+### `rsan::importer`
+
+Class to consume the resources provided by the exporter class.
+when applied to a node, all tooling agttributed to RSAN will be set up
+
+#### Examples
+
+##### 
+
+```puppet
+include rsan::importer
+```
+
+### `rsan::remove_exporter`
+
+A description of what this class does
+
+#### Examples
+
+##### 
+
+```puppet
+include rsan::remove_exporter
+```
+
+## Functions
+
+### `rsan::get_postgres_hosts`
+
+Type: Puppet Language
+
+The rsan::get_postgres_hosts function.
+
+#### `rsan::get_postgres_hosts()`
+
+The rsan::get_postgres_hosts function.
+
+Returns: `Any`
+
+### `rsan::get_puppet_servers`
+
+Type: Puppet Language
+
+The rsan::get_puppet_servers function.
+
+#### `rsan::get_puppet_servers()`
+
+The rsan::get_puppet_servers function.
+
+Returns: `Any`
+
+### `rsan::get_puppetdb_hosts`
+
+Type: Puppet Language
+
+The rsan::get_puppetdb_hosts function.
+
+#### `rsan::get_puppetdb_hosts()`
+
+The rsan::get_puppetdb_hosts function.
+
+Returns: `Any`
+
+### `rsan::get_rsan_importer_ips`
+
+Type: Puppet Language
+
+The rsan::get_rsan_importer_ips function.
+
+#### `rsan::get_rsan_importer_ips()`
+
+The rsan::get_rsan_importer_ips function.
+
+Returns: `Array` List of IP addresses for RSAN nodes or an empty array
+
+### `rsan::license_uuid`
+
+Type: Puppet Language
+
+return the uuid from a Puppet license file supplied in $content
+If no $content parameter specified, tries to read the license file
+from /etc/puppetlabs/license.key
+
+#### `rsan::license_uuid(Optional[String] $content)`
+
+return the uuid from a Puppet license file supplied in $content
+If no $content parameter specified, tries to read the license file
+from /etc/puppetlabs/license.key
+
+Returns: `String`
+
+##### `content`
+
+Data type: `Optional[String]`
+
+
+
+## Tasks
+
+### `supportuser`
+
+Creates pesupport user and PE Support Role, generated password should be shared with Puppet Enterprise Support personnel
+
+**Supports noop?** false
+
diff --git a/manifests/importer.pp b/manifests/importer.pp
@@ -54,13 +54,6 @@
   #######################################################################################
 
 
-  ##################### 4. VPN client (openvpn) ########################################
-  # deploy openvpn client, set up connection with preshared key use licence key UUID as preshared key
-  # destination will need IT involvement, scope to make it possible with a dummy end point
-  # Task to enable and disable connection
-  ######################################################################################
-
-
 
 
 

diff --git a/metadata.json b/metadata.json
@@ -1,6 +1,6 @@
 {
   "name": "martyewings-rsan",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "author": "Martin Ewings",
   "summary": "Module to Configure Remote Support Access Node for Puppet Enterprise",
   "license": "Apache-2.0",

diff --git a/tasks/supportsession.json b/tasks/supportsession.json