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 55% 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..f1a3ba916d 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,31 @@ 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: 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 +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. -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. +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`. -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`. +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. -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: +To illustrate this, consider the following example: ```yaml apiVersion: v1 @@ -95,10 +94,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 +107,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 +122,15 @@ 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 +145,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 +170,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 +180,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 +197,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 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/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/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 be3cc41e0a..2a12b07c44 100644 --- a/docs/content/en/docs/yaml-crd-ref/app.md +++ b/docs/content/en/docs/yaml-crd-ref/app.md @@ -64,8 +64,10 @@ spec: to trigger another deployment of a `KeptnApp` of the same version. For example, increment this number to restart a `KeptnApp` version that failed to deploy, perhaps because a - `preDeploymentEvaluation` or `preDeploymentTask` failed - for reasons that may be transient. + `preDeploymentEvaluation` or `preDeploymentTask` failed. + See + [Restart an Application Deployment](../implementing/restart-application-deployment/) + for a longer discussion of this. - **workloads** - **name** - name of this Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/). @@ -150,4 +152,5 @@ spec: - [Working with tasks](../implementing/tasks) - [Pre- and post-deployment tasks](../implementing/integrate/#pre--and-post-deployment-checks) - [Orchestrate deployment checks](../getting-started/orchestrate) -[Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) +- [Use Keptn automatic app discovery](../implementing/integrate/#use-keptn-automatic-app-discovery) +- [Restart an Application Deployment](../implementing/restart-application-deployment/)