From bd5d2eb313161ebdadc7953f6ca60447306d4713 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 16 Jun 2023 22:52:41 -0700 Subject: [PATCH 1/3] docs: remove old "Tasks" section from docs Signed-off-by: Meg McRoberts --- .../add-app-awareness/index.md | 0 .../restart-application-deployment/_index.md | 106 +++++++++++------- docs/content/en/docs/tasks/_index.md | 9 -- docs/content/en/docs/tasks/evaluate/_index.md | 8 -- .../implement-slack-notification/_index.md | 39 ------- docs/content/en/docs/yaml-crd-ref/app.md | 8 +- 6 files changed, 71 insertions(+), 99 deletions(-) rename docs/content/en/docs/{tasks => implementing}/add-app-awareness/index.md (100%) rename docs/content/en/docs/{tasks => implementing}/restart-application-deployment/_index.md (56%) delete mode 100644 docs/content/en/docs/tasks/_index.md delete mode 100644 docs/content/en/docs/tasks/evaluate/_index.md delete mode 100644 docs/content/en/docs/tasks/implement-slack-notification/_index.md diff --git a/docs/content/en/docs/tasks/add-app-awareness/index.md b/docs/content/en/docs/implementing/add-app-awareness/index.md similarity index 100% rename from docs/content/en/docs/tasks/add-app-awareness/index.md rename to docs/content/en/docs/implementing/add-app-awareness/index.md diff --git a/docs/content/en/docs/tasks/restart-application-deployment/_index.md b/docs/content/en/docs/implementing/restart-application-deployment/_index.md similarity index 56% rename from docs/content/en/docs/tasks/restart-application-deployment/_index.md rename to docs/content/en/docs/implementing/restart-application-deployment/_index.md index 35799cb52f..6f2264c2b2 100644 --- a/docs/content/en/docs/tasks/restart-application-deployment/_index.md +++ b/docs/content/en/docs/implementing/restart-application-deployment/_index.md @@ -3,32 +3,36 @@ title: Restart an Application Deployment description: Learn how to restart an unsuccessful Keptn Application Deployment. icon: concepts layout: quickstart -weight: 20 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html +weight: 30 +hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- ## Restart an Application Deployment -During the deployment of a `KeptnApp`, it might be that the deployment fails due to an unsuccessful pre-deployment -evaluation or pre-deployment task. -This could happen because of, e.g., a misconfigured target value of a `KeptnEvaluationDefinition`, or a wrong URL being -checked in a pre deployment check. - -To retry a `KeptnApp` deployment without incrementing the version of the `KeptnApp`, we introduced the concept of ** -revisions** for a `KeptnAppVersion`. -This means that -whenever the spec of a `KeptnApp` changes, even though the version stays the same, the KLT Operator will create a new -revision of the `KeptnAppVersion` referring to the `KeptnApp`. - -This way, when a `KeptnApp` failed due to a misconfigured pre-deployment check, you can first fix the configuration of -the `KeptnTaskDefinition`/`KeptnEvaluationDefinition`, then -increase the value of `spec.revision` of the `KeptnApp` and finally apply the updated `KeptnApp` manifest. -This will result in a restart of the `KeptnApp`. -Afterwards, all related `KeptnWorkloadInstances` will automatically refer to the newly -created revision of the `KeptnAppVersion` to determine whether they are allowed to enter their respective deployment -phase. - -To illustrate this, let's have a look at the following example: +A [KeptnApp](../../yaml-crd-ref/app.md] can fail +because of an unsuccessful pre-deployment evaluation +or pre-deployment task. +For example, this happens if the target value of a +[KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md) +resource is misconfigured +or a pre-deployment evaluation checks the wrong URL. + +Use the `spec.revision` field of `KeptnApp` +to retry a `KeptnApp` deployment +without incrementing the version of the `KeptnApp` +After you fix the configuration +that caused the pre-deployment evaluation or task to fail, +you can increment the `spec.revision` value +and apply the updated `KeptnApp` manifest +to create a new revision of the `KeptnApp` +without modifying the `version`. + +Afterwards, all related `KeptnWorkloadInstances` +automatically refer to the newly created revision of the `KeptnAppVersion` +to determine whether they are allowed +to enter their respective deployment phases. + +To illustrate this, consider the following example: ```yaml apiVersion: v1 @@ -95,10 +99,12 @@ spec: value: "9000" ``` -In this example, the `KeptnApp` executes a pre-deployment check which clearly fails due to the `pre-deployment-check` -task, and will therefore not be able to proceed with the deployment. +In this example, the `KeptnApp` executes a pre-deployment check +which clearly fails because of the `pre-deployment-check` task, +and therefore is not able to proceed with the deployment. -After applying this manifest, you can inspect the status of the created `KeptnAppVersion`: +After applying this manifest, +you can inspect the status of the created `KeptnAppVersion`: ```shell $ kubectl get keptnappversions.lifecycle.keptn.sh -n restartable-apps @@ -106,10 +112,12 @@ NAME APPNAME VERSION PHASE podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks ``` -You will notice that the `KeptnAppVersion` will stay in the `AppPreDeployTasks` phase for a while, due to the pre-check -trying to run until a certain failure threshold is reached. -Eventually, you will find the `KeptnAppVersion`'s `PredeploymentPhase` to be in a `Failed` state, with the remaining -phases being `Deprecated`. +Notice that the `KeptnAppVersion` stays +in the `AppPreDeployTasks` phase for a while, +due to the pre-check trying to run +until the failure threshold is reached. +Eventually, the `KeptnAppVersion`'s `PredeploymentPhase` +is in a `Failed` state, with the remaining phases being `Deprecated`. ```shell @@ -119,9 +127,16 @@ podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks Failed ``` -Now, to fix the deployment of this application, we first need to fix the task that has failed earlier. -To do so, edit the `pre-deployment-check` `KeptnTaskDefinition` to the -following (`kubectl -n restartable-apps edit keptntaskdefinitions.lifecycle.keptn.sh pre-deployment-check`): +To fix the deployment of this application, +we first need to fix the task that has failed earlier. +To do so, edit the `pre-deployment-check` `KeptnTaskDefinition`: + + +```shell +kubectl -n restartable-apps edit keptntaskdefinitions.lifecycle.keptn.sh pre-deployment-check +``` + +Modify the manifest to look like this: ```yaml apiVersion: lifecycle.keptn.sh/v1alpha2 @@ -136,9 +151,14 @@ spec: console.error("Success") ``` -After we have done that, we can restart the deployment of our `KeptnApplication` by incrementing the `spec.revision` -field by one -(`kubectl -n restartable-apps edit keptnapps.lifecycle.keptn.sh podtato-head`): +To restart the deployment of our `KeptnApplication`, +edit the manifest: + +```shell +kubectl -n restartable-apps edit keptnapps.lifecycle.keptn.sh podtato-head +``` + +Increment the value of the `spec.revision` field by one: ```yaml apiVersion: lifecycle.keptn.sh/v1alpha2 @@ -156,7 +176,8 @@ spec: - pre-deployment-check ``` -After those changes have been made, you will notice a new revision of the `podtato-head` `KeptnAppVersion`: +After those changes have been made, +you will notice a new revision of the `podtato-head` `KeptnAppVersion`: ```shell $ kubectl get keptnappversions.lifecycle.keptn.sh -n restartable-apps @@ -165,10 +186,12 @@ podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks podtato-head-0.1.1-2 podtato-head 0.1.1 AppDeploy ``` -As you will see, the newly created revision `podtato-head-0.1.1-2` has made it beyond the pre-deployment check phase and -has reached its `AppDeployPhase`. +See that the newly created revision `podtato-head-0.1.1-2` +has made it beyond the pre-deployment check phase +and has reached its `AppDeployPhase`. -You can also verify the execution of the `pre-deployment-check` by retrieving the list of `KeptnTasks` in +You can also verify the execution of the `pre-deployment-check` +by retrieving the list of `KeptnTasks` in the `restartable-apps` namespace: @@ -180,6 +203,7 @@ pre-pre-deployment-check-65056 podtato-head 0.1.1 ``` -You will notice that for both the `KeptnAppVersions` and `KeptnTasks` the previous failed instances are still available, -as this might be useful historical data to keep track of +Notice that, for both the `KeptnAppVersions` and `KeptnTasks`, +the previous failed instances are still available. +This may be useful historical data to keep track of what went wrong during earlier deployment attempts. diff --git a/docs/content/en/docs/tasks/_index.md b/docs/content/en/docs/tasks/_index.md deleted file mode 100644 index 0c47832571..0000000000 --- a/docs/content/en/docs/tasks/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Tasks -description: This section of the documentation describes how to do individual tasks with Keptn. -icon: concepts -layout: quickstart -weight: 40 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - diff --git a/docs/content/en/docs/tasks/evaluate/_index.md b/docs/content/en/docs/tasks/evaluate/_index.md deleted file mode 100644 index d6529b1955..0000000000 --- a/docs/content/en/docs/tasks/evaluate/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Evaluate Metrics -description: Learn how to use the Keptn Lifecycle Toolkit and explore basic features. -icon: concepts -layout: quickstart -weight: 25 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- diff --git a/docs/content/en/docs/tasks/implement-slack-notification/_index.md b/docs/content/en/docs/tasks/implement-slack-notification/_index.md deleted file mode 100644 index c77f37c786..0000000000 --- a/docs/content/en/docs/tasks/implement-slack-notification/_index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Implement Slack Notification -description: Learn how to implement Slack notification as a post deployment task. -icon: concepts -layout: quickstart -weight: 24 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - -## Create Slack Webhook - -At first, create an incoming slack webhook. -Necessary information is available in the [slack api page](https://api.slack.com/messaging/webhooks). -Once you create the webhook, you will get a URL similar to below example. - -`https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX` - -`T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX` is the secret part of the webhook which we would need in the next step. - -## Create slack-secret - -Create a `slack-secret.yaml` definition using the following command. -This will create a kubernetes secret named `slack-secret.yaml` in the `examples/sample-app/base` directory. -Before running this command change your current directory into `examples/sample-app`. - -```shell -kubectl create secret generic slack-secret --from-literal=SECURE_DATA='{"slack_hook":,"text":"Deployed PodTatoHead Application"}' -n podtato-kubectl -oyaml --dry-run=client > base/slack-secret.yaml -``` - -## Enable post deployment task - -To enable Slack notification add `post-deployment-notification` in as a postDeploymentTasks in the -[examples/sample-app/base/app.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/sample-app/base/app.yaml) -file as shown below. - -```yaml - postDeploymentTasks: - - post-deployment-notification -``` diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/yaml-crd-ref/app.md index e4d0d790d0..c6c3ff345d 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/yaml-crd-ref/app.md @@ -59,6 +59,9 @@ spec: For example, increment this number to restart a `KeptnApp` version that failed to deploy, perhaps because a `preDeploymentEvaluation` or `preDeploymentTask` failed. + See + [Restart an Application Deployment](../implementing/restart-an-application-deployment) + for a longer discussion of this. * **workloads** * **name** - name of this Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/). @@ -132,8 +135,9 @@ spec: ## Differences between versions -The `spec.Revision` field is introduced in v1alpha2. +The `spec.revision` field is introduced in v1alpha2. ## See also -[Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) +- [Restart an Application Deployment](../implementing/restart-an-application-deployment) +- [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) From 88d8dc485cc2c3662a0d2907f9d067fcf4f36475 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Fri, 16 Jun 2023 23:46:40 -0700 Subject: [PATCH 2/3] markdownlint issues, edits Signed-off-by: Meg McRoberts --- .../restart-application-deployment/_index.md | 13 +++++-------- docs/content/en/docs/yaml-crd-ref/app.md | 6 +++--- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/content/en/docs/implementing/restart-application-deployment/_index.md b/docs/content/en/docs/implementing/restart-application-deployment/_index.md index 6f2264c2b2..946ba7345f 100644 --- a/docs/content/en/docs/implementing/restart-application-deployment/_index.md +++ b/docs/content/en/docs/implementing/restart-application-deployment/_index.md @@ -3,13 +3,11 @@ title: Restart an Application Deployment description: Learn how to restart an unsuccessful Keptn Application Deployment. icon: concepts layout: quickstart -weight: 30 +weight: 100 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- -## Restart an Application Deployment - -A [KeptnApp](../../yaml-crd-ref/app.md] can fail +A [KeptnApp](../../yaml-crd-ref/app.md) can fail because of an unsuccessful pre-deployment evaluation or pre-deployment task. For example, this happens if the target value of a @@ -17,7 +15,7 @@ For example, this happens if the target value of a resource is misconfigured or a pre-deployment evaluation checks the wrong URL. -Use the `spec.revision` field of `KeptnApp` +Increment the `spec.revision` field of `KeptnApp` to retry a `KeptnApp` deployment without incrementing the version of the `KeptnApp` After you fix the configuration @@ -131,7 +129,6 @@ To fix the deployment of this application, we first need to fix the task that has failed earlier. To do so, edit the `pre-deployment-check` `KeptnTaskDefinition`: - ```shell kubectl -n restartable-apps edit keptntaskdefinitions.lifecycle.keptn.sh pre-deployment-check ``` @@ -203,7 +200,7 @@ pre-pre-deployment-check-65056 podtato-head 0.1.1 ``` -Notice that, for both the `KeptnAppVersions` and `KeptnTasks`, -the previous failed instances are still available. +Notice that the previous failed instances are still available +for both `KeptnAppVersions` and `KeptnTasks`. This may be useful historical data to keep track of what went wrong during earlier deployment attempts. diff --git a/docs/content/en/docs/yaml-crd-ref/app.md b/docs/content/en/docs/yaml-crd-ref/app.md index c6c3ff345d..1035aa98fa 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/yaml-crd-ref/app.md @@ -60,7 +60,7 @@ spec: that failed to deploy, perhaps because a `preDeploymentEvaluation` or `preDeploymentTask` failed. See - [Restart an Application Deployment](../implementing/restart-an-application-deployment) + [Restart an Application Deployment](../implementing/restart-application-deployment/) for a longer discussion of this. * **workloads** * **name** - name of this Kubernetes @@ -139,5 +139,5 @@ The `spec.revision` field is introduced in v1alpha2. ## See also -- [Restart an Application Deployment](../implementing/restart-an-application-deployment) -- [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) +* [Restart an Application Deployment](../implementing/restart-application-deployment/) +* [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) From 92717bd55c67a286c7efecf70df16e496ae2e74d Mon Sep 17 00:00:00 2001 From: odubajDT <93584209+odubajDT@users.noreply.github.com> Date: Tue, 20 Jun 2023 11:57:14 +0200 Subject: [PATCH 3/3] Update docs/content/en/docs/implementing/restart-application-deployment/_index.md Signed-off-by: odubajDT <93584209+odubajDT@users.noreply.github.com> --- .../docs/implementing/restart-application-deployment/_index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/content/en/docs/implementing/restart-application-deployment/_index.md b/docs/content/en/docs/implementing/restart-application-deployment/_index.md index 946ba7345f..f1a3ba916d 100644 --- a/docs/content/en/docs/implementing/restart-application-deployment/_index.md +++ b/docs/content/en/docs/implementing/restart-application-deployment/_index.md @@ -15,9 +15,6 @@ For example, this happens if the target value of a resource is misconfigured or a pre-deployment evaluation checks the wrong URL. -Increment the `spec.revision` field of `KeptnApp` -to retry a `KeptnApp` deployment -without incrementing the version of the `KeptnApp` After you fix the configuration that caused the pre-deployment evaluation or task to fail, you can increment the `spec.revision` value