Troubleshooting Kasm on Kubernetes
Recommendations and resources useful when troubleshooting a Kasm Kubernetes deployment.
Confirm All Pods are Running
kubectl get pods -n {NAMESPACE}
All application pods should have a Running status. Completed job pods (such as db-upgrade or pre-upgrade-backup) should show Completed.
If any pod shows Pending, CrashLoopBackOff, Error, or ImagePullBackOff, proceed to the next section to investigate further.
Check Error with Specific Pod
If a pod is not in a healthy state, inspect it with:
kubectl describe pod {POD_NAME} -n {NAMESPACE}
Check the Events section at the bottom of the output for error messages.
To view the pod logs:
kubectl logs {POD_NAME} -n {NAMESPACE}
If the pod has multiple containers, specify the container:
kubectl logs {POD_NAME} -n {NAMESPACE} -c {CONTAINER_NAME}
If the pod has already crashed, retrieve logs from the previous instance:
kubectl logs {POD_NAME} -n {NAMESPACE} --previous
If a pod is stuck in Init state, check the init container logs:
kubectl logs {POD_NAME} -n {NAMESPACE} -c {INIT_CONTAINER_NAME}
To list the init containers for a pod:
kubectl describe pod {POD_NAME} -n {NAMESPACE} | grep -A5 "Init Containers:"
Make Sure Your Ingress is Provisioned and Has an Address
kubectl get ingress -n {NAMESPACE}
The ADDRESS column should contain an IP address or hostname. If it is empty, your ingress controller may not be running or your cloud provider's load balancer has not finished provisioning.
To investigate further:
kubectl describe ingress {INGRESS_NAME} -n {NAMESPACE}
Check the Events section for any errors related to the ingress controller.
Make Sure Your Certificate is Ready (cert-manager)
kubectl get certificate -n {NAMESPACE}
The READY column should show True. If it shows False, pods that depend on the TLS secret may remain in a Pending or ContainerCreating state until the certificate is issued. Inspect the certificate for more detail:
kubectl describe certificate {CERTIFICATE_NAME} -n {NAMESPACE}
Check the Events and Status.Conditions sections for error messages.
You can also check the cert-manager logs directly for more detail:
kubectl logs -n cert-manager -l app=cert-manager
Investigate PVC / PV Issues
If a pod is stuck in Pending due to an unbound volume, check the status of all PersistentVolumeClaims in the namespace:
kubectl get pvc -n {NAMESPACE}
All PVCs should show a Bound status. If a PVC shows Pending, it means Kubernetes has not been able to provision the underlying storage. Inspect the PVC for more detail:
kubectl describe pvc {PVC_NAME} -n {NAMESPACE}
Check the Events section for errors such as no matching StorageClass, insufficient capacity, or a missing provisioner. If your cluster requires a specific storage class, ensure storageClassName is set correctly in your values or template files.
When using the built-in PostgreSQL database, the Kasm Helm chart creates a PersistentVolumeClaim that requires a default StorageClass (or an explicit storageClassName in your values). A missing or misconfigured StorageClass is a common cause of the database pod remaining in Pending state.
To list available storage classes in your cluster:
kubectl get storageclass
Find Container Image Versions
When troubleshooting, it is often useful to confirm the exact container image and version running in each pod:
kubectl get pods -n {NAMESPACE} \
-o=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image,IMAGE_ID:.status.containerStatuses[*].imageID"
This shows the image tag and the full image ID (including digest), which is helpful for verifying that the correct version is deployed.
Run Commands Inside a Container
To inspect configuration or debug issues inside a running pod, use kubectl exec. For example, to view the Kasm API application configuration:
kubectl exec {POD_NAME} -n {NAMESPACE} -- cat /opt/kasm/current/conf/app/api/api.app.config.yaml
If the pod has multiple containers, specify the container with -c:
kubectl exec {POD_NAME} -n {NAMESPACE} -c {CONTAINER_NAME} -- cat /opt/kasm/current/conf/app/api/api.app.config.yaml
You can also open an interactive shell for more in-depth debugging:
kubectl exec -it {POD_NAME} -n {NAMESPACE} -- /bin/bash
General Kasm Troubleshooting
For issues not specific to Kubernetes, see the Kasm Troubleshooting guides.