Visitar URL original
Actions | ZarfSkip to content
Zarf

Actions

Component Actions offer several exec entrypoints that allow a component to perform additional logic at key stages of its lifecycle. These actions are executed within a shell with the same context as the Zarf binary. For a detailed overview of the execution sequence of component actions, please refer to the Zarf package create lifecycle documentation and package deploy lifecycle documentation. Additionally, you can experiment with the component actions example located in the Component Actions example.

Action Sets

The component.actions field includes the following optional keys, also known as action sets:

  • onCreate - Runs during zarf package create.
  • onDeploy - Runs during zarf package deploy.
  • onRemove - Runs during zarf package remove.

Action Set Lists

These action sets contain optional action lists. The onSuccess and onFailure action lists are conditional and rely on the success or failure of previous actions within the same component, as well as the component’s lifecycle stages.

  • before - sequential list of actions that will run before this component is processed for create, deploy, or remove.
  • onSuccess - sequential list of actions that will run after the component is successfully processed for create, deploy, or remove.
  • onFailure - sequential list of actions that will run after ANY error during the above actions or component operations.

Action Set Defaults

In addition to action lists, action sets can also specify a defaults section that will be applied to all actions in the set. The defaults section supports dir, env, maxTotalSeconds, retries, shell, and silent.

Action Configurations

An action list contains an ordered set of action configurations that specify what a particular action will do. In Zarf there are two action types (cmd and wait), the configuration of which is described below.

Common Action Configuration Keys

Between all action configurations, there are a few common keys that are common to all of them which are described below:

  • description - a description of the action that will replace the default text displayed to the user when the action is running. For example: description: "File to be created" would display Waiting for "File to be created" instead of Waiting for "touch test-create-before.txt".
  • maxTotalSeconds - the maximum total time to allow the command to run (default: 0 - no limit for command actions, 300 - 5 minutes for wait actions).

cmd Action Configuration

A cmd action executes arbitrary commands or scripts within a shell wrapper. You can use the cmd key to define the command(s) to run. This can also be a multi-line script. You cannot use cmd and wait in the same action.

Within each of the action lists (before, onSuccess, and onFailure), the following action configurations are available:

  • cmd - (required if not a wait action) the command to run.
  • dir - the directory to run the command in, defaults to the current working directory.
  • silent - whether to mute the realtime output of the command, output is always shown at the end on failure (default: false).
  • retries - the maximum number of times to retry the command if it fails (default: 0 - no retries).
  • env - an array of environment variables to set for the command in the form of name=value.
  • setValues - store the command’s standard output under one or more value keys for subsequent actions or components (onDeploy and onRemove only). Each entry specifies a key and an optional type of string (default), json, or yaml.
  • enableTemplating - render the command using package values and other template data (onDeploy and onRemove only; default: false).
  • shell - set a preferred shell for the command to run in for a particular operating system (default is sh for macOS/Linux and powershell for Windows).

wait Action Configuration

The wait action temporarily halts the component stage it is initiated in, either until the specified condition is satisfied or until the maxTotalSeconds time limit is exceeded (which, by default, is set to 5 minutes). To define wait parameters, execute the wait key; it is essential to note that you cannot use cmd and wait in the same action. Essentially, a wait action is yaml sugar for a call to ./zarf tools wait-for.

Within each of the action lists (before, onSuccess, and onFailure), the following action configurations are available:

  • wait - (required if not a cmd action) the wait parameters.
    • cluster - perform a wait operation on a Kubernetes resource (kubectl wait).
      • kind - the kind of resource to wait for (required).
      • name - the name of the resource to wait for (required), can be a name or label selector.
      • namespace - the namespace of the resource to wait for.
      • condition - the condition or JSONPath state to wait for. When omitted, Zarf waits for the resource to be ready using kstatus. Set exists to wait only for the resource to exist. For non-core resources, include the API version and group in kind, such as Deployment.v1.apps.
    • network - perform a wait operation on a network resource (curl).
      • protocol - the protocol to use (i.e. http, https, tcp).
      • address - the address/port to wait for (required).
      • code - the HTTP status code to wait for if using http or https (defaults to any 2xx response).

Action Examples

Below are some examples of putting together simple actions at various points in the Zarf lifecycle:

Below is a simple example of an onCreate action set that declares defaults as well as before and onSuccess action lists:

  - name: on-create
    optional: true
    actions:
      # runs during "zarf package create"
      onCreate:
        # defaults are applied to all actions in this action set - below are the default defaults
        defaults:
          dir: ""
          env: []
          retries: 0
          maxTotalSeconds: 300
          silent: false
          shell:
            darwin: sh
            linux: sh
            windows: powershell
        # runs before the component is created
        before:
          # on Windows with `pwsh` or `powershell`, `touch` is replaced with New-Item
          - cmd: touch test-create-before.txt
            # description shows a more user friendly message when waiting for the command
            description: Create a test file
            # dir is the directory to run the command in
            dir: ""
            # env sets environment variables for this action only
            env:
              - thing=stuff
            # retries is the number of times to retry the action if it fails
            retries: 0
            # maxTotalSeconds is the maximum amount of times the action can run before it is killed, over all retries
            maxTotalSeconds: 30
            # silent determine if actions output should be printed to the console
            silent: false
            # shell sets the preferred shell across operating systems, in this case "pwsh" instead of "powershell" on Windows
            shell:
              windows: pwsh
        # runs after the component is created
        onSuccess:
          # actions in a list run in order
          - cmd: touch test-create-after.txt
          - cmd: sleep 0.5
          - cmd: echo "I can print!"
          - cmd: sleep 0.5
          # cmd actions can also specify a multiline string to run like a script
          - cmd: |
              echo "multiline!"
              sleep 0.5
              echo "updates!"
              sleep 1
              echo "in!"
              sleep 0.5
              echo "realtime!"
              sleep 0.5

Action Transformations

As you may have noticed mentioned in the before action list of the above Simple onCreate example, Zarf provides some helpful transformations that help enhance cross-platform compatibility and allow you to better orchestrate Zarf and its components.

Below are the transformations that Zarf will make on an action before it is ran:

  • Replace ./zarf  with the path to the currently running Zarf executable.
    • This allows you to run Zarf in Zarf and is designed to help you use zarf tools commands in the airgap.
  • Replace common Unix commands and shell syntax with powershell / pwsh alternatives on Windows.
    • This allows commands like touch to work on Windows and while not perfect enhances cross-platform capabilities.

Within onDeploy action lists, you can use the setValues action configuration to set a list of values that can be used in other actions or components during zarf package deploy. Use enableTemplating: true on action commands that read values with Go template syntax such as {{ .Values.example.key }}. These values will be available in subsequent actions and for the remainder of the deploy.

  - name: on-deploy-with-dynamic-value
    optional: true
    actions:
      # runs during "zarf package deploy"
      onDeploy:
        # runs before the component is deployed
        before:
          # setValues can be used to set a value for use in other actions or components
          - cmd: echo "meow"
            # the key to set with the output of the action (only useable onDeploy and onRemove)
            setValues:
              - key: .sounds.cat
          # this action will have access to the value set in the previous action
          - cmd: echo "the cat says {{ .Values.sounds.cat }}"
            enableTemplating: true

Additional Action Use Cases

Below are a few more use cases from other examples and packages for how actions can be used:

The example below shows the kiwix-serve component downloading a .zim file and packaging it in an image using onCreate.before actions.

  - name: kiwix-serve
    manifests:
      - name: kiwix-serve
        namespace: kiwix
        files:
          - manifests/deployment.yaml
          - manifests/service.yaml
    images:
      - name: ghcr.io/kiwix/kiwix-serve:3.5.0-2
    imageArchives:
      - path: kiwix-data.tar
        images:
            # Using zarf.internal as our registry ensures our manifest will never pull from a squatted registry url even if mutation is never run.
          - name: zarf.internal/kiwix-data:local
    actions:
      onCreate:
        before:
          # Download a .zim file of a DevOps Stack Exchange snapshot so that it can placed in the image we're building
          - cmd: curl -fSL https://zarf-init-resources-dev.s3.us-east-1.amazonaws.com/devops.stackexchange.com_en_all_2026-02.zim -o zim-data/devops.stackexchange.com_en_all_2026-02.zim
          # Below are some more examples of *.zim files of available content:
          # https://library.kiwix.org/?lang=eng
          # NOTE: If `zarf package create`ing regularly you should mirror content to a web host you control to be a friendly neighbor


          # Build a container image containing the ZIM data file
          - cmd: docker build -t zarf.internal/kiwix-data:local .


          # Export the container image to a tar archive for use as an image archive
          - cmd: docker save zarf.internal/kiwix-data:local -o kiwix-data.tar


attachments:
  readme: readme.md