Kubernetes troubleshooting

Bounded diagnostic collection and exact failing-path checks without exposing secrets.

Short glossary
  • Helm release: an installed and independently managed resource set from one chart.
  • Secret object: a Kubernetes resource referenced for sensitive values; the delivery charts do not own the values themselves.
  • PersistentVolumeClaim (PVC): a storage request used by a bundled data component.
  • NetworkPolicy: rules governing permitted network connections for application Pods.
  • Container Storage Interface (CSI) and Container Network Interface (CNI) capabilities are provided by the customer cluster.

Diagnostics and incident flow

Start with the bundled healthcheck, then inspect status and create a local redacted support-bundle. Nothing is sent automatically; the archive is created with mode 0600.

  • Schema or render failure: fix the reported values path; do not remove values.schema.json or weaken validation
  • Readiness Job failure: inspect the bounded category, Job log, Events, DNS, routes, CIDRs, credentials, TLS, ACLs, grants, and storage facts
  • CreateContainerConfigError: verify the referenced Secret and key names without printing or decoding values
  • ImagePullBackOff: verify registry access, imagePullSecret reference, immutable digest, and release provenance
  • NotReady with an open TCP port: inspect the application's readiness endpoint and authenticated dependency flow
  • Pending PVC: stop and inspect StorageClass binding, topology, and capacity; never substitute hostPath
  • Inspect work/install.log locally: it has mode 600 and contains the initial administrator password, so it must not be attached to an issue or diagnostic archive
  • Recover the dependency or controller, then repeat healthcheck and verify readiness, restart counts, and application control data
bash
./bin/healthcheck.sh
./bin/massaccess-k8s status --namespace <namespace>
./bin/massaccess-k8s support-bundle --namespace <namespace>