Troubleshooting

Each entry below describes one symptom, its cause and the action that resolves it.

Pods stay in Pending

d8 k -n code get pods shows one or more pods in the Pending state.

Cause. No StorageClass satisfies gitaly.persistence.storageClass (or the cluster has no default StorageClass), or no node has enough CPU and memory for the pod’s resource requests.

Action. Read the pod’s events:

d8 k -n code describe pod <POD_NAME>

A FailedScheduling event naming a persistent volume claim points to the StorageClass; check it with d8 k get storageclass. A FailedScheduling event naming CPU or memory points to node resources.

Ingress has no address

d8 k -n code get ingress shows no value in the ADDRESS column.

Cause. global.ingress.class does not match an ingress controller installed in the cluster, or the controller’s own Service has no external address yet.

Action. Confirm the ingress controller is running and that its class name matches global.ingress.class. If the controller’s Service is of type LoadBalancer, check that the surrounding infrastructure assigned it an address.

TLS certificate is not issued

The browser reports the certificate as invalid or self-signed when opening global.hosts.domain.

Cause. The Secret named in global.ingress.tls.secretName does not exist in the code namespace, or it does not hold a certificate valid for global.hosts.domain.

Action. Check the Secret and the certificate it holds:

d8 k -n code get secret <TLS_SECRET_NAME> -o yaml

Confirm the certificate’s subject and Subject Alternative Names cover global.hosts.domain.

Database connection refused

Pods restart and their logs show PG::ConnectionBad: could not connect to server: Connection refused.

Cause. global.psql.host or global.psql.port does not reach the external PostgreSQL server, or network policies block the connection from the release’s namespace.

Action. Test connectivity to the server from inside the cluster, and confirm the database in global.psql.database and the role in global.psql.username exist on it.

Object storage credentials rejected

Uploads and artifacts fail, and pod logs show an access-denied response from the object storage endpoint.

Cause. The Secret named in global.appConfig.object_store.connection.secretName holds an outdated endpoint, region or access key, or the bucket does not exist.

Action. Check the Secret’s content against the object storage provider’s console, and confirm the bucket exists and the credentials have write access to it.

Migrations job failing

The migrations job’s pod exits with a non-zero status, and pods that depend on the database schema stay Pending or restart in a loop.

Cause. PostgreSQL is not reachable yet, the credentials in global.psql.password.secretName are wrong, or the release skipped a Deckhouse Code version that a later migration depends on.

Action. Read the job’s log:

d8 k -n code logs job/<MIGRATIONS_JOB_NAME>

Resolve the database connection first, then check Upgrade for the version order when skipping a version is the cause.

Helm upgrade times out

helm upgrade exits with Error: UPGRADE FAILED: timed out waiting for the condition.

Cause. A pod or the migrations job didn’t reach a ready or complete state within Helm’s wait timeout — usually one of the causes above.

Action. Inspect the release’s pods and jobs:

d8 k -n code get pods,jobs

Resolve the underlying cause, then run helm upgrade again, adding --timeout when the release legitimately needs more time.