EQTY LabDocs

Deployment Troubleshooting

Common deployment issues and first-line diagnostics.

View as Markdown

Use this page for first-line deployment checks before escalating.

Each section below starts from one of these readiness checks. $API_SECRET is the Auth Service API secret, global.secrets.authService.values.apiSecret in secrets.yaml (key api-secret in the platform-auth-service secret):

bash
# Sign-In Fails
curl https://guardian.example.com/authService/health/ready
# Attachments Fail, Indicators Do Not Evaluate
curl https://guardian.example.com/governanceService/health/ready
# Certificates or Lineage Fail
curl https://guardian.example.com/integrityService/health/v1
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/signing

Install or Upgrade Fails

Confirm the chart version matches the release manifest, values are valid for the selected identity provider, and all required secrets are available in the target namespace.

Many configuration mistakes stop Helm before anything reaches the cluster. To see the error without installing, render the chart with the same chart version and values files:

bash
helm template guardian-platform \
  oci://ghcr.io/eqtylab/charts/guardian-platform \
  --version <chart-version> \
  --namespace guardian \
  --values values.yaml \
  --values secrets.yaml

Common render errors:

  • global.secrets.<name>.values.<key> is required when … create is true: secrets.yaml sets global.secrets.create: true but leaves that value empty. Fill it in, or set create: false and pre-create the secret.
  • global.secrets.database.values.gatewayDsn is required when create and gateway-stack are enabled: add the guardian_gateway DSN beside the database password.
  • No database configured: postgresql.enabled is false and global.postgresql.host is empty. Enable the bundled PostgreSQL or point at an external database.
  • Original containers have been substituted for unrecognized ones: the bundled PostgreSQL image was redirected to a mirror without postgresql.global.security.allowInsecureImages: true.
  • platformAdminEmail is required when … createPlatformAdmin is true: set the admin email for the identity provider’s post-install setup.

Images Do Not Pull

Confirm registry access, image pull secrets, registry override values, and mirrored image digests for restricted environments.

ImagePullBackOff usually means one of:

  • The platform-image-pull-secret secret is missing, or its registry does not match the image registry (for example Cloudsmith credentials with GHCR images, without values-cloudsmith.yaml).
  • The entitlement token is a dev token used against eqtylab/prod, or has been revoked.
  • An image tag was overridden to one the registry does not hold; leave image tags unset.
  • In a restricted environment, an upstream image was not mirrored or its setting was not redirected.

Sign-In Fails

Confirm identity provider mode, issuer, audience, client settings, callback URLs, and Guardian public domain.

Attachments Fail

Confirm object storage provider, bucket or container permissions, network access, and customer storage policies.

Certificates or Lineage Fail

Confirm Integrity Service readiness, key-management access, and credential configuration.

Indicators Do Not Evaluate

Confirm Governance Service readiness, event integration configuration, active indicator applications, and project context.