github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/docs/3-create-a-jackal-package/7-component-actions.md

import ExampleYAML from '@site/src/components/ExampleYAML';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Component 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 Jackal binary. For a detailed overview of the execution sequence of component actions, please refer to the Jackal [package create lifecycle documentation](./5-package-create-lifecycle.md) and [package deploy lifecycle documentation](../4-deploy-a-jackal-package/1-package-deploy-lifecycle.md). Additionally, you can experiment with the component actions example located in the [Component Actions](../../examples/component-actions/README.md) example page.

## Action Sets

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

- `onCreate` - Runs during `jackal package create`.
- `onDeploy` - Runs during `jackal package deploy`.
- `onRemove` - Runs during `jackal 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`.
- `after` - sequential list of actions that will run after this component is successfully processed for `create`, `deploy`, or `remove`.
- `onSuccess` - sequential list of actions that will run after **ALL** `after` actions have successfully completed.
- `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 contains all of the same elements as an action configuration, with the exception of the action specific keys like `cmd`, `description` or `wait`, which are not allowed in the `defaults` section.

## Action Configurations

An `action list` contains an ordered set of `action configurations` that specify what a particular action will do.  In Jackal 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`, `after`, `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.
- `mute` - whether to mute the realtime output of the command, output is always shown at the end on failure (default: `false`).
- `maxRetries` - 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`.
- `setVariables` - set the standard output of the command to a list of variables that can be used in other actions or components (onDeploy only).
- `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).

:::info

By default, multi-line `cmd` blocks will fail if one of the lines errors out; this is analogous to setting `set -e` in a shell script, as documented in the [GNU bash docs](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html).

:::

:::note

Any binaries you execute in your `cmd` actions must exist on the machine they are executed on.  You can bring binaries with a Jackal Package as `files` with the `executable` key set, or take advantage of the `./jackal ` transformation as described in [action transformations](#action-transformations).

:::

### `wait` Action Configuration

The `wait` action temporarily halts the component stage it's 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's 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 `./jackal tools wait-for`.

Within each of the `action` lists (`before`, `after`, `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 to wait for (default: `exists`).
  - `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`, or `success` to check for any 2xx response code (default: `success`).

## Action Examples

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

<Tabs queryString="action-examples">
<TabItem value="Simple onCreate">

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

<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-create" />
</TabItem>
<TabItem value="Failure Handling onDeploy">

Below is an example of an `onDeploy` action set that demonstrates how you can use `onFailure` actions to perform cleanup tasks or user messaging when an action of component lifecycle step fails:

<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-deploy-with-timeout" />
</TabItem>
<TabItem value="Wait for a Resource">

Below are examples of waiting for resources to exist or be available within an action using `wait` actions:

<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-create-with-network-wait-action" />
<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-deploy-with-wait-action" showLink={false} />
</TabItem>
</Tabs>

## Action Transformations

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

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

- Replace `./jackal `&nbsp;with the path to the currently running Jackal executable.
  - This allows you to run Jackal in Jackal and is designed to help you use `jackal tools` commands in the air gap.
- 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.
- Add `env` entries for all previously declared Jackal `variables`.
  - This allows you to use variables in actions and when combined with `setVariables` allows you to chain `variables` from an action for use in later actions or templates.

<Tabs queryString="action-transformations">

<TabItem value="Variables onDeploy">

Within `onDeploy` action lists, you can use the `setVariables` action configuration to set a list of variables that can be used in other actions or components during `jackal package deploy`. The variable value will be assigned in two environment variables: `JACKAL_VAR_{NAME}` and `TF_VAR_{name}`. These values will be accessible in subsequent actions and can be used for templating in `files` or `manifests` in other components as `###JACKAL_VAR_{NAME}###`. This feature allows package authors to define dynamic runtime variables for consumption by other components or actions.

:::note

Unlike normal variables, `setVariables` do not need to be defined with the `variables` key at the top of the `jackal.yaml`.

:::

<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-deploy-with-multiple-variables" />

</TabItem>
<TabItem value="Jackal in Jackal onRemove">

Below is an example of an `onRemove` action set that demonstrates how you can use `./jackal `&nbsp;to use Jackal commands like `jackal tools kubectl` to perform actions on systems that might not have the pre-requisite software (like `kubectl`) installed onto them:

<ExampleYAML src={require('../../examples/component-actions/jackal.yaml')} component="on-remove" />

</TabItem>
</Tabs>

---

## Additional Action Use Cases

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

<Tabs queryString="action-transformations">

<TabItem value="Downloading Pre-requisites">

The below example shows the `kiwix-serve` component from the data injections example which downloads a `.zim` file with an `onCreate.before` action for inclusion into the Jackal package.

<ExampleYAML src={require('../../examples/kiwix/jackal.yaml')} component="kiwix-serve" />

</TabItem>


<TabItem value="Setting up Dependencies">

The below example includes the `eksctl` binary and `eks.yaml` file in one component, setting it up in an `onDeploy.after` action and then uses the `eksctl` binary in a second component to create an EKS cluster in an `onDeploy.before` action.

<ExampleYAML src={require('../../packages/distros/eks/jackal.yaml')} component="load-eksctl" />
<ExampleYAML src={require('../../packages/distros/eks/jackal.yaml')} component="deploy-eks-cluster" showLink={false} />

</TabItem>

<TabItem value="Waiting for GitOps Resources">

The below example shows using a `wait` command to wait for a GitOps deployment to happen after Jackal configures the initial `GitRepository` manifest.  By default Jackal will only track the resources it directly deploys, but adding a `wait` action allows you to control the lifecycle more directly.

<ExampleYAML src={require('../../examples/podinfo-flux/jackal.yaml')} component="podinfo-via-flux" />

</TabItem>

</Tabs>