Promise Workflows
A Kratix Promise may contain workflow definitions for hooking into the Promise lifecycle.
Kratix supports two Promise workflow types: configure
and delete
.
- The
configure
workflow runs when the Promise is created, updated, or reconciled. - The
delete
workflow runs when the Promise is deleted.
Kratix workflows are made up of one or more Pipelines.
- The
configure
workflow may contain multiple Pipelines, which are executed serially. - The
delete
workflow can only contain a single Pipeline.
Refer to the Workflows documentation for details on how to write Kratix Pipelines.
To define Promise workflows inside a Promise, use spec.workflows.promise
in the Promise
definition as shown below.
platform: platform.kratix.io/v1alpha1
kind: Promise
metadata:
...
spec:
...
workflows:
promise:
configure:
- # Pipeline definitions (multiple)
delete:
- # Pipeline definition (single)
Configure Workflows
The configure
workflow runs when the Promise is created, updated, or reconciled.
Multiple Pipelines
Promise Configure workflows allow for multiple Pipelines to be executed in sequence.
This enables step-by-step configuration of declarative state, as each Pipeline ends by writing its output to the Kratix State Store. This means each Pipeline can depend upon state declared during the previous Pipelines.
Within each Pipeline, an array of containers are defined, which will also execute in sequence.
For simple cases, a single Pipeline with one or many containers will suffice.
The example below shows how a promise.configure
workflow can be defined:
platform: platform.kratix.io/v1alpha1
kind: Promise
metadata:
...
spec:
...
workflows:
promise:
configure:
- apiVersion: platform.kratix.io/v1alpha1
kind: Pipeline
metadata:
name: pipeline-a # Executes first
spec:
containers:
...
- apiVersion: platform.kratix.io/v1alpha1
kind: Pipeline
metadata:
name: pipeline-b # Follows pipeline-a
spec:
containers:
...
In this example, pipeline-a
will run first, followed by pipeline-b
.
Pipeline Failures
A Pipeline fails if any of its containers
return a non-zero exit code.
If this occurs, the workflow halts: no further containers are executed within the Pipeline, and no further Pipelines are executed in the workflow.
To re-run a workflow following a Pipeline failure, you can perform a manual reconciliation of the Promise, which will trigger the workflow again from the beginning.
Idempotency
All commands which run in Configure workflows must be idempotent, as there is a guarantee that they will be run multiple times a day, and may be run much more frequently depending on other environmental impacts (e.g. Pod restarts).
The promise.configure
workflow is regularly executed. Kubernetes reconciles on a number
different actions, including, but not limited to:
- Promise creation
- Regular interval (10 hours, not currently configurable)
- Kratix Controller restarts
- Changes to the Promise definition
Manual Reconciliation
Sometimes you may wish to manually trigger a Configure workflow for a specific Promise.
In addition to the standard triggers outlined above, a Promise can be manually triggered for reconciliation by labelling it as follows:
kratix.io/manual-reconciliation: "true"
This will trigger the Promise Configure workflow to run.
This workflow instance will terminate any in-progress Promise Configure workflow and start again from the first Pipeline.
Once Kratix schedules the manual workflow, the label will be removed, allowing you to add it again for any additional manual runs.
See below for an example command to trigger a manual reconciliation of a redis
Promise.
kubectl label promises.platform.kratix.io redis kratix.io/manual-reconciliation=true
Delete Workflows
Promise Delete workflows are triggered when a Promise is deleted, and currently only support a single Pipeline.
This Pipeline is responsible for cleaning up resources and configurations that were set up
by the promise.configure
workflow.
The example below shows how a promise.delete
workflow can be defined.
platform: platform.kratix.io/v1alpha1
kind: Promise
metadata:
...
spec:
...
workflows:
promise:
delete:
- apiVersion: platform.kratix.io/v1alpha1
kind: Pipeline
metadata:
name: delete-pipeline # Single pipeline
spec:
containers:
...
Pipeline Failures
Kratix will trigger the Delete Pipeline exactly once.
If a command fails during container execution, this must be handled within the container itself (including any retry attempts).
Kratix will not reschedule/retry any Pipelines which have failed as part of a Delete workflow.