Troubleshoot Installation, Identity, and Routing

Use this task when Policy cannot start, authenticate callers, or serve configured paths. Separate platform availability from policy delivery failures. Healthy workloads do not establish protection for an approved policy.

Prerequisites

Prepare the following:

• Obtain the configured Policy address and installed release details.
• Use your own supported gateway session or application programming interface (API) credentials.
• Involve a platform operator for namespace, release, gateway, and log inspection.
• Follow diagnostics before changing configuration.

For cluster inspection, have the platform operator complete the explicit context setup. Every cluster example below requires that approved CTX value.

Use the installation instructions and configuration reference for canonical settings. Do not copy development credentials or registry overrides into a customer installation.

Recover From a Failed Installation or Release Change

Complete these steps:

1. Ask the operator to inspect the installed release history. Replace the release and namespace if your deployment uses different names:

   helm --kube-context "${CTX:?Set CTX}" history policy -n pty-policy
   

2. Identify the first failing workload or initialization task. Use pod status, events, and bounded logs from the failed interval.

3. Check database bootstrap and runtime configuration through the authorized operator. Keep PostgreSQL inside the Policy stack.

4. Ask the operator to verify Secret references and required key names. Do not print or attach credential values.

5. Determine whether the release change altered database schema, grants, or ownership. Preserve this evidence before selecting a recovery procedure.

6. Ask the platform and database administrators for the deployment or restore procedure tested with the selected release versions. Do not restart an older API until they confirm that it can use the current database schema and accounts.

Helm rollback does not reverse database schema or ownership changes. An older chart might expect a former shared database login. Do not blindly roll back workloads after a database-role migration. Database recovery also requires reconciliation of external effects before resuming work. These checks do not establish a universal supported rollback or restore recipe.

Resolve Authentication and Permission Failures

Check authentication, command authority, and dependency access separately:

1. Record the failing route, action, and status code. Separate failed authentication from a refused policy command.
2. Reauthenticate through the supported gateway for a 401 response. Do not inject trusted identity headers or bypass the gateway.
3. Check the command capability for a 403 response. Ask a Protegrity Provisioned Cluster (PPC) user with administrator permissions to check the required capability against your account’s role mapping.
4. Check applicable policy resource grants for edit or rollback work. Ask an existing owner to resolve grant issues.
5. For a Policy Integration Manager (PIM) or Traverse login failure, ask that product’s administrator to check the account used by the failing request. Policy authority does not establish native integration permissions.

Do not grant broad administrator access as a routine repair. An owner/editor grant does not create approval, audit, or system-configuration capability. For draft decisions, use authoring and review troubleshooting.

Distinguish Credential Kinds

Your gateway login authenticates interactive requests. Your draft, governed-policy, and registry validators protect resource versions. An idempotency key identifies an exact reconciliation decision. None of these keys replaces authentication.

Interactive dependency calls and unattended workers can use different credentials. A caller’s delegated bearer token does not repair a worker’s configured service identity. A workload service identity does not grant an interactive user native permissions. Kubernetes ServiceAccounts, registry pull credentials, and dependency users serve different purposes.

Ask the PIM or Traverse administrator to verify the service user for worker failures, or your own dependency access for interactive failures. Do not copy worker credentials into user requests or share another user’s token. Refer to API authentication.

Diagnose Public Routing

Compare the public route with the configured deployment:

1. Confirm the configured host and versioned API base with the administrator. Do not assume a 404 means the policy itself is missing.

2. Compare the failing public path with the installed configuration. The usual API prefix is /pty/policy/v1.0.

3. Ask the operator to inspect gateway routes. For the default namespace:

   kubectl --context "${CTX:?Set CTX}" get httproute -n pty-policy
   

4. Ask the operator to inspect the affected route’s acceptance and backend references. Use the actual gateway name and namespace from that route.

5. Ask the operator to verify backend Service endpoints and ports. Correct the installed route configuration through approved change control.

6. Retest the configured Panel path and a known API path independently. The usual Panel path ends in /pty/policy/v1.0/ui/, not the host root.

Do not reapply chart values merely because a route is missing. Confirm whether this installation uses Gateway API routing first. Do not disable authentication or certificate validation to make a probe succeed.

Check Service Health Without Claiming Policy Recovery

Set POLICY_API, PPC_CA_FILE, and the protected POLICY_AUTH_HEADER file using the diagnostic setup. Use your deployment’s required authentication:

curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/live"
curl --silent --show-error --include --cacert "$PPC_CA_FILE" \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/ready"

Liveness normally returns 204. Readiness returns 204 when its checks succeed. 503 needs dependency investigation. These checks do not validate approval, publication, target activation, or deprotection.

Check Shared Identity Provider Metadata

The shared identity provider (IdP) connection document supports native member-source creation. It is not the Traverse poller’s login Secret. When Policy follows an existing Traverse installation, the shared document might remain empty. Use the reported workaround and ask the connection owner to verify the intended entry. Do not grant extra scanner permissions or replace working service credentials to conceal missing metadata.

Verification and Escalation

Confirm workload stability, supported authentication, route acceptance, and the original failing request. After deployment recovery, repeat installation verification. Then follow the delivery guide for affected policies.

Stop when database compatibility, trusted identity, or route ownership remains uncertain. Use the diagnostic handoff with the installed release, failing path, timestamps, and sanitized operator findings.