There are multiple ways on how to interact with the Keptn control-plane. Besides the Keptn API and Keptn CLI, there are more options how external tools can make use of the orchestration capabilities of Keptn. Those external tools can be triggered by Keptn and therefore integrated into a Keptn sequence execution.
In the following sections we look at different use cases to help you get started. If your use case is not listed, have a look at the generic option of Keptn service templates or feel free to start a conversation in the #keptn-integrations channel in the Keptn Slack.
In general, Keptn integrations (also called Keptn-services) integrate by receiving and sending events from and to the Keptn control-plane. Once an integration is triggered, the integration (service) usually indicates its start and once completed, responds to the Keptn control-plane with a finished status. Some integrations, such as notifications (e.g., via Slack), might not want to indicate their progress, which is also possible. In the following, we will have a look at different use cases for integrations and how they can be implemented.
Usually, a testing tool integration is getting triggered upon a
sh.keptn.event.test.triggered event. This event is sent by the Keptn control-plane and the tool integration only has to listen for this type of event. In order to make sure that this event is sent by the Keptn control-plane, a
test task needs to be present in the shipyard.
Example shipyard with a test task in each sequence:
apiVersion: spec.keptn.sh/0.2.3 kind: "Shipyard" metadata: name: "test-shipyard" spec: stages: - name: "test-automation" sequences: - name: "functionaltests" tasks: - name: "test" # your integration gets triggered here properties: teststrategy: "functional" - name: "evaluation" - name: "performancetests" tasks: - name: "test" # your integration gets triggered here properties: teststrategy: "performance" - name: "evaluation" ...
Please note: In general the task can be renamed. However, the important part is that both the event type and the task name correlate with your integration.
*.jmxfile for JMeter or
locustfile.pyfor Locust. These files must be added to Keptn and will be managed by Keptn. Files can be added to Keptn via the keptn add-resource Keptn CLI command. For example, if we have a project sockshop with a carts microservice, the following command adds the local resource
locustfile.pyto Keptn for each of the two sequences mentioned in our shipyard.
keptn add-resource --project=sockshop --stage=test-automation --service=carts --resource=./locustfile.py --resourceUri=locust/locustfile.py
test task is defined in the shipyard and the test definitions are added to Keptn, the integration must subscribe to the test events. Depending on how your integration is built, this can be done by adding the subscription either in the distributor or to the job-executor definition.
Since the tests might run for some time, it is important that once the integration receives the
sh.keptn.event.test.triggered event, it will respond with a
sh.keptn.event.test.started event, and once finished it sends a
Let us have a look at notification tool integrations such as Slack, or MS Team where you want to push (specific) events to a channel to notify members of it.
Usually, a notification tool reacts to a specific type of event or a set of events. The tool integration subscribes to these event types and then sends a defined payload to the channels. Consequently, there is no need to indicate that a notification integration starts and finishes the distribution of messages (i.e., no
*.finished event is required).
The easiest way to set up such an integration is by configuring a Webhook Integration.
The integration of tools with the Keptn control-plane is not limited to specific use cases. Any tool can be integrated by interacting with the Keptn control-plane via CloudEvents. As an inspiration, please have a look at the Keptn sandbox repository that lists community contributions of all kinds. A lot of them have been using the Keptn service template as a starting point, however, please have a look in the next section on different ways how to integrate with Keptn.
The Keptn community currently provides two Keptn service templates:
The service templates provide the best starting point for integrations that need to stay in full control of how they integrate with the Keptn control-plane while still making use of some utility functions. It is also best for integrations where business logic goes beyond a single execution of an action. For example, the Keptn service templates can handle a check that combines authentication, execution, status check, error handling, etc.
The Keptn job executor is appropriate for integrations that can be executed via the command-line interface. The job executor handles the interaction with the Keptn control-plane for sending
*.finished events and can provide a list of files (e.g., test instructions) that are needed for integrations. Find all information regarding the capabilities and usage of the job executor in its Github repository.
The generic-executor-service allows users to provide
.sh (shell scripts),
.py (Python3) or
.http (HTTP Request) files that are executed when Keptn sends different events, such as executing a specific script when a deployment-finished event is sent.