Ansible Operator Finalizers

Finalizers allow controllers (such as an Ansible Operator) to implement asynchronous pre-delete hooks. This allows custom logic to run after a resource has been marked for deletion, but before the resource has actually been deleted from the Kubernetes cluster. For Ansible Operator, this hook takes the form of an Ansible playbook or role. You can define the mapping from your finalizer to a playbook or role by simply setting the field on the entry in your watches.yaml. You can also choose to re-run your top-level playbook or role with different variables set. The watches.yaml finalizer configuration accepts the following options:

See for more information.

name

name is required.

This is the name of the finalizer. This is basically an arbitrary string, the existence of any finalizer string on a resource will prevent that resource from being deleted until the finalizer is removed. Ansible Operator will remove this string from the list of finalizers on successful execution of the specified role or playbook. A typical finalizer will be finalizer.<group>, where <group> is the group of the resource being managed.

playbook

One of playbook, role, or vars must be provided. If playbook is not provided, it will default to the playbook specified at the top level of the watches.yaml entry.

This field is identical to the top-level playbook field. It requires an absolute path to a playbook on the operator’s file system.

role

This field is identical to the top-level role field.

vars

One of playbook, role, or vars must be provided.

vars is an arbitrary map of key-value pairs. The contents of vars will be passed as to the playbook or role specified in the finalizer block, or at the top-level if neither playbook or role was set for the finalizer.

Here are a few examples of watches.yaml files that specify a finalizer:

This example will run playbook.yml when the Custom Resource is deleted. Because vars is set, the playbook will be run with state set to absent. Inside the playbook, the author can check this value and perform whatever cleanup is necessary.

  1. ---
  2. - version: v1alpha1
  3.   kind: Database
  4.   role: database
  5.   finalizer:
  6.     name: finalizer.app.example.com
  7.     vars:
  8.       state: absent

This example is nearly identical to the first, except it will run the /opt/ansible/roles/database role, rather than a playbook, with the state variable set to absent.

  1. ---
  2. - version: v1alpha1
  4.   kind: Database
  5.   playbook: playbook.yml
  6.     name: finalizer.app.example.com
  7.     playbook: destroy.yml

This example will run the /opt/ansible/destroy.yml playbook when the Custom Resource is deleted.

This example will run the myRole when the Custom Resource is deleted. (The collection must have been installed.)

You can set playbook or role and vars at the same time. This can be useful if only a small part of your logic handles interacting with the component that requires cleanup. Rather than run all the logic again, you can specify only to run the role or playbook that handled the interaction, with a different variable set.

  1. ---
  2. - version: v1alpha1
  3.   group: app.example.com
  4.   kind: Database
  5.   playbook: playbook.yml
  6.   finalizer:
  7.     name: finalizer.app.example.com
  8.     role: manage_credentials
  9.     vars:

For this example, assume our application configures automated backups to a third party service. On deletion, all we want to do is revoke the credentials used to backup the data. We run just the /opt/ansible/roles/manage_credentials role, which is imported by our playbook to create the credentials in the first place, but we pass the state: revoked option, which causes the role to invalidate our credentials. For everything else in our application, automatic deletion of dependent resources will be sufficient, so we can exit successfully and let the operator remove our finalizer and allow the resource to be deleted.

Further reading

•