Onboarding a Service

Shows you how to onboard the carts service including its database to a Keptn-managed project. Besides, this tutorial shows how to deploy a new version of carts via Keptn.

About this tutorial

The goal of this tutorial 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. After creating the project, the service that is going to be managed by Keptn needs to be onboarded. Finally, an artifact of the carts service will be deployed by Keptn.

Prerequisites

• The endpoint and API token provided by the Keptn installation.

• Clone example files used for this tutorial:

  git clone --branch 0.6.2 https://github.com/keptn/examples.git --single-branch
  

  cd examples/onboarding-carts
  

Authenticate Keptn CLI

If you have not yet authenticated 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.

• The Keptn CLI needs to be authenticated against the Keptn server by executing the auth command:

  keptn auth --endpoint=https://api.keptn.$(kubectl get cm -n keptn keptn-domain -ojsonpath={.data.app_domain}) --api-token=$(kubectl get secret keptn-api-token -n keptn -ojsonpath={.data.keptn-api-token} | base64 --decode)
  

Create project sockshop

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

stages:
  - 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"
    remediation_strategy: "automated"

Note: To learn more about a shipyard file, please take a look at the Shipyard specification.

• Create a new project for your services 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 examples/onboarding-carts folder.

• Besides, the Git user (--git-user), an access token (--git-token), and the remote URL (--git-remote-url) are required. If a requirement is not met, go to select Git-based upstream where instructions for GitHub, GitLab, Bitbucket, and an Azure DevOps Repos are provided.

keptn create project sockshop --shipyard=./shipyard.yaml --git-user=GIT_USER --git-token=GIT_TOKEN --git-remote-url=GIT_REMOTE_URL

keptn create project sockshop --shipyard=./shipyard.yaml

Onboard carts service and carts database

After creating the project, services can be onboard to this project.

• Onboard the carts service using the keptn onboard service command:

keptn onboard service carts --project=sockshop --chart=./carts

• After onboarding the service, tests (i.e., functional- and performance tests) need to be added as basis for quality gates in the different stages:

  • Functional tests for dev stage:

  keptn add-resource --project=sockshop --stage=dev --service=carts --resource=jmeter/basiccheck.jmx --resourceUri=jmeter/basiccheck.jmx
  

  • Performance tests for staging stage:

  keptn add-resource --project=sockshop --stage=staging --service=carts --resource=jmeter/load.jmx --resourceUri=jmeter/load.jmx
  

  Note: You can adapt the tests in basiccheck.jmx as well as load.jmx for your service. However, you must not rename the files because there is a hardcoded dependency on these file names in the current implementation of Keptn’s jmeter-service.

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

• Onboard the carts-db service using the keptn onboard service command. The --deployment-strategy flag specifies that for this service a direct deployment strategy in all stages should be used regardless of the deployment strategy specified in the shipyard. Thus, the database is not blue/green deployed.

keptn onboard service carts-db --project=sockshop --chart=./carts-db --deployment-strategy=direct

During the onboarding of the services, Keptn creates a namespace for each stage based on the pattern: projectname-stagename.

• To verify the new namespaces, execute the following command:

kubectl get namespaces

NAME                  STATUS   AGE
...
sockshop-dev          Active   2m16s
sockshop-production   Active   2m16s
sockshop-staging      Active   2m16s

Send new artifacts and watch Keptn doing the deployment

After onboarding the services, a built artifact of each service can be deployed.

• Deploy the carts-db service by executing the keptn send event new-artifact command:

keptn send event new-artifact --project=sockshop --service=carts-db --image=docker.io/mongo --tag=4.2.2

• Deploy the carts service by specifying the built artifact, which is stored on DockerHub and tagged with version 0.11.1:

keptn send event new-artifact --project=sockshop --service=carts --image=docker.io/keptnexamples/carts --tag=0.11.1

• Go to Keptn Bridge and check which events have already been generated. If you have not exposed the Bridge yet, execute the following command:

keptn configure bridge --action=expose

• The Keptn Bridge is then available on: https://bridge.keptn.YOUR.DOMAIN/

  It shows all deployments that have been triggered. On the left-hand side, you can see the deployment start events (i.e., so-called Configuration change events). During a deployment, Keptn generates events for controlling the deployment process. These events will also show up in Keptn’s Bridge. Please note that if events are sent at the same time, their order in the Keptn’s Bridge might be arbitrary since they are sorted on the granularity of one second.

  

• Optional: Verify the pods that should have been created for services carts and carts-db:

kubectl get pods --all-namespaces | grep carts

sockshop-dev          carts-77dfdc664b-25b74                            1/1     Running     0          10m
sockshop-dev          carts-db-54d9b6775-lmhf6                          1/1     Running     0          13m
sockshop-production   carts-db-54d9b6775-4hlwn                          2/2     Running     0          12m
sockshop-production   carts-primary-79bcc7c99f-bwdhg                    2/2     Running     0          2m15s
sockshop-staging      carts-db-54d9b6775-rm8rw                          2/2     Running     0          12m
sockshop-staging      carts-primary-79bcc7c99f-mbbgq                    2/2     Running     0          7m24s

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 the carts service. In the production namespace, you should receive an output similar to this: