Skip to main content

Manage execution hooks

Contributors netapp-mwallis
PDFs

An execution hook is a custom action that you can configure to run in conjunction with a data protection operation of a managed app. For example, if you have a database app, you can use an execution hook to pause all database transactions before a snapshot, and resume transactions after the snapshot is complete. This ensures application-consistent snapshots.

Types of execution hooks

Trident protect supports the following types of execution hooks, based on when they can be run:

  • Pre-snapshot

  • Post-snapshot

  • Pre-backup

  • Post-backup

  • Post-restore

  • Post-failover

Order of execution

When a data protection operation is run, execution hook events take place in the following order:

  1. Any applicable custom pre-operation execution hooks are run on the appropriate containers. You can create and run as many custom pre-operation hooks as you need, but the order of execution of these hooks before the operation is neither guaranteed nor configurable.

  2. The data protection operation is performed.

  3. Any applicable custom post-operation execution hooks are run on the appropriate containers. You can create and run as many custom post-operation hooks as you need, but the order of execution of these hooks after the operation is neither guaranteed nor configurable.

If you create multiple execution hooks of the same type (for example, pre-snapshot), the order of execution of those hooks is not guaranteed. However, the order of execution of hooks of different types is guaranteed. For example, the following is the order of execution of a configuration that has all of the different types of hooks:

  1. Pre-snapshot hooks executed

  2. Post-snapshot hooks executed

  3. Pre-backup hooks executed

  4. Post-backup hooks executed

Note The preceding order example only applies when you run a backup that does not use an existing snapshot.
Note You should always test your execution hook scripts before enabling them in a production environment. You can use the 'kubectl exec' command to conveniently test the scripts. After you enable the execution hooks in a production environment, test the resulting snapshots and backups to ensure they are consistent. You can do this by cloning the app to a temporary namespace, restoring the snapshot or backup, and then testing the app.

Important notes about custom execution hooks

Consider the following when planning execution hooks for your apps.

  • An execution hook must use a script to perform actions. Many execution hooks can reference the same script.

  • Trident protect requires the scripts that execution hooks use to be written in the format of executable shell scripts.

  • Script size is limited to 96KB.

  • Trident protect uses execution hook settings and any matching criteria to determine which hooks are applicable to a snapshot, backup, or restore operation.

Note Because execution hooks often reduce or completely disable the functionality of the application they are running against, you should always try to minimize the time your custom execution hooks take to run. If you start a backup or snapshot operation with associated execution hooks but then cancel it, the hooks are still allowed to run if the backup or snapshot operation has already begun. This means that the logic used in a post-backup execution hook cannot assume that the backup was completed.

Execution hook filters

When you add or edit an execution hook for an application, you can add filters to the execution hook to manage which containers the hook will match. Filters are useful for applications that use the same container image on all containers, but might use each image for a different purpose (such as Elasticsearch). Filters allow you to create scenarios where execution hooks run on some but not necessarily all identical containers. If you create multiple filters for a single execution hook, they are combined with a logical AND operator. You can have up to 10 active filters per execution hook.

Each filter you add to an execution hook uses a regular expression to match containers in your cluster. When a hook matches a container, the hook will run its associated script on that container. Regular expressions for filters use the Regular Expression 2 (RE2) syntax, which does not support creating a filter that excludes containers from the list of matches. For information on the syntax that Trident protect supports for regular expressions in execution hook filters, see Regular Expression 2 (RE2) syntax support.

Note If you add a namespace filter to an execution hook that runs after a restore or clone operation and the restore or clone source and destination are in different namespaces, the namespace filter is only applied to the destination namespace.

Execution hook examples

Visit the NetApp Verda GitHub project to download real execution hooks for popular apps such as Apache Cassandra and Elasticsearch. You can also see examples and get ideas for structuring your own custom execution hooks.

Create an execution hook

You can create a custom execution hook for an app using Trident protect. You need to have Owner, Admin, or Member permissions to create execution hooks.

Use a CR

  1. Create the custom resource (CR) file and name it trident-protect-hook.yaml.

  2. Configure the following attributes to match your Trident protect environment and cluster configuration:

    • metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.

    • spec.applicationRef: (Required) The Kubernetes name of the application for which to run the execution hook.

    • spec.stage: (Required) A string indicating which stage during the action that the execution hook should run. Possible values:

      • Pre

      • Post

    • spec.action: (Required) A string indicating which action the execution hook will take, assuming any execution hook filters specified are matched. Possible values:

      • Snapshot

      • Backup

      • Restore

      • Failover

    • spec.enabled: (Optional) Indicates whether this execution hook is enabled or disabled. If not specified, the default value is true.

    • spec.hookSource: (Required) A string containing the base64-encoded hook script.

    • spec.timeout: (Optional) A number defining how long in minutes that the execution hook is allowed to run. The minimum value is 1 minute, and the default value is 25 minutes if not specified.

    • spec.arguments: (Optional) A YAML list of arguments that you can specify for the execution hook.

    • spec.matchingCriteria: (Optional) An optional list of criteria key value pairs, each pair making up an execution hook filter. You can add up to 10 filters per execution hook.

    • spec.matchingCriteria.type: (Optional) A string identifying the execution hook filter type. Possible values:

      • ContainerImage

      • ContainerName

      • PodName

      • PodLabel

      • NamespaceName

    • spec.matchingCriteria.value: (Optional) A string or regular expression identifying the execution hook filter value.

      Example YAML:

      apiVersion: protect.trident.netapp.io/v1
kind: ExecHook
metadata:
  name: example-hook-cr
  namespace: my-app-namespace
  annotations:
    astra.netapp.io/astra-control-hook-source-id: /account/test/hookSource/id
spec:
  applicationRef: my-app-name
  stage: Pre
  action: Snapshot
  enabled: true
  hookSource: IyEvYmluL2Jhc2gKZWNobyAiZXhhbXBsZSBzY3JpcHQiCg==
  timeout: 10
  arguments:
    - FirstExampleArg
    - SecondExampleArg
  matchingCriteria:
    - type: containerName
      value: mysql
    - type: containerImage
      value: bitnami/mysql
    - type: podName
      value: mysql
    - type: namespaceName
      value: mysql-a
    - type: podLabel
      value: app.kubernetes.io/component=primary
    - type: podLabel
      value: helm.sh/chart=mysql-10.1.0
    - type: podLabel
      value: deployment-type=production

  3. After you populate the CR file with the correct values, apply the CR:

    kubectl apply -f trident-protect-hook.yaml
Use the CLI

  1. Create the execution hook, replacing values in brackets with information from your environment. For example:

    tridentctl protect create exechook <my_exec_hook_name> --action <action_type> --app <app_to_use_hook> --stage <pre_or_post_stage> --source-file <script-file>