Skip to content

Commit

Permalink
Merge pull request #137 from flanksource/playbooks-new-features
Browse files Browse the repository at this point in the history 
Playbooks new features
  • Loading branch information
@moshloop
moshloop authored Jan 16, 2024
2 parents be92c4e + bfbe586 commit be5d68b
Show file tree
Hide file tree
Showing 5 changed files with 145 additions and 20 deletions.
76 changes: 58 additions & 18 deletions mission-control/docs/playbooks/concepts/playbook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,16 @@ Filters can define what resources (checks, configs or components) are permitted

Playbook parameter defines a parameter that a playbook needs to run.

| Field | Description | Scheme | Required |
| ------- | --------------------------- | -------- | -------- |
| `name` | Specify name of parameter. | `string` | `true` |
| `label` | Specify label of parameter. | `string` | `true` |
| Field | Description | Scheme | Required |
| ------------- | ------------------------------------------------------------------------------------------------- | ------------------- | -------- |
| `name` | Name of parameter. | `string` | `true` |
| `default` | Default value of the parameter. | `string` | |
| `label` | Label of the parameter. | `string` | `true` |
| `required` | Specify if the parameter is required | `bool` | |
| `icon` | Icon of parameter. See [icons](https://github.com/flanksource/flanksource-ui/tree/main/src/icons) | `string` | |
| `description` | Description of the parameter. | `string` | |
| `type` | Type of parameter. | `string` | |
| `properties` | Properties of parameter. | `map[string]string` | |

## Run

Expand All @@ -88,17 +94,17 @@ Start time can be in future or even in the past.

Actions are the fundamental tasks executed by a playbook. A playbook can comprise multiple actions, which are executed sequentially. If any action encounters an error and fails, the execution of the playbook is halted.

| Field | Description | Scheme | Required |
| -------------- | --------------------------------------------------------------- | -------------------------------------------------- | -------- |
| `name` | Name of action. | `string` | `true` |
| `delay` | Delay the execution of the action. _(Sensitive to the minute.)_ | [`DurationString`](#duration-string) | |
| `timeout` | Timeout on this action. | [`DurationString`](#duration-string) | |
| `exec` | Specify exec of action. | [`ExecAction`](../actions/exec.md) | |
| `gitops` | Specify gitops of action. | [`GitopsAction`](../actions/gitops.md) | |
| `http` | Specify http of action. | [`HttpAction`](../actions/http.md) | |
| `sql` | Specify sql of action. | [`SqlAction`](../actions/sql.md) | |
| `pod` | Specify pod of action. | [`PodAction`](../actions/pod.md) | |
| `notification` | Specify notification of action. | [`NotificationAction`](../actions/notification.md) | |
| Field | Description | Scheme | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------- |
| `name` | Name of action. | `string` | `true` |
| `delay` | A CEL expression that evaluates to a duration to delay the execution of the action. _(Sensitive to the minute.)_ | `string` | |
| `timeout` | Timeout on this action. | [`DurationString`](#duration-string) | |
| `exec` | Specify exec of action. | [`ExecAction`](../actions/exec.md) | |
| `gitops` | Specify gitops of action. | [`GitopsAction`](../actions/gitops.md) | |
| `http` | Specify http of action. | [`HttpAction`](../actions/http.md) | |
| `sql` | Specify sql of action. | [`SqlAction`](../actions/sql.md) | |
| `pod` | Specify pod of action. | [`PodAction`](../actions/pod.md) | |
| `notification` | Specify notification of action. | [`NotificationAction`](../actions/notification.md) | |

:::note
Specify one or more actions; but at least one.
Expand All @@ -107,15 +113,49 @@ Specify one or more actions; but at least one.
![Playbook Action Logs](../../images/playbook-action-logs.png)
_Fig: Playbooks Action Logs_

### Duration String
### Delaying actions

Duration strings specify duration in a human readable format.
Actions can be delayed by a fixed duration or conditionally by a CEL expression.
It's only sensitive to the minute. i.e. if you delay by 20s it can take upto a minute to execute.

**Examples:**
#### Templating

The CEL expression receives a environment variable that contain details about the corresponding config, check or component and the parameter (if applicable).

| Field | Description | Schema |
| ----------- | ---------------------------------------- | -------------------------------------------- |
| `config` | Config passed to the playbook | [`ConfigItem`](../references/config_item.md) |
| `component` | Component passed to the playbook | [`Component`](../references/component.md) |
| `check` | Canary Check passed to the playbook | [`Check`](../references/check.md) |
| `params` | User provided parameters to the playbook | `map[string]string` |

Valid time units are "s", "m", "h", "d", "w", "y". Eg:

- `1m15s`
- `1h5m`
- `23h`
- `1d8h`
- `1w6d8h`
- `19w0d8h`

### Conditionally running actions

Playbook actions can be conditionally run using a CEL Expression. The expressions should either return

- a boolean value _(`true` indicating run the action & skip the action otherwise)_
- or a special function among the ones listed below

#### Functions

| Function | Description |
| ----------- | ----------------------------------------------------------- |
| `always()` | run no matter what; even if the playbook is cancelled/fails |
| `failure()` | run if any of the previous actions failed |
| `skip()` | skip running this action |
| `success()` | run only if all previous actions succeeded (default) |
| `timeout()` | run only if any of the previous actions timed out |

#### Examples

- `if: config.deleted_at ? true: false`
- `if: always()`
23 changes: 23 additions & 0 deletions mission-control/docs/playbooks/examples/action-filter.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Playbook Action Filter

```yaml title="delete-kubernetes-pod.yaml"
---
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: delete kubernetes pod
spec:
configs:
- type: Kubernetes::Pod
actions:
- name: Delete the pod
exec:
script: kubectl delete pod {{.config.name}}
- name: Log Maintenance Success
delay: 2m
if: failure()
notification:
connection: connection://telegram/aditya
title: 'Failed to delete kubernetes pod {{.config.name}}'
message: 'Something went wrong with deleting kubernetes pod {{.config.name}}'
```
23 changes: 23 additions & 0 deletions mission-control/docs/playbooks/examples/exec-delay.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Delay Actions

```yaml title="delay-deletion.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: write-config-to-file
spec:
description: Creates a file with the content of the config
configs:
- type: Kubernetes::Pod
actions:
- name: Create the config file
exec:
script: echo -n '{{.config.config}}' > /tmp/{{.config.id}}
- name: Delete the file
delay: 'config.name.startsWith("actual") ? "1m" : "0s"'
exec:
script: rm /tmp/{{.config.id}}
```
This playbook saves the config of a `Kubernetes::Pod` to a temporary file. A delay is introduced before deleting that file. If the name of the pod beings with
`actual` then the deletion is delayed by a minute, else it is deleted immediately.
33 changes: 31 additions & 2 deletions mission-control/docs/playbooks/triggers/events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ Filters can give you fine-grained control over the events that can trigger the p

## Types

At this point, there's only support for events on canaries and components.

### Canary events

Canary events relate to activities on health checks.
Expand Down Expand Up @@ -83,3 +81,34 @@ spec:
title: 'Database {{.component.name}} has become unhealthy'
message: 'Description: {{.component.description}}'
```

### Config events

Config events relate to activities on config items.

| Event | Description |
| --------- | ----------------------------- |
| `created` | when a config item is created |
| `updated` | when a config item is updated |
| `deleted` | when a config item is deleted |

#### Example

```yaml title="notify-newly-scraped-pod.yaml"
apiVersion: mission-control.flanksource.com/v1
kind: Playbook
metadata:
name: Notify on pod config creation
spec:
description: Notify when a new pod is discovered
on:
component:
- event: config.created
filter: config.class == 'Pod'
actions:
- name: Send notification
notification:
connection: connection://telegram/playbook-alerts
title: 'A new kubernetes pod {{.config.name}} was scraped'
message: 'Namespace: {{.config.namespace}}'
```
10 changes: 10 additions & 0 deletions mission-control/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -592,6 +592,16 @@ const sidebars = {
id: 'playbooks/examples/approval',
label: 'Approval'
},
{
type: 'doc',
id: 'playbooks/examples/exec-delay',
label: 'Delaying actions'
},
{
type: 'doc',
id: 'playbooks/examples/action-filter',
label: 'Conditionally running actions'
},
],
},
{
Expand Down

0 comments on commit be5d68b

Please sign in to comment.