Software development environment

This page gives instructions and hints for setting up a development environment and then develop, test, and deploy your software changes in that environment. This material was presented at the 11 September 2023 New Contributors meeting. You can view the video here.

To prepare to contribute to the Keptn project, we recommend that you:

Study the Keptn documentation to understand what Keptn does and how it works.
Familiarize yourself with the lifecycle-toolkit repository, which is the primary repository for Keptn software and documentation. In particular, study the sections for the four main Keptn components:
Each of these is described in the Components section of the documentation and most include a README file with more information.
Study the material in Technologies and concepts you should know.
Create an account for yourself on GitHub if you do not already have an account.
Set up a fork of the lifecycle-toolkit repository to use with your development.

View repository

When you view the lifecycle-toolkit repository, you see that Keptn is composed of multiple components, each of which is discussed in the Architecture Components documentation:

Three Kubernetes operators
- metrics-operator
- lifecycle-operatory
- cert-manager
Keptn scheduler

At the top level of the repository, you also see the runtimes directory. This defines the runners that you can use when defining tasks to be run either pre- or post-deployment. These are discussed in Runners and containers.

Install software

To test and develop software for the Keptn project, you need to install the following on your system:

Docker: a tool for containerization, which allows software applications to run in isolated environments and makes it easier to deploy and manage them.
A Kubernetes cluster running an appropriate version of Kubernetes. See Supported Kubernetes versions for details. Most contributors create a local Kubernetes-in-Docker(KinD) cluster. This is adequate for developing software for Keptn. See Kubernetes cluster for instructions.
kubectl: a command-line interface tool used for deploying and managing applications on Kubernetes clusters.
kustomize: a tool used for customizing Kubernetes resource configurations and generating manifests.
Helm: a package manager for Kubernetes that simplifies the deployment and management of applications on a Kubernetes cluster.
Go-lang: the language used to code the Keptn software.

First steps

Follow the instructions in Fork and clone the repository to get a local copy of the software.
Keptn provides a tool that deploys the development version of the software on your Kubernetes cluster and pushes the built image to your private repository. You identify your private repository with the RELEASE_REGISTRY= argument and can add any TAG arguments you like. You can also specify the architecture by setting the ARCH argument, which is set to amd64 by default. For example, the following command builds the environment and pushes the image to the docker.io/exampleuser DockerHub repository:

make build-deploy-dev-environment RELEASE_REGISTRY=docker.io/exampleuser TAG=main ARCH=arm64

The build commands are defined in the Makefile located in the root directory of your clone. This file includes a number of environment variables that can be specified as required.

After this runs, verify that pods are running on your Kubernetes cluster for the four components of the product.

Code your changes

You are now ready to make your changes to the source code.

Follow the instructions in Create local branch to create a branch for your changes.
Make your changes to the appropriate component.
Deploy the component you modified and push the image to your private Github repository. Note that you only need to rebuild the component you modified; you do not need to rebuild all components. For example, if your modifications are to the metrics-operator, run:
```
make build-deploy-metrics-operator \
    RELEASE_REGISTRY=docker.io/exampleuser TAG=my-feature
```

Testing

Keptn includes a set of tests that are run on each PR that is submitted. We require that all changes pass unit tests, component tests, end-to-end tests, and integration tests before you create a PR with your changes.

If your change introduces a new feature, you may need to update the test suites to cover your changes. These tests use basic go-library, Ginkgo or chainsaw tests. You can ask the maintainers to tell you where to put your additional test data.

Tests are run on your local machine. Study the detailed log that is produced to identify why the test failed. Study these errors, modify your code, and rerun the test until it passes.

Unit tests

Use your IDE to run unit tests on your code.

Integration tests

Run the integration tests from the root directory of your clone:

make integration-test-local

This runs a series of chainsaw (chainsaw) tests locally and then cleans up your local environment. You can run individual tests with the chainsaw test command; see the Makefile for the specific syntax of each test.

Component test

From the lifecycle-operator directory, run the component tests:

make component-test

End-to-end test

From the lifecycle-operator or scheduler directory, run the end-to-end tests:

make e2e-test

Create and manage the PR

When all the tests have passed, you can follow the instructions in Create PR to create your PR. Be sure to monitor your PR as discussed in PR review process until it is merged.