Reference - Plugins

Minimum PPA Version: 2.6.0

The plugins dictionary is optional in the root of the Playbook.

Best Practice

While this is an optional keyword, we recommend using it as a standard practice.

Summary

PPA Playbooks use plugin actions to automate operations on external systems.

Each installed plugin has a version, & functionality changes between these versions.

Unless instructed otherwise, PPA will use the latest plugin versions when you build a task.

You can 'lock' the task's plugin versions in the Playbook to override this behaviour.

This page will explain:

  • Why locking a task's plugin versions is a great idea
  • How to lock these plugin versions in a Playbook

Plugin Versions & Compatibility

Versioning Scheme

Plugin version numbers follow a major.minor.patch format.

Update Changes Backward Compatible
Major Significant functionality & bug fixes No
Minor Small functionality & bug fixes Yes
Patch Documentation only Yes

Compatibility Issues

Minor & patch version updates are all backward compatible.

Building a task with a new minor or patch update is perfectly safe.

However building a task with a new major version can cause issues.

A task written against a version 3.x.x plugin is not guaranteed to work with version 4.x.x.

Locking Plugin Versions

Avoid compatibility issues by locking your task to major plugin versions.

1 - Find Plugin Versions

By default PPA builds tasks using latest installed plugin versions.

This makes it really easy to find the versions to lock your new task to.

When a new task is tested & ready to deploy:

  • Make a note of the plugins you're using in the Playbook
  • Navigate to the PPA Plugins page
  • Note down the latest version of each plugin used by your Playbook

These version numbers are what you'll lock the task to in the Playbook.

2 - Update Playbook

As an example, let's assume your Playbook uses the following plugins & versions:

  • aws: 2.0.1
  • hashicorp_vault: 4.0.0
  • active_directory: 1.3.2

To avoid compatibility issues, lock the major versions in the Playbook:

Pinned Plugin Versions

1
2
3
4
plugins:
  aws: ~2
  hashicorp_vault: ~4
  active_directory: ~1

Lock Format

Putting ~ before the major version tells PPA to use the latest update in that series.

This is the approach recommended by the Osirium PPA team.

Now the task will build with the latest installed version in these series:

  • aws: 2.x.x
  • hashicorp_vault: 4.x.x
  • active_directory: 1.x.x

Newly installed major versions of those plugins won't affect this task at all.

PPA will always build the task with those plugin versions, until the locked versions are updated.