Skip to content

Troubleshooting Guide

Welcome to the Keptn troubleshooting guide.

This guide will help you address common issues that you might encounter while using Keptn for managing your workloads. Below are some common problems and their solutions:

Keptn is installed but it is not aware of my workloads

If you are facing an issue where Keptn is installed but does not seem to be aware of your workloads, follow these steps:

  1. Ensure that the namespace you wish to target is annotated correctly.
  2. Make sure your workloads (e.g., Deployment manifests) have the three required annotations.

Keptn is causing my pods to be pending

If your pods are stuck in a pending state and Keptn seems to be the cause, it might be due to a pre-deployment task or evaluation. Follow these steps:

The most probable reason is that a pre-deployment task in your workload is either failing or has not completed yet.

Failing pre-deployment evaluation tasks will prevent a pod from being scheduled.

Check the logs of the pre-deployment task Kubernetes Jobs for insights.

For instance, if your application is in the prod namespace:

kubectl -n prod get pods
kubectl -n prod logs job/...

I have pending Pods after Keptn is uninstalled

Note This section particularly affects clusters managed by ArgoCD.

If you have uninstalled Keptn and are now facing issues scheduling or deleting pods, follow these steps:

ArgoCD does not delete various CRDs and webhooks, when uninstalling applications, causing lingering resources.

For cleanup instructions

  1. Install Keptn & CRDs w/ Argo
  2. Uninstall Keptn via Argo
  3. Cluster is frozen, Pods cannot be deleted or scheduled

Trying to schedule a new pod results an error.

Reason: Argo doesn't remove the CRDs and global objects (mutating webhooks) and the default failurePolicy is to fail.

to get further information refer to this issue.

I cannot see DORA metrics or OpenTelemetry traces

Keptn will automatically generate DORA metrics and OTel traces for every deployment, but by default it does not know where to send them.

You need an OpenTelemetry collector installed and configured on the cluster.

The OpenTelemetry observability page contains more information on how to configure this.