py-r10k-webhook

ultra lightweight and flexible webhook for Puppet code deployment with r10k

• 1. Motivation
• 2. Dependencies
• 3. Params
• 4. Example config.ini
• 5. Installation
• 6. Testing
• 7. Limitations

1. Motivation

There are several other r10k webhooks out there. But I could not find any hook, that is easy to debug, supports ipv6, supports SSL, has minimal dependencies and logs the output of r10k. So here comes the simple and lightweight py-r10k-webhook.

2. Dependencies

The webhook requires python3 and the following modules. Most of them should be part of your distro's python3 base package:

• os, sys, syslog, socket, ssl, base64, threading
• json
• configparser
• http.server

3. Params

• [main]

  • listen_addr mandatory. Supports ipv4 and ipv6
  • listen_port mandatory. Specify port to listen on

• [r10k]

  • r10k_environment_command optional. Defaults to r10k deploy environment "$R10KENV" -pv, $R10KENV is the environment from payload
  • r10k_module_command optional. Defaults to r10k deploy module "$R10KMODULE" -v, $R10KMODULE is the modulename.
    Note: If the name in payload is 'puppetlabs-apt', the $R10KMODULE is then 'apt'.
    Note: This setting may be useful for those who want to execute a r10k postrun. Currently r10k does no postrun after module deployment, see also this issue.

• [ssl]

  • ssl_key optional. Has to come with 'ssl_cert'. Hook is using HTTP, if the ssl section is absent.
  • ssl_cert optional. Has to come with 'ssl_key'. Hook is using HTTP, if the ssl section is absent.
  • ssl_ca optional, SSL socket is beeing used without ca, if left out

• [auth]

  • user optional. Has to come with 'pass'. Basic auth is not beeing used, if section auth is absent.
  • pass optional. Has to come with 'user'. Basic auth is not beeing used, if section auth is absent.

4. Example config.ini

[main]
listen_addr = ::   
listen_port = 8443

[r10k]
r10k_environment_command = r10k deploy environment "$R10KENV" -pv; /my/fancy/slack/plugin "$R10KENV"
r10k_module_command = r10k deploy module "$R10KMODULE" -v; /my/post/hook/script "$R10KMODULE"

[ssl]
ssl_cert = /etc/ssl/hook.pem
ssl_key = /etc/ssl/private/hook.pem
ssl_ca = /etc/ssl/ca.pem

[auth]
user = iamgood
pass = letmein

5. Installation

You just need the file py-r10k-webhook, your config.ini file (see below) and a systemd service file:

[Unit]
Description=py-r10k-webhook
Conflicts=shutdown.target
After=network.target network-online.target
Wants=network-online.target
StartLimitInterval=25
StartLimitBurst=3

[Service]
Type=simple
ExecStart=/path/to/py-r10k-webhook /path/to/py-r10k-webhook.conf
KillMode=process
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical.target

Note: This is an just-working exmaple unit file. For securing the service please refer to systemd-analyze security

One could configure all parts using puppet. For that you'll need the modules vcsrepo, inifile and systemd.

Configure Gitlab by navigating to control-repo / Settings / Webhooks and adding a Push-Hook with URL https://user:pass@host:port/api/v1/r10k/environment/. For adding the hook to a module use the URI https://user:pass@host:port/api/v1/r10k/module/

6. Testing

Test your configs by following the logs:

journalctl -fu py-r10k-webhook.service &

… and trigger environment deployment, e.g. production:

curl -X POST -H "Content-Type: application/json" -H "X-Gitlab-Event: Push Hook" -d '{ "ref": "production" }' https://user:pass@host:port/api/v1/r10k/environment/

… and trigger module deployment, e.g. my-puppetmodule:

curl -X POST -H "Content-Type: application/json" -H "X-Gitlab-Event: Push Hook" -d '{ "project": { "name": "my-puppetmodule" }}' https://user:pass@host:port/api/v1/r10k/module/

7. Limitations

• Currently, there's only gitlab supported. More information about gitlab hooks can be found here and here
• The hook can only be triggered by a push event. One may check the Merge Request settings (merge commit required)
• Logging facilitiy is currently hard-coded local0. One may implement more complex logging libraries for higher requirements.
• One could improve thread handling as there's currently no errorhandling on started threads.
• There are no automated Code Tests, but the hook is working stable on Ubuntu focal (20.04) and Python 3.8.5 😄