Skip to main content
Version: Developer

Troubleshoot Kasm on Kubernetes

This reference lists recommendations and resources for troubleshooting a Kasm Workspaces 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. When any pod shows Pending, CrashLoopBackOff, Error, or ImagePullBackOff, continue to the next section to investigate.

Check errors on a specific pod​

When a pod is not healthy, inspect it:

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}

When the pod has multiple containers, specify the container:

kubectl logs {POD_NAME} -n {NAMESPACE} -c {CONTAINER_NAME}

When the pod has already crashed, retrieve logs from the previous instance:

kubectl logs {POD_NAME} -n {NAMESPACE} --previous

When a pod is stuck in the 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:"

Confirm the ingress is provisioned and has an address​

kubectl get ingress -n {NAMESPACE}

The ADDRESS column should contain an IP address or hostname. When it is empty, the ingress controller may not be running, or the cloud provider load balancer has not finished provisioning. To investigate:

kubectl describe ingress {INGRESS_NAME} -n {NAMESPACE}

Check the Events section for errors related to the ingress controller.

Confirm the certificate is ready (cert-manager)​

kubectl get certificate -n {NAMESPACE}

The READY column should show True. When 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:

kubectl logs -n cert-manager -l app=cert-manager

Investigate PVC and PV issues​

When a pod is stuck in Pending because of an unbound volume, check the status of all PersistentVolumeClaims in the namespace:

kubectl get pvc -n {NAMESPACE}

All PVCs should show a Bound status. When a PVC shows Pending, Kubernetes has not provisioned 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. When the cluster requires a specific storage class, confirm that storageClassName is set correctly in your values or template files.

note

With 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 the Pending state.

To list the available storage classes in the cluster:

kubectl get storageclass

Find container image versions​

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 the digest, which helps verify 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

When 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

To open an interactive shell for deeper debugging:

kubectl exec -it {POD_NAME} -n {NAMESPACE} -- /bin/bash

General Kasm troubleshooting​

For issues that are not specific to Kubernetes, see the Kasm troubleshooting guides.