Kubernetes Event Triggers
Testkube allows you to automate running Test Workflows by defining triggers on certain events for various Kubernetes resources.
What is a Testkube Event Trigger?
In generic terms, a Trigger defines an action which will be executed for a given execution when a certain event on a specific resource occurs. For example, we could define a TestTrigger which runs a Test when a ConfigMap gets modified.
In Testkube, Event Triggers allow you to trigger the execution of a Workflow based on Kubernetes Events - for example when a Deployment is updated or an Ingress gets deleted.
You can currently create/manage Event Triggers in the Testkube Dashboard or by interacting with corresponding Trigger custom resources
via kubectl
.
Creating Test Triggers in the Testkube Dashboard
Select the Integrations tab (lightning bolt icon) on the left on the Testkube Dashboard to access the "Triggers" panel which shows a list of Triggers in your Environment.
The "Create a new trigger" on the right allows you create a new trigger as described at create Test Triggers.
Custom Resource Definition Model
Triggers are ultimately defined as Customer Resources in your cluster - TestTrigger Reference
Selectors
Triggers use Selectors to specify which events to listen for.
The resourceSelector
and testSelector
fields support selecting resources either by name or using
the Kubernetes Label Selector.
Each selector should specify the namespace
of the object, otherwise the namespace defaults to testkube
.
selector := resourceSelector | testSelector
Name Selector
Name selectors are used when we want to select a specific resource in a specific namespace.
selector:
name: Kubernetes object name
nameRegex: Kubernetes object name regex (for example, "testworkflow.*")
namespace: Kubernetes object namespace (default is **testkube**)
Label Selector
Label selectors are used when we want to select a group of resources in a specific namespace.
selector:
namespace: Kubernetes object namespace (default is **testkube**)
labelSelector:
matchLabels: map of key-value pairs
matchExpressions:
- key: label name
operator: [In | NotIn | Exists | DoesNotExist
values: list of values
Resource Conditions
Resource Conditions allows triggers to be defined based on the status conditions for a specific resource.
conditionSpec:
timeout: Duration in seconds the test trigger waits for conditions, until its stopped.
delay: Duration in seconds the test trigger waits between condition checks.
conditions:
- type: test trigger condition type
status: test trigger condition status, supported values - True, False, Unknown
reason: test trigger condition reason
ttl: test trigger condition ttl
Resource Probes
Resource Probes allows triggers to be defined based on the probe status.
probeSpec:
timeout: Duration in seconds the test trigger waits for probes, until its stopped.
delay: Duration in seconds the test trigger waits between probes.
probes:
- scheme: test trigger condition probe scheme to connect to host, default is http
host: test trigger condition probe host, default is pod ip or service name
path: test trigger condition probe path to check, default is /
port: test trigger condition probe port to connect
headers: test trigger condition probe headers to submit
Supported Values
- Resource -
pod
,deployment
,statefulset
,daemonset
,service
,ingress
,event
,configmap
- Action -
run
- Event -
created
,modified
,deleted
- Cause (can be used instead of Event)
- For deployments -
deployment-scale-update
,deployment-image-update
,deployment-env-update
,deployment-containers-modified
- For Testkube events -
event-start-test
,event-end-test-success
,event-end-test-failed
,event-end-test-aborted
,event-end-test-timeout
,event-start-testsuite
,event-end-testsuite-success
,event-end-testsuite-failed
,event-end-testsuite-aborted
,event-end-testsuite-timeout
,event-queue-testworkflow
,event-start-testworkflow
,event-end-testworkflow-success
,event-end-testworkflow-failed
,event-end-testworkflow-aborted
,event-created
,event-updated
,event-deleted
- For deployments -
- Execution -
test
,testsuite
,testworkflow
- ConcurrencyPolicy -
allow
,forbid
,replace
Events and values related to Tests and Test Suites have been deprecated and will be removed - Read More
Examples
On Deployment Update
Here is an example for a Test Trigger default/testtrigger-example which runs the TestSuite frontend/sanity-test when a deployment containing the label testkube.io/tier: backend gets modified and also has the conditions Progressing: True: NewReplicaSetAvailable and Available: True.
apiVersion: tests.testkube.io/v1
kind: TestTrigger
metadata:
name: testtrigger-example
namespace: default
spec:
resource: deployment
resourceSelector:
labelSelector:
matchLabels:
testkube.io/tier: backend
event: modified
conditionSpec:
timeout: 100
delay: 2
conditions:
- type: Progressing
status: "True"
reason: "NewReplicaSetAvailable"
ttl: 60
- type: Available
status: "True"
probeSpec:
timeout: 50
delay: 1
probes:
- scheme: http
host: testkube-api-server
path: /health
port: 8088
headers:
X-Token: "12345"
- host: testkube-dashboard
port: 8080
action: run
execution: testworkflow
concurrencyPolicy: allow
testSelector:
name: sanity-test
namespace: frontend
disabled: false
On Testkube Cluster Event
You can define Test Trigger for Testkube cluster events.
In below example, if TestWorkflow k6-executor-smoke
is completed succesfully, then we run TestWorkflow postman-smoke-tests
apiVersion: tests.testkube.io/v1
kind: TestTrigger
metadata:
name: testtrigger-event
namespace: testkube
spec:
resource: event
resourceSelector:
name: k6-smoke-test
event: event-end-test-success
action: run
execution: testworkflow
testSelector:
name: postman-smoke-tests
namespace: testkube
Disabling Test Triggers
Disabling test triggers can be helpful to test your configuration during the development. Testkube lets you disable them via
the API or modifying the CRD directly specifying disabled
field value as true
.
By default, test triggers are enabled on creation.
Architecture
Testkube uses Informers to watch Kubernetes resources and register handlers on certain actions on the watched Kubernetes resources.
Informers are a reliable, scalable and fault-tolerant Kubernetes concept where each informer registers handlers with the Kubernetes API and gets notified by Kubernetes on each event on the watched resources.
API
Testkube exposes CRUD operations on test triggers in the REST API. Check out the OpenAPI docs for more info.
Injected Environment Variables
The following environment variables are automatically injected into each triggered test pod:
WATCHER_EVENT_RESOURCE
: resource typeWATCHER_EVENT_NAME
: resource nameWATCHER_EVENT_NAMESPACE
: resource namespaceWATCHER_EVENT_EVENT_TYPE
: event type