How to integrate your tool?

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, we’ll have a 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.

General overview

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.

Use Cases

Testing tools

Integrating (load and performance) test tools such as JMeter, Neoload, Artillery, Locust, etc. is a common use case in Keptn. In this section, we will learn what is needed to integrate such tools.

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.

• Typically, test tools rely on some way of test definition files, such as a *.jmx file for JMeter or locustfile.py for Locust. These files have to be added to Keptn and will be managed by Keptn. Files can be added to Keptn via the keptn add-resource Keptn CLI command. Let us assume we have a project sockshop with a carts microservice, the following command will add the local resource locustfile.py to Keptn in both the two sequences mentioned in our shipyard.

keptn add-resource --project=sockshop --stage=test-automation --service=carts --resource=./locustfile.py --resourceUri=locust/locustfile.py

• Once a test task is defined in the shipyard, and the test definitions are added to Keptn, the integration needs to subscribe for the test events. Depending on how your integration is built, this can be done either via adding the subscription 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 sh.keptn.event.test.finished event.

Notification tools

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 will subscribe to these event types and then send 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 *.started or *.finished event has to be sent).

• The easiest way to set up such an integration is by configuring a Webhook Integration.

Tools for your use cases

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.

Integration options

Service Templates

The Keptn community currently provides two Keptn service templates:

1. Keptn service template written in Go
2. Keptn service template written in Python

The service templates provide the best starting point for integrations that need to stay in full control how to integrate with the Keptn control-plane while still making use of some utility functions. It is also best for integrations which business logic goes beyond a single execution of an action. For example, if an authentication, execution, status check, error handling, etc are needed, the Keptn service templates allow handling this.

Job Executor

The Keptn job executor is used best for integrations that can be executed via the command-line interface. The job executor will handle the interaction with the Keptn control-plane for sending *.started and *.finished events and is able to 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.

Generic Executor

The purpose of the generic-executor-service is to allow users to provide either .sh (shell scripts), .py (Python3) or .http (HTTP Request) files that will be executed when Keptn sends different events, e.g: you want to execute a specific script when a deployment-finished event is sent.

Webhook Integration

Please see the detailed description provided here.