Forge Home

supervisor_provider

Adds a provider for Supervisor to the built in service resource type

18,309 downloads

13,521 latest version

4.3 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.3 (latest)
  • 0.1.2
  • 0.1.1
  • 0.1.0
released Jun 1st 2017
This version is compatible with:
  • Puppet Enterprise 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >=2.7.20 <5.0.0
  • , , , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'dskad-supervisor_provider', '0.1.3'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add dskad-supervisor_provider
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install dskad-supervisor_provider --version 0.1.3

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

dskad/supervisor_provider — version 0.1.3 Jun 1st 2017

supervisor_provider

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with supervisor_provider
  1. Usage - Configuration options and additional functionality
  1. Reference - An under-the-hood peek at what the module is doing and how
  2. Limitations - OS compatibility, etc.
  3. Development - Guide for contributing to the module

Overview

The supervisor_provider module adds a provider to the service resource type to control the Supervisor process manager.

Module Description

This module enables management of processes that are controlled by Supervisor using the Puppet service resource type.

This is especially useful when using Puppet inside Docker containers when a Puppet module expects to manage a service (typically sysV/BSD init, upstart, systemd, etc), but can't find a suitable init system in the container. Supervisord provides lightweight init-like process management that can start/stop/restart services, restart crashed services, reap zombie processes and handle signals from the Docker daemon.

This provider supports

  • Start/Stop
  • Enable/Disable
  • Restart
  • Status

Setup

What supervisor_provider affects

  • Adds a provider for Supervisor to the built-in service resource type

Setup Requirements

  • Supervisor needs to be installed and configured before using this module. (See ajcrowe-supervisord for a well maintained module for Supervisor mamangement)

  • If you are managing Supervisor configuration with Puppet, ensure the configuration happens before attempting to manage processes that are controlled by Supervisor.

  • This provider expects the Supervisor binaries to be in the system path.

  • Pluginsync should be enabled in a Master/Agent environment. This is the default for Puppet versions after 3.0.0.

Beginning with supervisor_provider

Once Supervisor is installed and supervisorctl is in your path, make sure a service is configured, typically by placing an .ini file in /etc/supervisor.d for each service. (Location may differ by platform) Here is an example configuration to manage the Puppet agent daemon.

[program:puppet]
command=/opt/puppetlabs/puppet/bin/puppet agent --no-daemonize --logdest console
stdout_logfile=/var/log/puppetlabs/puppet/agent.log
redirect_stderr=true
autostart=false

Use the Puppet Service resource type to modify Supervisor services. In most cases, Puppet should detect that Supervisor is being used and choose the correct provider. (see Multiple Service Providers below)

service {'puppet':
  ensure => 'stopped',
  enable => false,
  hasrestart  => true,
}

Usage

Service Refreshing

To allow this provider to use Supervisor's native restart command when responding to refresh events (via notify, subsctibe or the ~> arrow), Set the hasrestart attribute to true. If this is omitted, the service resource will use the stop and start commands to restart the service.

Multiple Service providers

There is likely going to be an existing service provider running on the system where Supervisor is installed. Puppet will detect both Supervisor and the system's init provider. (e.g. Systemd, SysV init, etc) Puppet may not correctly identify which provider to use, especially in the case where the service name exists in both places. To ensure the Supervisor provider is used, use the provider attribute to force the choice.

service {'myservice':
  ensure    => 'running',
  enable    => true,
  hasrestart  => true,
  provider  => 'supervisor',
}

Special Note On Disabled Services

Supervisord does not allow a running service to be disabled or a disabled service to start. This provider will stop a running service before disabling it and enable a disabled service before running it.

For a disabled service

# Initial State
service {'myservice':
  ensure => 'stopped',
  enable => false,
  hasrestart  => true,
}

After starting service: puppet resource service myservice ensure='running'

# New Running State
service {'myservice':
  ensure => 'running',
  enable => true,
  hasrestart  => true,
}

For a running service

# Initial State
service {'myservice':
  ensure => 'running',
  enable => true,
  hasrestart  => true,
}

After disabling service: puppet resource service myservice enable='false'

# New Disabled State
service {'myservice':
  ensure => 'stopped',
  enable => false,
  hasrestart  => true,
}

Reference

Manages supervisord services using supervisorctl.

  • Required binaries: supervisorctl, supervisord.
  • Supported features: enableable, refreshable.
  • Set hasrestart to true to use Supervisor's built-in restart command. If omitted or set to false, puppet will use Supervisor's start and stop commands.
  • If using a puppet version prior to 2.7.0, set the hasstatus attribute to true to use the Supervisor status command to get service states.
service {'myservice':
  ensure      => 'running',
  enable      => true,
  hasrestart  => true,

  # only needed for puppet agent < 2.7.0
  # hasstatus => true,
}

Limitations

  • This module has currently been tested on CentOS 7, but should work on any Unix like platform where Supervisor is supported.

  • This module only adds support for Supervisor to the service resource type. It does not handle configuration or installation of Supervisor itself or the creation of services in Supervisor.

  • When used in conjunction with another module to manage Supervisor configuration, use Puppet version 2.7.8 or greater to ensure best compatibility. This version introduced lazy evaluation for provider suitability, allowing Supervisord configuration and process management with Supervisor to happen in the same Puppet run. (i.e. Use this provider to start a service in the same run that Supervisor is installed and configured)

Development

If you see any problems or have any suggestions, submit an issue or pull request!