Getting started guide. Pre-complete KeptnApp

[agardnerIT]

Today I am walking through the getting started (after a short time away from Keptn).

I am working with Argo so want to explicitly create the KeptnApp rather than relying on the built-in creation mechanism.

The getting started guide has a good template but I must admit, it took me a few attempts to get the fields correct!

Currently it is shown as:

apiVersion: lifecycle.keptn.sh/v1alpha3
kind: KeptnApp
metadata:
  name: <app-name>
  namespace: <app-namespace>
spec:
  version: "x.y"
  revision: x
  workloads:
  - name: <workload1-name>
    version: <version-string>
  - name: <workload2-name>
    version: <version-string>
  preDeploymentTasks:
  - <list of tasks>
  postDeploymentTasks:
  - <list of tasks>
  preDeploymentEvaluations:
  - <list of evaluations>
  postDeploymentEvaluations:
  - <list of evaluations>

Whereas (for the getting started guide specifically), it could be filled out for the user as:

apiVersion: lifecycle.keptn.sh/v1alpha3
kind: KeptnApp
metadata:
  name: keptndemoapp
  namespace: keptndemo
spec:
  version: "x.y.z"
  revision: x
  workloads:
  - name: nginx
    version: 0.0.1
#  - name: <workload2-name>
#   version: <version-string>
#  preDeploymentTasks:
#  - <list of tasks>
#  postDeploymentTasks:
#  - <list of tasks>
#  preDeploymentEvaluations:
#  - <list of evaluations>
#  postDeploymentEvaluations:
#  - <list of evaluations>

Hash comments are deliberate here as it:

1. Hints to possible additional usecases for Keptn
2. Hints that future tutorials will cover these aspects

@prakrit55 would you like to take this on?

[prakrit55]

@agardnerIT, yes with pleasure 🙌

[StackScribe]

I am questioning why we have a copy of the reference material in this Getting Started Guide. The goal is to have the details about each resource in just one place to avoid maintenance headaches but I think it also makes the docs more readable. So you could just link to https://main.lifecycle.keptn.sh/docs/yaml-crd-ref/app/ for the synopsis and field description, then discuss the specifics of the example: "The example defines a KeptnApp resource named podtato-head that includes the podtato-head-left-arm and podtato-head-left-leg workloads. It runs the my-prometheus-definition evaluation before the KeptnApp is deployed and the post-deployment-hello task after the KeptnApp is deployed.

You could replace evaluation and task with links to the appropriate reference pages. Also good to link to https://main.lifecycle.keptn.sh/docs/implementing/integrate/#use-keptn-automatic-app-discovery for more information about how the auto app generation feature works and be more specific about what is done automatically
and what is not. I think you can autogenerate the KeptnApp to include the workloads, then edit it to add tasks and evaluations.

We have guide material about all of this in the User Guides section (https://main.lifecycle.keptn.sh/docs/implementing/ )

Also a heads-up -- I have an open PR (#2294) that will hopefully be merged in 12 hours or so that moves the path of this file -- we'll have a "Getting started" section and this will be in that section along with the exercise for tasks and something about Keptn Metrics -- the latter needs to be redone but, for now, it's the best we have.

Holler if you need help with any of this.

[prakrit55]

I am questioning why we have a copy of the reference material in this Getting Started Guide. The goal is to have the details about each resource in just one place to avoid maintenance headaches but I think it also makes the docs more readable. So you could just link to https://main.lifecycle.keptn.sh/docs/yaml-crd-ref/app/ for the synopsis and field description, then discuss the specifics of the example: "The example defines a KeptnApp resource named podtato-head that includes the podtato-head-left-arm and podtato-head-left-leg workloads. It runs the my-prometheus-definition evaluation before the KeptnApp is deployed and the post-deployment-hello task after the KeptnApp is deployed.

You could replace evaluation and task with links to the appropriate reference pages. Also good to link to https://main.lifecycle.keptn.sh/docs/implementing/integrate/#use-keptn-automatic-app-discovery for more information about how the auto app generation feature works and be more specific about what is done automatically and what is not. I think you can autogenerate the KeptnApp to include the workloads, then edit it to add tasks and evaluations.

We have guide material about all of this in the User Guides section (https://main.lifecycle.keptn.sh/docs/implementing/ )

Also a heads-up -- I have an open PR (#2294) that will hopefully be merged in 12 hours or so that moves the path of this file -- we'll have a "Getting started" section and this will be in that section along with the exercise for tasks and something about Keptn Metrics -- the latter needs to be redone but, for now, it's the best we have.

Holler if you need help with any of this.

Hey @StackScribe acc. to #2116, we created the KeptnApp reference in "Getting Started Guide" to persuade users to create the KeptnApp on their own since the KeptnApp is autogenerative but what you suggested is a best practice and I wd like to hear from @agardnerIT too. Thanks.

[StackScribe]

Hey @prakrit55 Thanks for the response. As I understand it, even if one wants the pre/post deployment stuff, one can (should) autogenerate the KeptnApp resource to get the basics in place, then edit the yaml file to add the pre-/post- lines; it may be necessary to oyaml the resource to create the yaml file -- the user guide and ref page may need to be updated to reflect this. And we should confirm that this works. Frankly, I think that most people who DO create the KeptnApp manually are just going to copy one of the sample files, either from a sample repo or the docs, then modify them. So they aren't going to look up the details about each field, just look something up when they have a question.

Of course, I have a strong writer's bias here so feel free to push back, but I think that part of the job of "Getting started" guides is to introduce the user to the full doc set so they are a bit familiar and know where to look when they need information. Of course, we don't want to bury them with details before they can get something up and running so it's a fine line and worth discussion...

[mowies]

IMHO this ticket should not be implemented. The getting started guide is for DORA metrics, it doesn't really talk about KeptnApps or how they work at all. So I really don't think the KeptnApp addition fits into that guide at all. There could a separate guide for it, but the getting started guide as it is is already crazy long and just on a different topic.
(of course KeptnApps are somewhat related to DORA metrics but not really that much to open that pandora's box as well in this guide)

@agardnerIT

[mowies]

I also don't see how working with Argo is really related to the getting started guide. The whole guide mentions GitOps once, in the first line and then never again. Also, the guide is imperative which is IMO the opposite of GitOps altogether, so why would we change anything in that regard?
IMO it's good that the guide is imperative, otherwise we would need a completely different angle if we want to talk about Argo in there.

[mowies]

Putting this on hold until the discussion here is resolved.

[StackScribe]

We discussed this in the Community Meeting and agreed that duplicating the content of the KeptnApp reference page in the Getting Started exercise is ill-advised for two reasons: (1) This should be a simple introductory exercise, not a comprehensive guide and (2) Duplicating information complicates the maintenance of the docs and almost guarantees that the two copies will get out of sync at some time.

We have the Deployment Tasks guide and a couple others that go into much more detail -- one also has to deal with runners and context and parameterized functions and maybe secrets. I am working on #2601 and will delete the KeptnApp reference details and replace them with a list of "To learn more" references. The Getting Started guides should be simple, high-level exercises that they show the path to the other documents for additional information.

@agardnerIT I would love to develop a guide for using Keptn with ArgoCD. I don't know that we need to go to the effort of creating a getting started for that but we can discuss. I'm thinking just a regular guide where we can lay out the steps required, issues, etc is more useful. Shall we collaborate -- if you feed me the salient points, I can write it up.

Meanwhile, I am closing this issue.