Troubleshoot a deployment#

This guide shows you how to diagnose and fix the problems you are most likely to hit when you deploy Plone with cdk8s-plone.

Start by looking at the overall state, then drill into the failing object.

kubectl get pods -n <namespace>
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace>

cdk8s synth fails#

If synth fails while rendering PloneHttpcache, confirm the helm CLI is installed and on your PATH. PloneHttpcache renders the kube-httpcache Helm chart at synth time and shells out to helm.

If synth fails on a missing custom resource type, run the example’s import step (npm run import) to regenerate the CRD bindings.

Pods stay Pending#

Describe the pod and read the Events section for the scheduler’s reason.

kubectl describe pod <pod> -n <namespace>

Common causes:

  • Insufficient CPU or memory on the nodes. Lower requestCpu or requestMemory, or add capacity.

  • A nodeSelector or tolerations setting that no node satisfies. See Schedule pods to specific nodes.

  • PloneHttpcache pods only schedule on amd64 nodes, because the construct hard-codes kubernetes.io/arch=amd64. Provide an amd64 node or use Deploy with cloud-vinyl cache instead.

A pod is in CrashLoopBackOff#

Read the logs of the current and previous container starts.

kubectl logs <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous

A backend that exits immediately almost always cannot reach its database. See The backend cannot reach the database.

The backend cannot reach the database#

The backend uses RelStorage on PostgreSQL, so it needs a correct connection string and credentials.

kubectl get secret -n <namespace>
kubectl exec -n <namespace> deployment/<backend-deployment> -- env | grep -i storage

Pods never become ready#

A pod that stays Running but never Ready is failing its readiness probe.

  • Increase readinessInitialDelaySeconds if the backend needs longer to start.

  • Increase readinessTimeoutSeconds or readinessFailureThreshold for a slow first request.

backend: {
  image: 'plone/plone-backend:6.1.3',
  readinessInitialDelaySeconds: 30,
  readinessTimeoutSeconds: 15,
}

Liveness probes are disabled by default (livenessEnabled defaults to false). If pods restart in a loop after you enable liveness, raise livenessInitialDelaySeconds so the probe does not fire during startup.

The cache does not cache#

Check the cache pod logs, then confirm requests reach the cache service rather than the backend or frontend directly.

kubectl logs -n <namespace> -l app.kubernetes.io/part-of=plone
kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
  curl -sI http://<cache-service>.<namespace>:80/

A missing X-Varnish header means traffic bypasses the cache; point your ingress at the cache service. See Configure ingress and TLS. For VCL behavior, see Deploy with PloneHttpcache and Deploy with cloud-vinyl cache.

Prometheus does not scrape the metrics#

If a ServiceMonitor exists but no target appears in Prometheus, the selectors do not match.

  • Confirm the ServiceMonitor namespace matches the Prometheus resource’s serviceMonitorNamespaceSelector.

  • Confirm its labels match the Prometheus resource’s serviceMonitorSelector.

See Enable Prometheus monitoring for the full setup.

See also#