Tiny Puppet

Table of Contents

• Tiny Puppet
• Table of Contents
• Module description
  • Features
  • Use cases
• Setup
  • What tp affects
  • Getting started with tp
• Usage in Puppet code
  • Common uses
  • Installing packages - tp::install
  • Installation alternatives - tp::stdmod
  • Managing configurations - tp::conf
  • tp::conf file paths conventions
  • Managing directories - tp::dir
  • Managing repositories - tp::repo
  • Automated and easy testing - tp::test
  • Configuring tp resources via Hiera
• Updating tiny data and using alternative data sources
• Usage on the command line
• Reference
  • Classes
  • Defined types
  • Types
  • Functions
  • Tasks
• Prerequisites and limitations
• Additional info

Module description

Example42's tp (short for Tiny Puppet) module can manage every application (relevant tinydata is needed) on every Operating System (Linux flavours, Solaris, macOS, Windows) using different methods (native packages, packages from upstream repos, release tarballs, git source, docker container).

It permits allows this as code, via Puppet user defined types:

• Install applications' packages and manage their services (tp::install) using different methods
• Handle eventual relevant repos, allowing to choose between native distro repos or the ones from upstream developer (tp::repo)
• Manage applications configuration files (tp::conf)
• Manage whole directories (tp::dir), also from an SCM source.
• Add custom test and debug options (tp::test, tp::debug)
• Download app's source code (tp::source)

via the command line tool tp, that allows to:

• Install applications with single command (tp install <app>)
• Test if they are working correctly (tp test [app])
• Get information about them (tp info [app])
• Troubleshoot them (tp debug [app])
• See their version (tp version [app])
• Show their logs (tp log [app])
• Manage desktop configurations as code without a Puppet server (tp desktop)

via Bolt tasks, that permits to orchestrate the above operations on remote nodes.

Features

The main features of tp module are:

• Quick, easy to use, standard, coherent, powerful interface to applications installation and their config files management.
• Multiple installation options
• Out of the box and easily expandable support for most common Operating Systems.
• Modular data source design. Support for an easily growing set of applications.
• Smooth coexistence with any existing Puppet modules setup: it's up to the user to decide when to use tp and when to use a dedicated module.
• Application data stored in a configurable separated module (tinydata is the default source for applications data).
• Optional CLI command (tp) which can be used to install, test, get info, troubleshoot and query for logs any tp managed application.
• Optional Bolt tasks to perform the above actions on remote nodes.
• Usable both by total beginners and experienced sysadmins: interface is simple but allows powerful customisations

Use cases

Tiny Puppet can be considered a supplement or a replacement of standard component modules.

It's particularly useful when there are to manage packages, services and configuration files, for more complex and application-specific resources a dedicated module is probably preferable.

It can be used in the following cases:

• In local profiles, as an alternative to custom resources or dedicated modules, to ease the management of the relevant applications.
• Directly via Hiera, specifying in data hashes of tp resources to apply. Check Configuring tp resources via Hiera section for details.
• Even in component modules to leverage on the abstraction on Operating Systems to easily handle package and service names, configuration files paths and upstream repositories.

The intended users can be any of the following:

• Experienced sysadmins who know exactly how to configure their applications without digging into dedicated modules documentation or adapting to their logic.
• Absolute Puppet beginners who struggle to use and integrate public modules and need a quick and fast way to install and configure applications.
• Puppet experts who leverage on tp resources who want to optimise and limit the number of resources on nodes catalogs and of external modules to use.

To see real-world usage of tp defines give a look to:

• The profiles in the psick module where tp is used widely.
• Usage samples in hieradata.
• The psick_profile module which is contains more profiles for common applications.
• The tp-desktop repository, used to mabage desktop configurations as code using puppet apply (serverless).

Setup

TP can be installed as any other module:

• From the forge, via the puppet module command on the CLI:

    puppet module install example42-tp
  

• From the forge, adding to Puppetfile and entry like

    mod 'example42-tp', 'latest' # For latest version
    mod 'example42-tp', '3.8.0'  # For a specific version (recommended)
  

• From the forge, initializing a new Bolt project with this module:

    bolt project init --modules example42-tp
  

• From GitHub repository, cloning the module in your local $modulepath

    git clone https://github.com/example42/puppet-tp.git tp
  

Once tp module is added to the modulepath the (optional) tp command can be installed to a node in the following ways:

• Classifying the tp class for the node in Puppet manifests (or via other classification approaches):

    include tp
  

• Directly for the command line on the target node, as root:

    puppet tp setup
  

What tp affects

• Any application package which is possible to install with the OS native package manager.
• Eventually application specific package repository files or release packages (if relevant tinydata is present).
• Configuration files of any application, for which there's tinydata. Their content is up to the user.
• Full directories, whose source can also be an SCM repository.

Getting started with tp

Starting from version 3.8.0, a technology preview of tp 4 features is available by specifying the use_v4 parameter:

tp::use_v4: true

Here follows an example of tp resources used inside a custom profile where the content of a configuration file is based on a template with custom values.

class profile::openssh (
  String $server_template = 'profile/openssh/sshd_config.erb',
  String $client_template = 'profile/openssh/ssh_config.erb',
  Hash $options    = {},
) {

  # OpenSSH installation
  tp::install { 'openssh': }

  # Configuration of sshd_config server configuration file (main config file)
  tp::conf { 'openssh':
    template     => $server_template,
    options_hash => $options,
  }

  # Configuration of ssh_config client configuration file
  tp::conf { 'openssh::ssh_config':
    template     => $client_template,
    options_hash => $options,
  }
}

The above class, once included, will:

• Install the openssh package (name of the package adapted to the underlying OS).
• Manage the /etc/ssh/sshd_config and /etc/ssh/ssh_config files (eventually on different paths, according to the OS).
• Start the service openssh (name adapted to OS) taking care of dependencies and service restarts on files changes (restart behaviour can be customised).

In the defined templates key-values set in the $options hash can be accessed via <%= @options['key_name'] %> (example for an erb template), so, with hieradata as follows:

profile::openssh::options:
  StrictHostKeyChecking: yes

we can have in the used templates lines as follows:

StrictHostKeyChecking: <%= @options['StrictHostKeyChecking'] %>

Usage in Puppet code

The user defined types (or defines, or user defines) provided by tp module can be used in Puppet manifests to manage installation and configuration of applications. They can be straightforward and essential ( tp:: { 'Application name': }) but provide several parameters which can be used to customise and fine-tune the managed resources as needed.

Common uses

Install an application with default settings (package installed, service started)

tp::install { 'redis': }

Configure the application main configuration file a custom erb template which uses data from a custom $options_hash:

tp::conf { 'rsyslog':
  template     => 'site/rsyslog/rsyslog.conf.erb',
  options_hash => lookup('rsyslog::options_hash'),
}

Populate any custom directory from a Git repository (it requires Puppet Labs' vcsrepo module):

tp::dir { '/opt/apps/my_app': 
  source      => 'https://git.example.42/apps/my_app/',
  vcsrepo     => 'git',
}

Installing packages - tp::install

Some parameters are available to manage tp::install automation:

• upstream_repo Default: true. When true, uses the repo from the upstream developer, if defined in tinydata.

• auto_conf Default: true. If true and tinydata relevant is present a default configuration is provided (this could happen just when some basic configuration is needed to actually activate the service).

• auto_prereq Default: false. If true eventual package, tp::install or other dependencies are installed automatically. This is set to false by default in order to minimize duplicated resources risk, but might be required to set up specific applications correctly.

  tp::install { 'consul': upstream_repo => true, auto_conf => true, auto_prereq => false, }

Other parameters are available to manage integrations:

• cli_enable Default: true. Installs the tp command on the system and provides the data about the application used by tp log and tp test commands.
• puppi_enable Default: false. Installs Puppi and enables puppi integration.
• test_enable Default: false. If to enable automatic testing of the managed application.
• test_template Default: undef. If provided, the provided erb template is used to test the application (instead of default tests).
• options_hash Default: {}. An optional hash where to set variable to use in test_template.

Some specific params are to handle repos:

• repo Default: undef. Name of the upstrem_repo to use. This param allows, if tinydata is present, to customise the repo to use (for example to manage the installation of specific versions of an application).
• repo_exec_environment Default []. An array passed to the environment argument of exec types used inside tp::repo define, declared within tp::install when a repo is configured. Can be useful when trying to use tp::repo from behind a proxy.

These parameters allow to skip management of packages or services:

• manage_package Default: true. When false, tp::install doesn't handle packages, even when there's a package_name defined in tinydata.
• manage_service Default: true. When false, tp::install doesn't handle services, even when there's a service_name defined in tinydata.

Some parameters allow to configure tp::conf and tp::dir resources directly from tp::install (inheriting the same settings and options):

• conf_hash. Default: { }. A hash of tp::conf resources to create. These resources will refer to the same application specified in the tp::install $title and inherits the settings ensure, settings_hash, options_hash and data_module
• dir_hash. Default: { }. A hash of tp::dir resources to create, as for the conf one.

Parameters are also available to customise the tiny data settings which affect package and service names, repos settings, file paths and so on. The params are common to all the tp defines, check Updating tiny data and using alternative data sources section for details.

• settings_hash Default: {}. An optional hash which can be used to override tinydata settings.
• data_module Default: 'tinydata'. The name of the module to use to get tp data for the managed application.

An example with a custom test for the rabbitmq service:

tp::install { 'rabbitmq':
  cli_enable    => true,
  test_enable   => true,
  test_template => 'profile/rabbitmb/tp_test.erb',
  options_hash  => { 'server' => "rabbitmq.${::domain}" }
}

It's possible to specify the version of the package to install (the provided version must be available in the configured repos):

tp::install { 'postfix':
  ensure => '2.10.1-9',
}

To uninstall an application, there are two alternatives:

tp::uninstall { 'redis': }
tp::install { 'redis': ensure => absent }

Installation alternatives - tp::stdmod

To handle packages installations and configuration files, there's also the tp::stdmod define to manage an application using stdmod compliant parameters.

Note that tp::stdmod is alternative to tp::install (both of them manage packages and services) and may be complementary to tp::conf (you can configure files with both).

tp::stdmod { 'redis':
  config_file_template => 'site/redis/redis.conf',
}

If you wonder what's better, use tp::install + tp::conf rather than tp::stdmod.

Managing configurations - tp::conf

The tp::conf define is a wrapper over a file resource which makes it easy and fast to manage configuration files for an application, handling the correct permissions, paths and owners for the underlying OS. Be aware anyway that the contents of the managed files are entirely up to you: Tiny Puppet does not have any awareness of the configuration options available for the managed applications.

If as the title is passed just the name of the application, Tiny Puppet tries to configure its main configuration file. There are various ways to manage other configuration files related to the application as detailed in the section tp::conf file paths conventions.

It's possible to manage files with different methods, for example directly providing its content:

tp::conf { 'redis':
  content => 'my content is king',
}

or providing a custom template with custom options:

tp::conf { 'openssh::ssh_config':
  template     => 'profile/openssh/ssh_config.erb',
  options_hash => {
    UsePAM        => 'yes',
    X11Forwarding => 'no',
  } 
}

Via the template parameter with can both specify files .erb suffix (used as content => template($template)) or with .epp suffix (used as content => epp($template)). If not .erb or .epp suffix is present in the template value, then it's treates as and erb (content => template($template)).

In the profile/templates/openssh/ssh_config.erb template you will have the contents you want and use the above options with something like (note you can use both the @options and the @options_hash variable):

[...]
UsePAM <%= @options['UsePAM'] %>
X11Forwarding <%= @options['X11Forwarding'] %>
[...]

Alternatively a custom epp template with Puppet code instead of Ruby (used as content => epp($epp)) directly with the epp parameter:

tp::conf { 'redis:
  epp   => 'site/redis/redis.conf.epp',
}

also it's possible to provide the source to use, instead of managing it with the content argument:

tp::conf { 'redis':
  source      => [ "puppet:///modules/site/redis/redis.conf-${hostname}" ,
                   'puppet:///modules/site/redis/redis.conf' ] ,
}

For applications for which it exists the setting 'config_file_format' you can just pass the hash of options_hash of settings to configure and tp::conf creates a valid configuration file for the application:

tp::conf { 'filebeat':
  options_hash => {
    filebeat.modules => ['module: system']
    syslog => {
      enabled   => true,
      var.paths => ["/var/log/syslog*","/var/log/messages"],
    }
  }
}

This example makes much more sense if based on Hiera data (see Configuring tp resources via Hiera section for details):

tp::conf_hash:
  filebeat:
    options_hash:
      filebeat.modules:
      - module: system
      syslog:
        enabled: true
        var.paths:
          - "/var/log/syslog*"
          - "/var/log/messages"

By default, configuration files managed by tp::conf automatically notify the service(s) and require the package(s) installed via tp::install. If you use tp::conf without a relevant tp::install define and have dependency cycle problems or references to non existing resources, you can disable these automatic relationships:

tp::conf { 'bind':
  config_file_notify  => false,
  config_file_require => false,
}

You can also set custom resource references to point to actual resources you declare in your manifests:

tp::conf { 'bind':
  config_file_notify  => 'Service[bind9]',
  config_file_require => 'Package[bind9-server]',
}

Tiny Puppet even validates the syntax of the managed configuration files before applying them, if the setting 'validate_cmd' is present in Tiny Data. To disable this validation, which prevents Puppet from changing a file if its syntax is wrong, set validate_syntax parameter to false.

tp::conf file paths conventions

Tp:conf has some conventions on the actual configuration file managed.

By default, if you just specify the application name, the file managed is the "main" configuration file of that application (in case this is not evident or might be questionable, check the config_file_path value in the tinydata files for the used application).

# This manages /etc/ssh/sshd_config
tp::conf { 'openssh':
  [...]
}

If you specify a file name after the application name in the title, separated by ::, and you don't specify any alternative base_file, then that file is placed in the "base" configuration dir (config_dir_path in tinydata):

# This manages /etc/ssh/ssh_config
tp::conf { 'openssh::ssh_config':
  [...]
}

If you specify the parameter base_file then the path is the one of the specified base_file and the title does not provide any information about the managed file path (it still needs the relevant app in the first part, before ::, and it needs to be unique across the catalog). For example, if base_file => 'init' the path used is the value of the init_file_path key in the relevant tinydata.

# This manages /etc/default/puppetserver on Debian or /etc/sysconfig/puppetserver on RedHat
tp::conf { 'puppetserver::init':
  base_file => 'init',
  [...]
}

If you explicitly set a path, that path is used and the title is ignored (be sure, anyway, to refer to a supported application and is not duplicated in your catalog):

# This manages /usr/local/bin/openssh_check
tp::conf { 'openssh::ssh_check':
  path => '/usr/local/bin/openssh_check',
  [...]
}

Managing directories - tp::dir

Manage a whole configuration directory:

tp::dir { 'redis':
  source      => 'puppet:///modules/site/redis/',
}

Manage a specific directory type. Currently defined directories types are:

• config: The application main configuration directory (Default value).
• conf: A directory where you can place single configuration files (typically called ./conf.d ).
• data: Directory where application data resides.
• log: Dedicated directory for logs, if present.

Note that some of these directory types might not be defined for every application.

tp::dir { 'apache':
  base_dir => 'data',
  source   => 'puppet:///modules/site/apache/default_site',
}

Clone a whole configuration directory from a Git repository (it requires Puppet Labs' vcsrepo module):

tp::dir { 'redis':
  source      => 'https://git.example.42/puppet/redis/conf/',
  vcsrepo     => 'git',
}

Populate any custom directory from a Subversion repository (it requires Puppet Labs' vcsrepo module):

tp::dir { 'my_app': # The title is irrilevant, when path argument is used 
  path        => '/opt/apps/my_app',
  source      => 'https://svn.example.42/apps/my_app/',
  vcsrepo     => 'svn',
}

Provide a data directory (the default DocumentRoot, for apache) from a Git repository (it requires Puppet Labs' vcsrepo module) :

tp::dir { 'apache':
  # base_dir is a tag that defines the type of directory for the specified application.
  # Default: config. Other possible dir types: 'data', 'log', 'confd', 'lib'
  # or any other name defined in the application data with a format like: ${base_dir}_dir_path
  base_dir    => 'data' 
  source      => 'https://git.example.42/apps/my_app/',
  vcsrepo     => 'git',
}

Continuous deployment the tiny way: automatically deploy the latest version of an app from a git repo whenever Puppet runs:

tp::dir { 'my_app':
  ensure  => latest,
  path    => '/opt/apps/my_app',
  source  => 'https://git.example.42/apps/my_app/',
  vcsrepo => 'git',
}

Managing repositories - tp::repo

Currently, Tiny Puppet supports applications' installation only via the OS native packaging system or Chocolatey on Windows and HomeBrew on MacOS. In order to cope with software which may not be provided by default on an OS, TP provides the tp::repo define that manages YUM and APT repositories for RedHat and Debian based Linux distributions.

The data about a repository is managed like all the other data of Tiny Puppet. Find here an example for managing Apt repositories and here one for Yum ones.

Generally, you don't have to use the tp::repo define directly, as, when the repository data is present, it's automatically added from the tp::install one.

When it's present the relevant data for an application, it's possible to install it using different alternative repos. For example you can use this synatx to install the repo for the Elastic stack version 6.x:

tp::install { 'elastic_repo':
  repo => '6.x',
}

In some cases, where for the given application name there are no packages, the following commands have exactly the same effect:

tp::install { 'epel': }  # Installs Epel repository on RedHat derivatives. Does nothing on other OS.
tp::repo { 'epel': }     # Same effect of tp::install since no application package (other than the release one) is actually installed

If, for whatever reason, you don't want to automatically manage a repository for an application, you can set to false the auto_repo parameter, and, eventually you can manage the repository in a custom dependency class:

tp::install { 'elasticsearch':
  auto_repo => false,
}

Tinydata has information about various useful repos, both general or application/vendor specific. They are a tp::install away, all the following ones add repos for RedHat systems and derivatives:

• tp::install {'epel': }. Configures Epel repo on RedHat and derivatives
• tp::install {'rpmfusion-free': } - tp::install {'rpmfusion-nonfree': }. Configure RPM Fusion free and nonfree repo
• tp::install {'ius': }. Configures IUS repo
• tp::install {'remi': }. Configures Remi Repository
• tp::install {'elrepo': }. Configures ELRepo
• tp::install {'nux': }. Configures Nux DexTop repo
• tp::install {'ulyaoth': }. Configures Ulyaoth repo

There is also Tiny Data for some vendors repos, and sometimes they are directly in the relevant application data, sometimes in a dedicated namespace:

• tp::install {'elastic_repo': }. Configures ELastic repo on RedHat and Debian derivatives
• tp::install {'hashicorp_repo': }. Configures Hashicorp repo on RedHat, Amazon, Fedora and Debian derivatives

Automated and easy testing - tp::test

The tp module provides the following functionality for writing easy and quick checks:

• The tp::test define, to add custom scripts with tests related to apps managed by tp or just anything else worth testing
• The test_enable argument of the tp::install define which automatically creates tests (usually package presence and service status) of the app installed via tp
• The tp test command argument which allows, from the CLI, to run all the tests created by the tp::test defines and the ones automatically added by tp::install with ``test_enable``` set to true
• The tp::test task, which delivers site-wide, uick and easy tests on different nodes.

To automatically add testing for an application installed via tp use the follwoing parameters:

tp::install { 'redis':
  test_enable => true,  # Default: false
  cli_enable  => true,  # Default: false. This also installs the tp command on the system
}

If you want these functionality enabled by default, in your control-repo's main manifests/site.pp you can add the following resource defaults:

Tp::Install {
  test_enable => true,
  cli_enable  => true,
}

To add a custom test for an application you can either specify the template to use for the test script of that application, in tp::install:

tp::install { 'rabbitmq':
  test_enable   => true,
  cli_enable    => true,
  test_template => 'profile/rabbimq/tptest.erb',
} 

Or you can use a specific tp::test define:

tp::test { 'rabbitmq':
  template => 'profile/rabbimq/tptest.erb',
  options_hash => {
    port => '11111',
    host => 'localhost',
  },
}

All the keys set via the $options_hash parameter can be used in the erb template with sopmething like:

port_to_check=<%= @options_hash['port'] >

The tp::test define has the following parameters to manage the content of the test script (placed under /etc/tp/test/$title):

• template, to specify an erb template. Example: template => 'profile/rabbimq/tptest.erb' (erb template located in $MODULEPATH/profile/templates/rabbimq/tptest.erb)
• epp, to specify an epp template. Example: template => 'profile/rabbimq/tptest.epp' (epp template located in $MODULEPATH/profile/templates/rabbimq/tptest.epp)
• template, to specify the full content . Example: content => $my_script_content (content of the $my_script_content variable set somewhere in Puppet code)
• source, to specify the source file an erb template. Example: source => 'puppet:///modules/profile/rabbimq/tptest' (static source file located in $MODULEPATH/profile/files/rabbimq/tptest).

Starting from tp version 3.1.0 it's also possible to add any custom test script also unrelated to a specific application. You can you these to check general system status of some web application status or whatever it may make sense to test. You can legerage on the tp test command or the tp::test define to automate infrastructure testing on your CI/CD pipelines.

Examples:

tp::test { 'system_health':
  source => 'puppet:///modules/profile/base/system_health',
}

tp::test { 'my_web_app':
  source => 'puppet:///modules/profile/my_web_app/test',
}

The scripts can be in any language, they just need to have an exit code 0 in case of success, and a different exit code in case of failure.

The tp test command and the tp::test task will exit with 0 if all the test have been successfull, and exit with 1 if any of the test have returned an error.

Configuring tp resources via Hiera

The main and unique class of this module, tp, installs the tp CLI command (set tp::cli_enable to false to avoid that) and offers parameters which allow to configure via Hiera what tp resources to manage.

For each of these parameters (example: install_hash) it's possible to set on hiera:

• The hash or resources to manage (tp::*_hash).
• The merge lookup method to use for the lookup. Default: first (tp::*_hash_merge_behaviour).
• A hash of default options for that define's Hash of resources (tp::*_defaults).

Where * is any of install, conf, dir, puppi, stdmod, concat and repo.

An example to install kubernetes and sysdig, adding the management of the required dependencies:

tp::install_hash:
  kubernetes:
    auto_prereq: true
  sysdig:
    auto_prereq: true

This is an example of tp::dir hash (with the ensure latest for a git repo for "Tiny Continuous Deployment"):

tp::dir_hash:
  apache::openskills.info:
    vcsrepo: git
    source: git@git.alvagante.com:web/openskills.info.git
    path: /var/www/html/openskills.info
  apache::abnormalia.com:
    ensure: latest
    vcsrepo: git
    source: git@git.alvagante.org:web/abnormalia.com.git
    path: /var/www/html/abnormalia.com

There are also analogue parameters to handle resources Hashes based on the clients' OS Family for tp::install (tp::osfamily_install_hash, tp::osfamily_install_hash_merge_behaviour, tp::osfamily_install_defaults) and tp::conf (tp::osfamily_conf_hash, tp::osfamily_conf_hash_merge_behaviour, tp::osfamily_conf_defaults)

Here is an example of OS based install_hash (note the usage of Yaml merge keys to avoid data duplication for RedHat and Debian families):

linux_tp_install: &linux_tp_install
  filebeat:
    auto_prereq: true
  metricbeat: {}
  auditbeat: {}
  heartbeat-elastic:
    ensure: absent

tp::osfamily_install_hash:
  RedHat:
    <<: *linux_tp_install
  Debian:
    <<: *linux_tp_install
  windows:
    chocolateygui: {}
    docker-desktop: {}
    powertoys: {}
    MobaXTerm: {}
    Sysinternals: {}

Updating tiny data and using alternative data sources

By default Tiny Puppet uses the tinydata module to retrieve data for different applications, but it's possible to override its settings in two ways:

• Via the settings_hash parameter
• Via the data_module parameter

The settings_hash parameter, present in all tp defines, allows the override of specific settings coming from tiny data.

The names of the available settings are defined in the tp::settings data type. Usage can be as follows:

tp::install { 'redis':
  settings_hash => {
    'package_name'     => 'my_redis',
    'config_file_path' => '/opt/etc/redis',
  },
}

The data_module parameter allows to use a totally different module for tinydata:

tp::install { 'apache':
  data_module => 'my_data', # Default: tinydata
}

In this custom data module, we have to reproduce the structure of tinydata to make it work with tp.

If we want to use our own data module for all our applications, we might prefer to set the following resource defaults in our main manifest (manifest/site.pp, typically):

Tp::Install {
  data_module  => 'my_data',
}
Tp::Conf {
  data_module  => 'my_data',
}
Tp::Dir {
  data_module  => 'my_data',
}

Starting from version 2.3.0 (with tinydata version > 0.3.0) tp can even install applications for which there's actually no tinydata defined. In this case just the omonimous package is installed and a warning about missing tinydata is shown. In these cases other defines like tp::conf don't work.

Usage on the command line

Tiny Puppet adds the tp command to Puppet. Just have it in your modulepath and install the tp command with:

sudo puppet module install example42-tp
sudo puppet tp setup

With the tp command you can install on the local OS the given application, taking care of naming differences, additional repos or prerequisites.

tp install <application>    # Install an application
tp uninstall <application>  # Uninstall an application
tp test [application]       # Test one or all the applications
tp log [application]        # Tail the logs of one or all applications
tp info [application]       # Show info on one or all applications
tp debug [application]      # Troubleshoot one or all applications
tp version [application]    # Show version of one or all applications
tp source <application>     # Clone the source of an applications
tp version [application]    # Show version of one or all applications

tp desktop                  # Show tp desktop options
tp desktop init             # Initialise a new tp desktop repostiory
tp desktop list             # List the available desktops
tp desktop show <desktop>   # Show the details of a desktop
tp desktop prevew <desktop> # Preview what desktop apply would do
tp desktop apply <desktop>  # Apply a desktop configuration

Check this to see tp cli in action.

Reference

The tp module provides the following resources.

Classes

• tp Offers entry points for data-driven management of tp resources, and the possibility to install the tp command

Defined types

• tp::install. It installs an application and starts its service, by default.
• tp::conf. It allows to manage configuration files.
• tp::dir. It manages the content of directories.
• tp::stdmod. It manages the installation of an application using StdMod compliant parameters. LEGACY
• tp::test. It allows quick and easy (acceptance) testing of an application.
• tp::repo. It manages extra repositories for the supported applications.
• tp::puppi. Puppi integration (Don't worry, fully optional). LEGACY

Types

• tp::settings, validates all the possible setting for tinydata

Functions

• tp::content, manages content for files based on supplied (erb) template, epp, and content
• tp::ensure2bool, converts ensure values to boolean
• tp::ensure2dir, converts ensure values to ensure values to be used for directories
• tp::ensure2file, converts ensure values to ensure values to be used for files
• tp::ensure2service, converts ensure values to ensure and enable values to be used for services
• tp::install, wrapper around the tp::install define, it tries to avoid eventual duplicated resources issues
• tp::is_something, returns true if input of any type exists and is not empty
• tp::fail, handles errors or unexpected conditions in the desired way (via a notify resource, via server side notification functions, or just silently ignoring)
• tp::create_everything, runs create_resources on the specified hash of resources types
• tp::url_replace, gets as input an URL with variables are replaces them with actual values

Tasks

• tp::test, runs a tp test command on a system to check the status of tp installed applications

Refer to in-code documentation for full reference.

Check Puppetmodule.info for the online version.

Prerequisites and limitations

Starting from version 3 Tiny Puppet requires Hiera data in module, available from Puppet 4.9.

Version 2.x of Tiny Puppet is compatible with Puppet 4.4 or later and PE 2016.1.1 or later.

Version 1.x is compatible also with Puppet 3, using the 3.x compatible defines (with the 3 suffix, like tp::install3).

Version 0.x of Tiny Puppet is compatible by default with Puppet 3 (tp::install) and have Puppet 4 / future parser version, with the 4 suffix, like tp::install4).

If tp doesn't correctly install a specific application on the OS you want, please TELL US.

It's very easy and quick to add new apps or support for a new OS in tinydata.

Currently most of the applications are supported on RedHat and Debian derivatives Linux distributions, but as long as you provide a valid installable package name, tp can install any application given in the title, even if there's no specific Tinydata for it.

Tiny Puppet requires these Puppet modules:

• The tinydata module

• Puppet Labs' stdlib module.

In order to work on some OS you need some additional modules and software:

• On Windows you need Chocolatey and puppetlabs-chocolatey module with chocolatey package provider.
• On Mac OS you need Home Brew and thekevjames-homebrew or equivalent module with homebrew package provider.

If you use the relevant defines, other dependencies are needed:

• Define tp::concat requires puppetlabs-concat module.
• Define tp::dir , when used with the vcsrepo argument, requires puppetlabs-vcsrepo module.
• Define tp::puppi requires example42-puppi module.

Additional info

You can experiment and play with Tiny Puppet and see a lot of usage examples on Example42's PSICK control-repo and the psick module.

Tiny Puppet has a website.

The following blog posts, newest first, have been written on Tiny Puppet, older ones might contain not updated information:

• Managing extra repositories with Tiny Puppet
• Five Years of Tiny Puppet
• Request for Tiny Data - Part 4 - Defaults and final call
• Request for Tiny Data - Part 3 - Tiny. fancy and powerful features
• Request for Tiny Data - Part 2 - Tiny data exposed
• Request for Tiny Data - Part 1 - Tiny Puppet (tp)
• Custom applications management using Tiny Puppet
• tp install anything (anywhere),and configure
• A few steps to Tiny Puppet on the command line
• Tiny Puppet 1.0
• Preparing for Tiny Puppet 1.0
• Introducing Tiny Puppet

CHANGELOG

3.10.1

• Changed CI containers used
• Unit tests for Puppet 7 and 8
• Lints and fix on undefined vars
• Updated tp::create_dir

3.10.0

• Added support for $MAJVERSION variable in tinydata
• Added support for xz release files
• Refactorings in install type management:
• • support for root and normal users
  • install_type file renamed to release
  • settings are computed in tp::install and used in tp::install::* defines
• get_version and url_replace functions accept an addtional version type paramter
• Widened support for variables in tinydata
• Removed legacy facts for Puppet 8 compatibility

3.9.1

• Fixed tp debug cli command
• Fixed tp test command on apps without packages
• Fixed possible resource duplicstion when multiple app with exec_postinstall setting are present in the catalog
• Fixed repo keys managmeent when apt_safe_trusted_key is true
• Updated metadata.json to reflect factual compatibility with only Puppet 6 or later
• Updated metadata.json to have puppetlabs/vcsrepo as a dependency
• Updated sample tinydata and OS tests in unit tests
• Fixed tp uninstall command to remove also tp data files

3.9.0

• tp::install::* defines simplified and aligned to semifinal v4 tinydata structure
• Added function tp::get_version
• Added function tp::title_replace
• Changed lookup method to deep_merge to all tp_lookup function calls
• Added define tp::copy_file
• Added define tp::service
• Added define tp::setup
• Added data types to match v4 tinydata structures
• Updated tp::dir to v4
• Updated tp::file to v4

3.8.0

• Added tp::use_v4 setting to use Puppet 4 compatible code
• Added v4 code for tp, tp::install
• Added tp::cli class to manage tp command in v4
• Added tp::install::package to manage apps from packages
• Added tp::install::file to download apps from release urls
• Added tp::fail function and data type and on_missing_data setting
• Added tp::url_replace and tp::create_everything functions
• Separated all old code, files and templaes from v4 specific
• Added tp::install::source to download apps from source repos
• Added tp::install::image to download and install app container image
• Params tp::tp_dir and tp::tp_path have been replaced by tp::tp_params and derived from identify fact
• Added v4 entrypoints for Hiera data driven tp resources: tp::s and tp::osfamily_resources
• Deprecated the corresponding tp::hash and tp::osfamily_hash

3.7.0

• tp desktop noapply command renamed to tp desktop preview
• Added /usr/sbin/tp symbolic link to avoid errors due to incorrect PATH
• Fixed tp::repo with setting repo_file_url
• Fixed tp test with packages using pip3
• Do not clone locally tp module when using tp desktop command
• Added new settings: website_url, winget_package_name, choco_package_name, docker_image

3.6.2

• Added tp debug command, define and task. Added debug_commands tinydata key.
• Added tp desktop noapply command
• Better management of tp global files when user is not privileged
• Added support for scope in tp::conf and tp::dir
• Added relevant user_ tinydata settings
• Quote shellvars script
• Fixed prerequisites dependencies when package_name is absent
• Added tp source command and task

3.6.1

• Fixed tp desktop show command
• Show output of tp desktop apply command

3.6.0

• Added shellvars data to shell scripts using tiny data.
• Fixed tp info output
• First prototype of tp desktop
• Added define tp::source

3.5.3

• Fix tp service test within docker containers

3.5.2

• Fixed idempotency in keys management when tp::apt_safe_trusted_key is true

3.5.1

• From Debian 11 and Ubuntu 22.04 upwards apt-key is no more used by default to manage apt keys. Keys are placed under /etc/apt/keyrings and trusted in the relevant source list files. If you upgrade tp and have Debian 11 and Ubuntu 22.04 servers where keys are already present, tp updates the trusted entry in the source list file but does not move existing keys from /etc/apt/trusted.gpg.d to /etc/apt/keyrings. You have to do it manually, naming the keyring gpg file as referenced in the source list. If you want to keep on using deprecated apt-key method to install keys also in these OS versions set on Hiera: tp::apt_safe_trusted_key: false
• Added ensure parameter to tp class
• Added support for Debian 11, SLES 15, Ubuntu 22.04
• Fixed tinydata module path search when not using the official Puppet agent package
• Added options to suppress annoying warnings or full output in tp install and uninstall commands
• Fixed ruby interpreter path in tp command when not using the official Puppet agent package

3.5.0

• Added ability to install from git_source in tp::install
• Added git_use, git_destination and git_source settings
• Added version_command setting and tp version subcommand
• Added tp::version task
• Fixed tp install command auto_prereq

3.4.0

• Added tp info define, task and cli command
• Added init_system setting
• tp test output change
• Added info_commands setting
• Added yumrepo_params setting

3.3.0

• Updated to latest pdk template
• Added GitHub workflow for Merge Request
• Massive linting based on Voxpupuli extra lint checks
• Added brew_tap setting

3.2.0

• Avoid usage of legacy tp_content function
• Allow to specify an .epp file for tempalte param of tp::conf
• Fix .epp template management in tp::conf
• Correctly identify repo check in tp test command when repo file path is custom
• Fix usage of custom templates when config_file_type is set in tinydata
• Correctly handle $options in templates used by tp::conf
• Better handle errors in tp command when tp module is not installed locally

3.1.0

• Added support for custom tp tests not related to apps
• Better handling of errors in tp command when tp module is missing

3.0.0

• Added data in module. Supported only Puppet version 4.9 and later.

2.5.1

• Added support for tinydata config_file_format setting
• Added tp::osfamily_install_hash and tp::osfamily_conf_hash parameters
• Allow to set defaults and lookup method for all _hash parameters in tp class
• Added tinydata extra_prerequisites and extra_postinstall params
• tp_prerequisites can can a String, Array of Hash of tp installs

2.5.0

• Added tinydata params git_source and git_destination to install apps from git source
• Added param repo_file_url to install a repo directly from http url (Note: if using https, the repo webserver certificate must be valid and accepted by locally installed CAs certs).
• Added repo_description tinydata setting
• Added support for puppet gem packages in tp test
• Improved support for Windows
• tp test now shows also tp managed repos

2.4.3

• Added repo_description setting

2.4.2

• Ensure we find tp command in task tp::test
• Propagate data_module var to tp defines used in tp::install
• pdk convert

2.4.1

• Fix for tp::install when upstream_repo is missing in tinydata

2.4.0

• Added upstream_repo option

2.3.5

• Explicitly close open files in tp_lookup
• Add purge_dirs argument to tp class

2.3.4

• Added repo_exec_environment argument to tp::install

2.3.3

• Updated README

2.3.2

• Approved status request MODULES-5811
• Skip danger in travis CI
• any variables can be accepted for ensure of dir (#59)

2.3.1

• Allow spaces in key for apt-key checks in tp::repo (#57)

2.3.0

• Do not fail on missing tinydata, try to install homonimous package

2.2.1

• Added support for tinydata settings repo_name and repo_filename in tp::repo
• Added support for tinydata settings config_file_params and config_dir_params
• tp from command line Install cli integration by default

2.2.0

• Added support for tinydata setting repo_package_params in tp::repo
• tp::repo just installs the release package if tinydata exists
• Install via wget and dkpg release package from repo_package_url On Debian in tp::repo
• Added support for package_params and service_params in tp::install

2.1.1

• Add support for trust_server_cert and any extra option on tp::dir
• Install_hash should support arrays (@logicminds)

2.1.0

• Added validate_syntax option to tp::conf

2.0.4

• Added task tp::test

2.0.1

• Added more spec tests
• Minor fixes

2.0.0

• Removed Puppet3 defines
• Class tp: Removed params: packages, services, files
• Define tp::install: Params auto_prerequisites renamed to auto_prereq
• More Puppet 4 language constructs
• Removed pick_undef and tp_pick functions. Use stdlib pick_default
• Removed tp::concat define
• Main tp class refactored to use params pattern instead of data in modules for backwards compatibility
• Refactored spec tests. Now is possible to test any tp define on any os on any app
• Added tests for tp::test, tp::uninstall, tp::stdmod