Home / Keptn v1 Docs / Release 1.y.z / Manage Keptn Projects / Plan your project
It is useful to think about what you want your Keptn project to do before you begin implementing it. This page summarizes some things you should consider. You can then use the Create project page for instructions about implementing a project.
It is important to understand that a Keptn project is not a pipeline. Instead, activities are triggered by specific events. For a broader explanation of this, you can read the seminal Continuous Delivery without pipelines – How it works and why you need it article.
Before you can run the Keptn command to create a project,
you must populate a shipyard.yaml file
that at least defines the
stages for your project.
At the current time, it is not possible to add or remove stages
after you create your project.
A stage defines the stages and sequences of tasks that your Keptn project can orchestrate. The shipyard.yaml file you use to create a project must show the stages to be used – at least one stage is required but most projects have multiple stages – and each stage must have a name property defined. For example, a shipyard.yaml file like the following is enough to create the project:
apiVersion: spec.keptn.sh/0.2.3 kind: "Shipyard" metadata: name: "shipyard-sockshop" spec: stages: - name: "dev" - name: "hardening" - name: "production"
You can add the sequences and tasks for the project to the shipyard either before or after you create the project.
stage corresponds to a phase in your Continuous Delivery process.
Each stage that is defined for the project
becomes a branch in the upstream repo when you create the project.
A stage can be given any meaningful name
that conforms to the naming rules described in the
shipyard.yaml reference page;
some common stage types are:
qa-java-appstage for testing your Java application and a
validate-databasestage for testing the associated database.
The Define a Project section contains pages about how to implement the different types of stages.
Projects frequently need to deploy an application.
The initial design of Keptn uses the
to deploy such applications with Helm charts.
In earlier releases, the
helm-service was included when Keptn was installed.
For current Keptn versions, you must install the
see Install Execution Plane.
To implement blue-green deployments with the
you must also install Istio;
see Install and configure Istio.
This approach works for all releases of Keptn
and is discussed in more detail on the
Deployment with Helm page..
If you want to deploy your application from an existing Helm registry,
you can still use the
helm-service to deploy your application
by creating an external automation step that packages the
.tgz Helm chart
and pushes it to the Keptn configuration repository
as part of your CI, before initiating the Keptn sequence.
A better approach is to use the
Helm Job Executor Integration
to deploy your Helm chart.
You will still need to install Istio if you are doing blue-green deployment
but you do not need Istio if you are implementing user-managed delivery.
You could intead use the Job Executor Service (JES)
helm directly to deploy your application from your registry.
Tools such as Argo and Flux are better at deployment so you might choose to have Keptn call one of these tools to do the actual deployment. See Orchestrate ArgoCD from Keptn for notes about how to use ArgoCD with Keptn and Orchestrate Argo Rollouts from Keptn for information about using Argo Rollouts. You could use a similar approach for other tools.
You may also want to investigate the inclubating Keptn Lifecycle Toolkit (KLT) project. Because tools such as Argo and Flux do a better job of deployment, the KLT leverages such tools to bring deployment lifecycle observability into your existing delivery process in a way that is more straight-forward and better conforms to the GitOps model.
Keptn orchestrates what to do. You can integrate almost any tool you like to define how this task is accomplished. You must identify each tool you use to Keptn; this can be done in a variety of ways. See Keptn and other tools for more information.
When integrating certain tools with Keptn, you have a choice of having your tool call Keptn or having Keptn call your tool. For example, you may have a Jenkins Pipeline that builds and tests your software. You want Keptn to take that artifact and run an evaluation before deploying the software. You can either have Jenkins call Keptn or you can have Keptn call Jenkins.
The preferred solution for current Keptn releases is be to use
Keptn Webhooks to have Keptn call Jenkins.
This is easier to implement, allows you to break up your Jenkins Pipeline,
and you get the
evaluation “for free”.
For example, you can define a Keptn sequence that you can trigger like this:
sequence: - name: doMyDeployment tasks: - name: "deploy" - name: "evaluation" - name: "test"
Then configure the Keptn webhook service to fire on the
and have Jenkins return the
Keptn automatically runs your
quality gate evaluation when it receives the event.
When the evaluation is finished, Keptn triggers the
You could again use the Keptn webhook service to trigger Jenkins
to implement any test you wanted.
The Trigger Webhook Integrations from Keptn video shows how to trigger Jenkins from a Jenkins task inside a sequence. This is also documented on the Jenkins Integration page.
You can instead have Jenkins call Keptn. This is the only implementation that is supported for Keptn 0.12.x and earlier releases. To do this, use the Jenkins Shared Library integration.
To implement this functionality:
stagewith a Keptn
sequencethat includes a single
This approach is more difficult to implement and provides less functionality than using the Keptn webhooks strategy described above.
Most projects use quality gates to evaluate their software. See Quality Gates for more information. You can (and probably will) modify the details of your quality gates as you test and develop your project but it is useful to consider your goals from the beginning.
If you are using quality gates, you need to consider the following:
What are you using for your data provider, also called the SLI provider? An SLI (Service-Level Indicator) provides quantitative data such as response time. You can use an observability platform (integrations are currently provided for DataDog, Dynatrace, and Prometheus) or you can define another SLI provider by following the instructions in Custom SLI-Provider.
If you are already using an observability platform, you probably want to just configure Keptn to use that tool. If you need to choose a platform, the following may be useful or you can search for other resources:
What are your SLO’s (Service-Level Objectives) for each stage?
For example, for an SLI that measures response time,
you could define an SLO with an absolute value (less than 100ms)
or a relative value (no more than 5% slower than previous evaluations.
Absolute and relative results can be combined into a
total_score for the evaluation.
See SLO for more details.
What service will you use to deploy your artifact for quality gates evaluation?
The most common choice is
See Create a service for more information.
Will you pass your artifact to the next stage (for example, from testing to hardening or from staging to production) automatically if the SLO results meet the specified goals or will you require manual intervention. Note that you can have your project automatically deploy your artifact to the next stage under certain conditions and require manual intervention under other conditions.
A Keptn project can regularly evaluate the production site that runs your deployed software and can provide remediation (“self-healing”) for problems that are found. For example, if the response time is too slow, Keptn could add pods to your Kubernetes cluster. For certain other issues, it could roll back the software to the previous version.
If you want your project to evaluate and remediate issues on your production site, you should consider the following: