Note This section is under development. Information that is published here has been reviewed for technical accuracy but the format and content is still evolving. We hope you will contribute your experiences and questions that you have.
Before you begin the migration project, we suggest that you run through the exercises in Getting started to familiarize yourself with how Keptn works. When you are ready to begin the migration, follow the instructions in Installation and upgrade to set up your Kubernetes cluster and install Keptn on it.
On this page, we discuss some of the major paradigm shifts in Keptn relative to Keptn v1 and then discuss how elements of your Keptn v1 can be implemented for Keptn.
The Keptn cloud native paradigm
Keptn uses a different paradigm than Keptn v1 and so migration requires technical adjustments. Much of the logic and functionality of your Keptn v1 projects can be migrated to Keptn but must be rewritten to utilize Keptn components.
Some key points:
Keptn uses native Kubernetes CRDs to configure SLIs/SLOs, tasks, and other elements that are part of the environment where the application deployment lives rather than using its own Git repo and its shipyard.yaml file as Keptn v1 does.
Keptn is not a delivery tool because it does not provide promotion. Instead, it works with standard deployment tools such as ArgoCD, Flux, even
kubectl -- apply. Keptn then prevents the scheduling and deployment of workflows if the environment does not meet the user-defined requirements.
Keptn operates on a KeptnApp resource that is an amalgamation of multiple Kubernetes workloads, which together comprise the released application. Each workload deploys a separate microservice, which can be deployed at different times using different tools.
Keptn integrates with continuous delivery tools to insures that a
KeptnAppis not deployed if it does not meet the user-defined requirements for all the associated workloads. It also exposes metrics to evaluate the success/status of a deployment.
Keptn provides an operator that can observe and orchestrate application-aware workload life cycles. This operator leverages Kubernetes webhooks and extends the Kubernetes scheduler to support pre- and post-deployment hooks. When the operator detects a new version of a service (implemented as a Kubernetes Workload), it can execute pre- and post-deployment evaluations and tasks using Kubernetes capabilities.
Keptn provides extensive observability data using OpenTelemetry and Prometheus rather than storing the data in a special Keptn database. This data can be displayed using Grafana and Jaeger or the dashboard of your choice.
For in-depth information about Keptn components and how they work, see the Architecture section.
Disposition of Keptn v1 components in Keptn
To help you wrap your mind around the migration process, this lists Keptn v1 components and identifies their possible disposition when you migrate to Keptn.
A Keptn v1 project represents an arbitrary, higher-level grouping of services. A project is defined by a shipyard.yaml file.
Keptn does not recognize projects.
Many Keptn v1 projects may translate into
but others will not.
For example, if your Keptn v1 project has a large number of services,
you may want to aggregate them into separate
A project has a 1:1 mapping to a Git repo,
but, since few applications are stored in a mono-repo,
it is difficult to implement a project-as-application paradigm.
In general, the Keptn v1 project is a useful as a reference list when migrating to Keptn. but may not directly translate to a Keptn resource.
A Keptn v1 service models a smaller chunk of a project. Most projects include many services. In a micro-services world, a service may represent a micro-service but it could instead be a wrapper for something else, like “the entire public website”
Keptn does not have the concept of a service. When migrating to Keptn, you need to analyze what each service is doing and translate that into an appropriate resource. The closest analogy is a Kubernetes workload but some services may be translated into KeptnTaskDefinition or other resources. See Working with Keptn tasks for more information.
- A Keptn v1 service that runs chaos or load tests
can probably be translated into
- A Keptn v1 service that runs a database
can probably be translated
into a Kubernetes
StateFulSetworkload; see Workload Resources for more information.
- A Keptn v1 service that runs a webserver
can probably be translated into
A stage is a subsection of a project.
Because Keptn is not a delivery tool,
it has no concept of a
but rather depends on a deployment engine.
However, the logic of the stages can be useful
when architecting the migration:
- A deployment stage – may define sequences of tasks that should be translated into KeptnTaskDefinition resources that are executed pre- and post-deployment
- A testing stage may define sequences of tasks
that should be translated into
KeptnTaskDefinitionresources that are executed pre- and post-deployment.
Stage functionality could be implemented in many different ways. Some functionality might be implemented in different namespaces or even in different Keptn-enabled clusters, allowing a tool such as ArgoCD to handle promotion.
A sequence is an ordered and user-defined sequence of tasks
that are defined in a
The shipyard controller micro-service reads the shipyard file
and (when the time is right),
taskName.triggered cloud event onto the event bus.
The shipyard controller waits to receive a
and a correspondingly equal number of
before the shipyard controller reads the next task
and emits a
taskName.finished event for that task.
In this way, you can define arbitrary sequences of any tasks at any length and also link (or chain) sequences together to form (primitive) workflows. When migrating, these sequences of tasks can often be translated into KeptnTaskDefinition resources that are defined to run either pre- or post-deployment of the pod-scheduling phase.
shipyard file is a general purpose workflow engine
that is backed by cloud events.
It is not opinionated to a tool, platform, technology,
or a particular “slice” of the lifecycle.
TriggeredOn property allows
a Keptn v1 sequence to be triggered at any time
by a user or another system.
This capability can be used, for example,
to trigger a data encryption and backup operation,
or a file movement over a network, or other arbitrary activities
that may or may not have anything to do with an application’s lifecycle.
When migrating to Keptn, sequences that are not part of the lifecycle workflow should not be handled by Keptn but should instead be handled by the pipeline engine tools being used such as Jenkins, Argo Workflows, Flux, and Tekton.
Keptn v1 defines some specific types of tasks, each of which is translated to a Keptn resource that is appropriate for the activity:
- A Keptn v1 deployment task becomes a Deployment, StatefulSets, or DaemonSets, workload. You can code KeptnTaskDefinition and KeptnEvaluationDefinition resources that are configured to run either pre- or post-deployment tasks
- An evaluation task becomes a KeptnEvaluationDefinition resource.
- All other standard tasks
(action, approval, get-action, rollback,
as well as custom task types
that might be defined should be translated into
key:valueproperties for each Keptn v1 sequence should be coded into the
KeptnTaskDefinitionresource as appropriate.
Note that all
KeptnTask resources at the same level
(either pre-deployment or post-deployment)
execute in parallel
whereas Keptn v1 sequences and tasks can not execute in parallel.
- If you have actions that need to execute sequentially,
create a single
KeptnTaskDefinitionthat calls each action in order.
- If you have tasks that can execute in parallel, migrating to Keptn may improve the performance of the deployment.
Keptn v1 SLIs (Service Level Indicators) represent queries from the data provider such as Prometheus, Dynatrace, or Datadog, which is configured as a Keptn integration.
When migrating to Keptn, you need to define a KeptnMetricsProvider resource for the data provider(s) you are using. Note that Keptn allows you to support multiple data providers and multiple instances of each data provider for your SLIs whereas Keptn v1 only allows you to use one SLI per project.
The queries defined for the Keptn v1 SLIs should be translated into KeptnMetric resources.
Keptn at this time does not support the full range of Quality Gates evaluations that are represented by SLOs. Facilities such as weighting of SLIs and scoring of the evaluation do not currently exist. This functionality is under development; see Epic 1646.
However, simple evaluations of an SLI can be defined as KeptnEvaluationDefinition resources.
Keptn does not currently support the same level of remediations as Keptn v1 does, but it does provide limited “Day 2” facilities:
- Any query that is possible for your data provider post-deployment
can be defined as a
KeptnMetricDefinition; this is then reported as a Keptn Metric. Evaluation can be defined as a
KeptnMetricsDefinitionresources can be retrieved and used to implement the Kubernetes HorizontalPodAutoscaler (HPA), which can detect the need for additional resources (more pods, memory, disk space, etc.) and automatically add those resources to your configuration based on the
ReplicaSetresources you have defined. See Using the HorizontalPodAutoscaler for more information.
Integrations and services in JES
Most functionality coded using the Keptn v1
(Job Executor Service) facility
can simply be moved into a
that uses the
you may be able to use the
If the JES container code is written in Python 3,
you may be able to use the
Note that there is no need for integrations for data providers in Keptn;
these are configured as