rsan

Table of Contents

1. RSAN is currently part of a Beta Program
2. Description
3. Setup - The basics of getting started with rsan
   • What RSAN modifies in your PE Installation
   • Setup requirements
   • Beginning with rsan
4. Usage - Configuration options and additional functionality
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

RSAN is currently part of a Beta Program

The Puppet Enterprise Support team is opening an exciting Beta to help us remove some obstacles our customers have reported when engaging the Support Team for incident resolution. The Remote Support Service Beta is a combination of a Service provided by the Support team and Puppet Module named RSAN (Remote Support Access Node). Puppet Enterprise Support will work with you to see how your organization can access the RSAN deployment and how that process should be implemented. , Currently we have two access options; direct as an incoming VPN connection from the Puppet Support Member, or a simple screen share on the video conferencing software of your choice.

How you can get involved

As an existing Puppet Enterprise customer with access to the Support Portal, open a Priority 4 ticket with the subject “Participate in the RSAN beta” and a support engineer will engage with you regarding access methods and any help installing the module you may need.

Description

The Remote Support Access Node (RSAN) will allow Puppet support engineers to conduct live troubleshooting, resolving problems more quickly and efficiently and lead to a reduction of system disruption to the customer.
Customers currently must deliver large volumes of data to support and resolution time is hindered by transfer logistics and privacy concerns. This same data must then be processed by internal support engineers leading to artificially decreased capacity of the support team.

The RSAN platform is designed to be a contained infrastructure endpoint in the customer Puppet Enterprise environment, collating data and access, useful in incident resolution for the target customer deployment. The node will allow for read-only access to Puppet Enterprise Component Data and configuration, and limit other access through Puppet Enterprise’s built-in Role Based Access Control(RBAC).

Setup

What RSAN modifies in your PE Installation

RSAN will Export NFS mounts of key directories from each infrastructure node, while also setting up requirements for gathering of metrics and Database access for the RSAN node. Software required for the proper functioning of the RSAN will be deployed on the target agent node.

Setup Requirements

Module Dependencies

• derdanne/nfs (>= 2.1.5)
• puppetlabs/postgresql (>= 6.6.0)
• puppetlabs/puppet_metrics_dashboard (>= 2.3.0)
• puppetlabs/stdlib (>= 4.5.0 < 8.1.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 < 10.0.0)
• puppet-telegraf (>= 2.0.0 < 5.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

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 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)

Following the application of these classes to the infrastructure, Puppet Will need to be run on the corresponding agents in the following order:

Infrastructure Agent(s)->RSAN Agent->Infrastructure 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

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

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 necessary 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"]

The RSAN::Exporter class allows for the NFS mounts to be optionally available, to disable existing mounts, or prevent the mounts from installing in the first place set the following parameter:

In Hiera

rsan::exporter::nfsmount: false

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

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.

Creating Support User

User: pesupport

Role: PE Suport Role

The role is intentionally 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

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 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 Uninstall 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

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
• The current version does not have any built in remote access capability

Known Issues

• PuppetDB Metric Collection fails due to CVE-2020-7943 27

Please refer to the documentation of Puppet Metrics Dashboard for recommended work arounds

• RSAN NFS volumes are mounted RW, but exported RO 26

  There is no impact to the end user

Contributions

For feature development + bug reporting:

• A Git Issue should exist or be created per feature or Bug
• Repository should be forked and any changes made by way of PR to the Main Branch
• PRS should always reference a git issue

Reference

Table of Contents

Classes

• rsan::exporter: Sets up target nodes with nessary services and access for RSAN When Applied to the Infrastruture Agent Node group, Will dynamically configure
• 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
• rsan::remove_exporter: disables and removes services and components enabled by the exporter class

Functions

• rsan::get_postgres_hosts: Function to provide a list of pe_postgresql hosts to RSAN
• rsan::get_puppet_servers: Function to return a list of components running pe_puppetserver to RSAN
• rsan::get_puppetdb_hosts
• rsan::get_rsan_importer_ips
• rsan::license_uuid: If no $content parameter specified, tries to read the license file from /etc/puppetlabs/license.key

Tasks

• supportuser: Creates pesupport user and PE Support Role, generated password should be shared with Puppet Enterprise Support personnel

Classes

rsan::exporter

Sets up target nodes with nessary services and access for RSAN When Applied to the Infrastruture Agent Node group, Will dynamically configure all matching nodes to allow access to key elements of Puppet Enterprise to the RSAN node

Examples

include rsan::exporter

Parameters

The following parameters are available in the rsan::exporter class:

• rsan_importer_ips
• rsan_host
• pg_user
• pg_group
• pg_psql_path
• nfsmount_log
• nfsmount_etc
• nfsmount_opt
• logdir

rsan_importer_ips

Data type: Array

An array of rsan ip addresses Defaults to the output of a PuppetDB query

Default value: rsan::get_rsan_importer_ips()

rsan_host

Data type: Optional[String]

The certname of the rsan node

Default value: undef

pg_user

Data type: Optional[String]

The postgres user PE uses

Default value: 'pe-postgres'

pg_group

Data type: Optional[String]

The postgres group PE uses the default is pg_user

Default value: $pg_user

pg_psql_path

Data type: Optional[String]

The path to the postgres binary in pe

Default value: '/opt/puppetlabs/server/bin/psql'

nfsmount_log

Data type: Boolean

Trigger to turn NFS Mounts for logging On Or Off

Default value: true

nfsmount_etc

Data type: Boolean

Trigger to turn NFS Mounts for /etc/puppetlabs On Or Off

Default value: true

nfsmount_opt

Data type: Boolean

Trigger to turn NFS Mounts for /opt/puppetlabs On Or Off

Default value: true

logdir

Data type: Enum['/var/log/', '/var/log/puppetlabs/']

Allows the scope of logging to be narrowed

Default value: '/var/log/'

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

include rsan::importer

rsan::remove_exporter

In the event RSAN should be uninstalled on all or some of the exporter nodes, this will stop NFS service, and remove the database components if applied to a postgres node

Examples

include rsan::remove_exporter

Functions

rsan::get_postgres_hosts

Type: Puppet Language

Function to provide a list of pe_postgresql hosts to RSAN

rsan::get_postgres_hosts()

Function to provide a list of pe_postgresql hosts to RSAN

Returns: Array List of FQDN

rsan::get_puppet_servers

Type: Puppet Language

Function to return a list of components running pe_puppetserver to RSAN

rsan::get_puppet_servers()

Function to return a list of components running pe_puppetserver to RSAN

Returns: Array List of Fqdn of nodes with the Master profile

rsan::get_puppetdb_hosts

Type: Puppet Language

The rsan::get_puppetdb_hosts function.

rsan::get_puppetdb_hosts()

The rsan::get_puppetdb_hosts function.

Returns: Array List of node running Puppetdb

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

If no $content parameter specified, tries to read the license file from /etc/puppetlabs/license.key

rsan::license_uuid(Optional[String] $content)

If no $content parameter specified, tries to read the license file from /etc/puppetlabs/license.key

Returns: String the uuid from a Puppet license file supplied in $content

content

Data type: Optional[String]

An array of rsan ip addresses Defaults to the output of a PuppetDB query

Tasks

supportuser

Creates pesupport user and PE Support Role, generated password should be shared with Puppet Enterprise Support personnel

Supports noop? false

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v0.3.0 (2021-12-03)

Full Changelog

Added

• (SUP-2817) Consider the distributed architecture of PE_XL and make log scope configurable #81 (MartyEwings)

v0.2.0 (2021-06-28)

Full Changelog

Added

• Make NFS mounts optional #66 (MartyEwings)

Fixed

• (sup-2385) Resolve unresponsive RSAN node as a result of missing NFS Server #64 (MartyEwings)

v0.1.3 (2021-06-10)

Full Changelog

Fixed

• Update Readme for Beta Launch #59 (MartyEwings)

0.1.2 (2021-05-07)

Full Changelog

Fixed

• (SUP-2412) changed privatekey permissions for psql client #51 (MartyEwings)
• Fix for Issue 49 - New replica installation #50 (MartyEwings)
• Fix #46 (SUP-2384) #47 (MartyEwings)
• (SUP-2386) updating documentation and dependancies [SUP-2386] #45 (MartyEwings)

0.1.1 (2021-01-18)

Full Changelog

Fixed

• Metadata and spelling corrections #42 (MartyEwings)

0.1.0 (2021-01-15)

Full Changelog

Added

• Documentation and release prep #41 (MartyEwings)
• remove mocha deprecation warnings #39 (MartyEwings)
• {WIP} remove exporter class state from infra nodes #36 (MartyEwings)
• Feature - PE Client tools Deployment #12 (MartyEwings)
• Morgan lillie #11 (morgan-lillie)
• W.I.P. PR2: New functions created to query for each item - calling of functions in importer.pp #10 (liamjohnsexton)
• add codeownerfiles #9 (MartyEwings)

Fixed

• https://github.com/MartyEwings/RSAN/issues/6 #7 (MartyEwings)

* This Changelog was automatically generated by github_changelog_generator