Writing a Filter Plugin in Ansible

You might find that you're doing the same kind of data-munging in multiple places. There are many cases where you'd want to pull this into a little named package:

• It requires logic which can't be expressed simply in basic jinja filters
• It's common and used in many places, so there's lots of duplication
• It's uncommon and you can never remember the requirements
• It's actually complicated
• You just want to name what these 3 filters do together

Basic outline

The basic outline of a plugin is as follows:

import re


def storage_account(name):  # 3
	return re.sub("[^a-z0-9]", "", name)[:24]


class FilterModule(object):  # 1
	def filters(self):  # 2
		return {"storage_account": storage_account}  # 4

1. Create a class FilterModule
2. Create a function filters
3. Define your function
4. Return a dict with k-vs of filter_name:function_reference

Documenting your plugin

If you want your documentation to work with the Ansible tooling (showing up nicely in the docs, working with ansible-doc), you can't use the standard ansible documentation, since Filter plugins don't show up as an option you can select documentation for. Go figure. You can still try to use the standard documentation features, though.

You can include only the sections of the documentation that you want to appear. Here's the full referece for the version this article was written to. For convenience, here they are:

• Shebang & encoding
• Copyright
• DOCUMENTATION (includes module parameters)
• EXAMPLES
• RETURN

These have to be python strings which contain the YAML. This makes it kinda gross to work on, since you have no YAML syntax highlighting to help you. Here's a stub python file (feel free to change the license line):

{% raw %}

#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) {{ year }}, {{ Your Name }} <{{ your email }}>
# GNU Affero General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/agpl-3.0.txt)

DOCUMENTATION = r"""
module:
short_description:
description:
  -
version_added: "0.1.0"
options:
"""

EXAMPLES = r"""
"""

RETURN = r"""
{{ key }}:
  desctiption:
  returned:
  type:
  sample:
"""

{% endraw %}

Common things you'd want to do

Using an existing filter

If you want to use an existing filter plugin (perhaps to format your output), you can just import them from the Ansible package:

from ansible.plugins.filter.core import to_json, quote

Including other parameters in your filter

If you want to have other parameters in your filter, you can just do that

from ipaddress import ip_network


def ip_in_snet(snet, ip):
	_snet = ip_network(snet)
	_ip = int(ip)
	return _snet[_ip]


class FilterModule(object):
	def filters(self):
		return {"ip_in_snet": ip_in_snet}

and then use that like you'd expect, more or less

 "{{ '10.0.1.0/24' | ip_in_snet(10) }}" 

Building an extractor

Sometimes you can't remember the sequence of keys you need to extract that thing you want from the huge JSON blob. You can write a simple extractor:

DOCUMENTATION = r"""
name: extract_connectionstring
short_description: extracts the connection stirng from azure_rm_storageaccount_info
description:
  - extracts the connection stirng from M(azure_rm_storageaccount_info)
  - make sure to use the option C(show_connection_string: true) on the M(azure_rm_storageaccount_info) invocation
options:
  rm_info:
  description: 
    - The result of azure_rm_storageaccount_info
  type: object
  required: True
  endpoint:
  description:
    - The storageaccount endpoint to get the connectionstring for
    - if blank, will fetch for blob
    - use "key" to get the key itself
  choices: ["blob", "file", "queue", "table", "key"]
  required: False
    default: blob
"""

EXAMPLES = r"""
- name: get storageaccount info
  azure_rm_storageaccount_info:
    name: "{{ storage_acount_name }}"
    resource_group "{{ rg }}"
    show_connection_string: true # important !
  register: storageaccount_raw

- name: get blob connection string
  set_fact:
    blob_connectionstring: "{{ storageaccount_raw | extract_connectionstring }}

- name: get connection string for something other than blob
  set_fact:
    table_connectionstring: "{{ storageaccount_raw | extract_connectionstring('table') }}

- name: get account key
  set_fact:
    connectionstring: "{{ storageaccount_raw | extract_connectionstring('key') }}
"""


def extract_connectionstring(rm_info, endpoint="blob"):
	if endpoint == "key":
		return rm_info["storageaccounts"][0]["primary_endpoints"]["key"]
	else:
		return rm_info["storageaccounts"][0]["primary_endpoints"][endpoint][
			"connectionstring"
		]


class FilterModule(object):
	def filters(self):
		return {"extract_connectionstring": extract_connectionstring}

Abusing filters as functions

Let's say that you want to have some functions assemble things, like you would with some proper typed data modelling. I'm not saying this is a good idea, but you can use functions as the closest thing to that (it's not really close). For an example, I always forget the little fiddly bits of assembling an Azure Storageaccount Lifecycle Policy. I could do the following:

from _includes.resources.ansible_plugins.filter.extractor import EXAMPLES


EXAMPLES = r"""
- name: format lifecycle policy
  set_fact:
    autodelete_rule: "{{ "autodelete" | storageaccount_lifecycle_rule(filters, blob_actions) }}
  vars:
    blob_actions:
      - {"delete":{"daysAfterModificationGreaterThan": 30}}
    filters:
      - {"blobTypes":["blockBlob"],"prefixMatch":["my_container"]}
"""


from typing import Dict


def rule(
	name,
	filters,
	actions_blob: Dict[str, Dict] = None,
	actions_version: Dict[str, Dict] = None,
):
	return {
		"enabled": True,
		"name": str(name),
		"type": "Lifecycle",
		"definitions": {
			"actions": {"baseBlob": actions_blob, "versions": actions_version,},
			"filters": filters,
		},
	}


class FilterModule(object):
	def filters(self):
		return {"storageaccount_lifecycle_rule": rule}

And yes, you can also build filters to construct those filters and blob_actions, and make a terrible filter chain. But maybe don't and just write a one-off plugin.