component-actions

Note

To view the full example, as well as its dependencies, please visit examples/component-actions.

This example demonstrates how to define actions within your package that can run either on zarf package create, zarf package deploy or zarf package remove. These actions will be executed with the context that the Zarf binary is executed with.

For more details on component actions, see the component actions documentation.

zarf.yaml

apiVersion: zarf.dev/v1beta1
kind: ZarfPackageConfig
metadata:
  name: component-actions
  description: Component actions examples

values:
  files:
    - values.yaml

# See the example README.md in this folder or /adrs/0010-scripts-actions.md for more info.
components:
  - 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

  - name: on-deploy-and-remove
    optional: true
    actions:
      # runs during "zarf package deploy"
      onDeploy:
        # runs before the component is deployed
        before:
          - cmd: touch test-deploy-before.txt
        # runs after the component is deployed
        onSuccess:
          - cmd: touch test-deploy-after.txt
      # runs during "zarf package remove"
      onRemove:
        # runs before anything else from the component is removed
        before:
          - cmd: rm test-deploy-before.txt
        # runs after everything else from the component is removed
        onSuccess:
          - cmd: rm test-deploy-after.txt

  - name: on-deploy-with-value
    optional: true
    actions:
      # runs during "zarf package deploy"
      onDeploy:
        # runs before the component is deployed
        before:
          - cmd: echo "the dog says {{ .Values.sounds.dog }}"
            enableTemplating: true

  - 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

  - name: on-deploy-with-multiple-values
    optional: true
    actions:
      # runs during "zarf package deploy"
      onDeploy:
        # runs before the component is deployed
        before:
          # setting this value will allow it to be used in other actions with additional values
          # set in other actions or components
          - cmd: echo "hiss"
            # setValues defines a list of values to set from the `cmd` standard out.
            setValues:
              - key: .sounds.snake
        # onSuccess will only run if steps in this component are successful
        onSuccess:
          # this action will print the cat sound value that was set in a previous component
          - cmd: echo "the cat says {{ .Values.sounds.cat }}"
            enableTemplating: true
          # this action will print the dog sound value set in values.yaml
          - cmd: echo "the dog says {{ .Values.sounds.dog }}"
            enableTemplating: true
          # this action will print the snake sound value set within this component
          - cmd: echo "the snake says {{ .Values.sounds.snake }}"
            enableTemplating: true

  - name: on-deploy-with-template-use-of-value
    optional: true
    files:
      # this file will be copied to the target location and the cat, dog, and snake sounds will be replaced with their values
      # requires the on-deploy-with-dynamic-value and on-deploy-with-multiple-values components
      - source: test.txt
        destination: test-templated.txt
        checksum: sha256:d84fa3f5071b5cee0ffb09989c95b0078f4265ed485b314492a19bab2e3f69f3
        enableTemplating: true

  - name: on-deploy-with-timeout
    optional: true
    description: This component will fail after 1 second
    actions:
      # runs during "zarf package deploy"
      onDeploy:
        # defaults allow you to specify default values for the actions in that actionSet
        defaults:
          # maxTotalSeconds is the maximum amount of time the action can run before it is killed, over all retries
          maxTotalSeconds: 1
        before:
          # this action will fail after 1 second
          - cmd: sleep 10
        onFailure:
          - cmd: echo "😭😭😭 this action failed because it took too long to run 😭😭😭"

  - name: on-remove
    optional: true
    # A manifest that we expect to be removed by Zarf
    manifests:
      - name: test-configmap
        files:
          - test-configmap.yaml
    actions:
      # runs during "zarf package remove"
      onRemove:
        before:
          # because this runs before the manifest is removed this should return our manifest
          - cmd: ./zarf tools kubectl get configmap -n zarf remove-test-configmap || echo "Not Found"
        onSuccess:
          # because this runs after the manifest is removed this should no longer be found
          - cmd: ./zarf tools kubectl get configmap -n zarf remove-test-configmap || echo "Not Found"

  - name: on-deploy-with-env-var
    optional: true
    target:
      os: linux
    actions:
      onDeploy:
        before:
          - cmd: touch $TEST_FILENAME
            env:
              # this will set the env var TEST_FILENAME - useful for passing information into scripts
              - TEST_FILENAME=test-filename-from-env.txt

  - name: on-create-with-network-wait-action
    optional: true
    description: This component will wait for 15 seconds for a network resource to be available
    actions:
      onCreate:
        onSuccess:
          - description: Github.com to be available
            maxTotalSeconds: 15
            wait:
              # wait for a network address to return a 200 OK response
              network:
                protocol: https
                address: github.com
                code: 200

  - name: on-deploy-with-wait-action
    optional: true
    description: This component will wait for 5 seconds for the test-configmap to be exist
    manifests:
      - name: test-configmap
        files:
          - test-configmap.yaml
    actions:
      onDeploy:
        onSuccess:
          - description: The simple-configmap to exist
            maxTotalSeconds: 5
            wait:
              # wait for the configmap to be available in the cluster
              cluster:
                kind: configmap
                name: simple-configmap
                namespace: zarf
                condition: exists

  - name: on-deploy-immediate-failure
    optional: true
    description: This component will fail on the first error instead of continuing execution
   # the default for multi-line commands is set -e
    actions:
      onDeploy:
        onSuccess:
          - cmd: |
              bad_cmd
              echo "this text shouldn't be printed"

attachments:
  readme: readme.md