Onboarding a Service

This use case shows how to onboard the carts service including its database. Besides this, a new artifact will be automatically deployed via keptn.

About this use case

The goal of this use case is to automatically deploy a service into a multi-stage environment using keptn. The stages of the environment are described in a shipyard file that defines the name, deployment strategy and test strategy of each stage. In case an additional stage is needed, the shipyard file can be easily extended by a stage definition before creating the project. After creating the project, the service that is going to be managed by keptn needs to be onboarded. Therefore, keptn provides the functionality to create the deployment and service definition of the onboarded service for each stage. Finally, an artifact of the carts service will be deployed by keptn.

To illustrate the scenario this use case addresses, keptn relies on the following services: github-service, helm-service, jmeter-service, and gatekeeper-service. These services have the following responsibilities:


  • Creating a project: When a new project is created, the github service will create a new repository within your configured GitHub organization. This repository will contain the complete configuration (e.g., the image tags to be used for each service within your application) of your application, where the configuration for each stage is located in a separate branch. For the configuration of a keptn-managed app we use Helm Charts.
  • Onboarding a service: When a new service is onboarded to a project (here a manifest file containing the specification for that service is required), the github service will add the service as a new entry in the values.yaml file of your application’s helm chart. Further, depending on the deployment strategy of each stage, the github service will also generate a set of Istio configurations (i.e., a Gateway, DestinationRules, and VirtualServices) to facilitate blue/green deployments. You can read more about this concept at the Istio documentation.
  • Listening to a new artifact event: When the github service receives a new artifact event, it updates the reference to the new artifact in the service configuration. By this, the new image is used for the respective service.


  • Listening to configuration changed events to deploy a service using the new configuration.


  • Listening to deployment finished events to test a newly deployed service using jmeter.


  • Listening to evaluation done events to decide whether the deployment can be promoted to the next stage or not.


  1. A GitHub organization, user, and personal access token, which are used by keptn.

  2. The endpoint and API token provided by the keptn installation.

  3. Git clone artifacts for this use case.

    git clone --branch 0.4.1 https://github.com/keptn/examples.git --single-branch
    cd examples/onboarding-carts
  4. Fork carts example into your GitHub organization

    • Go to https://github.com/keptn-sockshop/carts and click on the Fork button on the top right corner.
    • Select the GitHub organization you use for keptn.
    • Clone the forked carts service to your local machine. Please note that you have to use your own GitHub organization.
      git clone https://github.com/your-github-org/carts.git

Authenticate and configure keptn

If you have not yet authenticated and configured the keptn CLI, please follow these instructions. If you have already done this during the installation, please skip this part and continue with creating a project.

  1. The CLI needs to be authenticated against the keptn server. Therefore, please follow the keptn auth instructions.

    Set the needed environment variables.

    KEPTN_ENDPOINT=https://control.keptn.$(kubectl get cm keptn-domain -n keptn -o=jsonpath='{.data.app_domain}')
    KEPTN_API_TOKEN=$(kubectl get secret keptn-api-token -n keptn -o=jsonpath='{.data.keptn-api-token}' | base64 --decode)

    Authenticate to the keptn server.

    keptn auth --endpoint=$KEPTN_ENDPOINT --api-token=$KEPTN_API_TOKEN
  2. Configure the used GitHub organization, user, and personal access token using the keptn configure command:

    keptn configure --org=<YOUR_GITHUB_ORG> --user=<YOUR_GITHUB_USER> --token=<YOUR_GITHUB_TOKEN>

Create project sockshop

For creating a project, this use case relies on the shipyard.yaml file shown below:

  - name: "dev"
    deployment_strategy: "direct"
    test_strategy: "functional"
  - name: "staging"
    deployment_strategy: "blue_green_service"
    test_strategy: "performance"
  - name: "production"
    deployment_strategy: "blue_green_service"
  • Create a new project for your carts service using the keptn create project command. In this example, the project is called sockshop. Before executing the following command, make sure you are in the folder examples/onboarding-carts.
  keptn create project sockshop shipyard.yaml

Onboard carts service and carts database

After creating the project, you are ready to onboard the first services.

  • Onboard the carts service using the keptn onboard service command. In this onboarding scenario, a default deployment and service template will be provided by the github-service.
  keptn onboard service --project=sockshop --values=values_carts.yaml

Since the carts service needs a mongo database, a second service needs to be onboarded.

  • Onboard the carts-db service using the keptn onboard service command. In this onboarding scenario, the deployment and service files are handed over to the github-service.
  keptn onboard service --project=sockshop --values=values_carts_db.yaml --deployment=deployment_carts_db.yaml --service=service_carts_db.yaml

Note, by onboarding a service without specifying a deployment file, we automatically include a readiness and liveness probe. Therefore, we assume that the onboarded service has an endpoint /health on the internal port 8080. This is true for the carts service used in this use case. In case you would like to onboard your own service, please ensure that your service has an endpoint health, which can be used or define your own readiness and liveness probe in the deployment.

Send a new artifact and watch keptn doing the deployment

  1. Send a new artifact event for the carts service using the keptn send event new-artifact command. The used artifact is stored on Docker Hub.

    keptn send event new-artifact --project=sockshop --service=carts --image=docker.io/keptnexamples/carts --tag=0.8.1
  2. Go to the keptn’s bridge and check which events have already been generated. You can access it by a port-forward from your local machine to the Kubernetes cluster:

    kubectl port-forward svc/bridge -n keptn 9000:8080

    Now access the bridge from your browser on http://localhost:9000.

    The keptn’s bridge shows all deployments that have been triggered. On the left-hand side you can see the deployment start events, such as the one that is selected. Over time, more and more events will show up in keptn’s bridge to allow you to check what is going on in your keptn installation. Please note that if events happen at the same time, their order in the keptn’s bridge might be arbitrary since they are only sorted on the granularity of one second.

    keptn's bridge

View carts service

  • Get the URL for your carts service with the following commands in the respective namespaces:
  echo http://carts.sockshop-dev.$(kubectl get cm keptn-domain -n keptn -o=jsonpath='{.data.app_domain}')
  echo http://carts.sockshop-staging.$(kubectl get cm keptn-domain -n keptn -o=jsonpath='{.data.app_domain}')
  echo http://carts.sockshop-production.$(kubectl get cm keptn-domain -n keptn -o=jsonpath='{.data.app_domain}')

Navigate to the URLs to inspect your carts service. In the production namespace, you should receive an output similar to this:

carts service in production