KLT Migration Guide

[StackScribe]

Goal

We need a Migration Guide to help Keptn v1 users migrate to KLT.

Problem

Because KLT represents a major paradigm shift from Keptn v1, migration is never going to be a process we can define with a series of "cookbook" steps. Instead, I suggest that we create a section in the KLT documentation that contains a series of articles about how to migrate various features and use-cases. We can start by setting down what we know and ideas we have then grow the information as we learn more.

Update from 2 August 2023

With the limited number of adopters for V1, continued development of the Migration Guide is not worth the effort. We can focus on new adopters, features and documentation.

• We should complete sections of the migration guides that are nearly done. This is basically the "Migration strategy" page that is nearly ready to be merged and summarizes the paradigm switch between V1 and KLT.
• For use cases that are not started or little work has been done, we will have a link to the installation guides (actually, to the doc set in general), and recommend that Users reach out by email or slack in case they need to migrate. We can then write these if users approach us to migrate if no one approaches we can leave them as they are.

Technical Details

This must be a "crowd-sourced" effort to succeed. Meg will begin writing up what she can, asking that anyone with ideas or suggestions add them as a comment to this epic. The hope is that, by 0.9.0, we will have enough structure to include this in the published doc set as a work-in-progress. At that time, we create a #klt-migration slack channel and solicit questions and experiences from the broader community.

DoD

The Migration Guide should not duplicate information about how to use KLT features but should instead reference the documentation for basic information about how to do a certain task or use a certain feature and then discuss how one migrates Keptn v1 practices to KLT.

• Landing page -- outline the migration process -- steps to take, in order, when to run what tests. These are guidelines not strict steps, of course, and may actually be similar to the steps for implementing KLT "from scratch", except that we have not (yet) written that up.
• Evolution of Keptn -- start by transcribing text from Andi's Pakistan presentation
  • Why you should migrate to KLT -- helm-service and multi-stage delivery
  • Who should not migrate to KLT -- identify features that Keptn v1 supports that KLT does not support. And include a blurb that people can continue to contribute to and grow Keptn v1 but this will require community leadership
• General migration strategy -- discuss the paradigm switch and provide basic mapping of Keptn v1 components to KLT resources, etc to help users architect the implementation they want to have when the migration process is complete
• Migrating Continuous Delivery with KLT
• Migrating Quality Gates to Evaluations -- full-fledged quality gates are not currently available in KLT but many simple evaluations can be implemented with Keptn metrics and Keptn evaluations. Show how to transform SLIs to KeptnMetrics and SLOs to KeptnEvaluations.
• Use Container Runtimes for tasks run with JES -- container-runtime runner should be able to accommodate many things run in Keptn v1 JES; discuss this, give examples, and identify things that may not work
• Migrating remediation services to Day 2 evaluations -- KLT does not support remediation services at the level Keptn v1 does but some remediation can be implemented using post-deployment evaluations and tasks as Day 2 evaluations. And evaluation of the production system can be implemented for anything available as a KeptnMetric resource. The type and quality of information provided depends on the data source being used. Some remediation is provided through HPA and sending slack messages

Tasks

Preview Give feedback

1. Evolution of Keptn #1502
   documentation stale +2
   
2. Who should use KLT and who should use Keptn v1 #1555
   documentation stale +2
   
3. How to migrate JES functionality to a KeptnTaskDefinition container #1556
   documentation stale +2
4. Migrating Continuous Delivery with KLT #1557
   documentation stale +2
5. How to create KeptnEvaluationDefinition from quality gates #1558
   documentation +1
6. How to create Day 2 evaluations on KLT #1559
   documentation stale +2
7. how to define KeptnMetricsProvider resources for data sources #1609
   documentation +1
   
8. migration: set up k8s deployment environment #1624
   documentation +1
   
9. conceptual mapping of Keptn v1 components to KLT resources, etc #1630
   documentation +1
   
10. how to create KeptnMetric resources from SLIs #1651
    documentation +1
    
11. migration: install, enable, integrate, and create KeptnApp #1652
    documentation +1
    
12. How to implement task based on evaluation results #1829
    documentation +1
    

[agardnerIT]

Technically KLT is still a subproject. A discussion needs to occur publicly that the community agrees to move KLT to the "main" project rather than as a subproject.

Perhaps this KEP covers the above, but then we need to remove references to KLT being a subproject.