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:

  • lifecycle-operator
  • metrics-operator
  • scheduler
  • keptn-cert-manager

  Each of these is described in the Architecture 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 Architecture 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

1. Follow the instructions in Fork and clone the repository to get a local copy of the software.

2. 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. For example, the following command builds the environment and pushes the image to the docker.io/exampleuser github repository:

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

   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.

3. 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.

1. Follow the instructions in Create local branch to create a branch for your changes.

2. Make your changes to the appropriate component.

3. Deploy the component you modified and push the image to your private Github repository. Note that you do not need to rebuild all components, only the one you modified. 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 KUTTL 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.

1. Use your IDE to run unit tests on your code.

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

   make integration-test-local
   

   integration-test-local cleans up after the test.

3. From the lifecycle-operator directory, run the component test:

   make component-test
   

4. From the lifecycle-operator 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.