Collect Policy Diagnostics

Collect enough evidence to identify the failed task and responsible operator. Start with information you can access. Do not request broad administrator access merely to report an issue.

Prerequisites

Prepare the following:

• Use your own supported Policy session or application programming interface (API) credentials.
• Obtain policy:audit only when your assigned investigation requires restricted diagnostics.
• Obtain namespace read access only for the optional platform checks.
• Follow your organization’s incident process for sensitive evidence.

Steps

Collect evidence available without cluster access:

1. Record the failed action and its timestamp with time zone. Include the configured Policy address and release version when known.
2. Retain the response status and sanitized error details. Capture a support reference if the response includes one.
3. Open the affected policy in Policy Library, or read it through GET /policies/{policy_id}. Record the policy identifier, displayed version, draft status, and protection status.
4. Record the last successful action. Include relevant source changes and the time the problem started.
5. Route the evidence to the matching troubleshooting task. Stop if its next step requires authority you lack.

Do not send bearer tokens, cookies, passwords, private keys, or rejected sensitive values. Remove authentication headers from captured requests before sharing them.

Inspect Restricted Evidence

An authorized auditor can inspect operations and validation diagnostics. Run the examples in Bash. Complete the endpoint, trusted certificate authority (CA), and token setup in Configure API access. This setup does not require cluster access. Use your own token, not a worker account or another participant’s token. Keep the protected header file in that setup’s dedicated shell. Follow its credential cleanup when you finish. Set the API alias and affected policy identifier before the first request:

export POLICY_API="${POLICY_BASE_URL:?Complete endpoint setup}"
export PPC_CA_FILE="${PPC_CA_FILE:?Set the trusted CA bundle path}"
export POLICY_ID='replace-with-the-affected-policy-identifier'

POLICY_API and the operations guide’s POLICY_BASE_URL identify the same versioned API base. Keep response headers when using these read-only requests:

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

Complete the following steps:

1. Save the operation-list response in your incident record after removing sensitive values.

2. Select the entry with the largest generation number. Record its deploymentId, lastError, attemptCount, and diagnostics. These identify the latest delivery request and its failure.

3. Retrieve retained validation evidence when you have a VAL- support reference. Set SUPPORT_REFERENCE to that exact reference:

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

4. Retain only the evidence needed for the incident. Successful diagnostic responses specify Cache-Control: no-store. Use approved incident storage.

Validation diagnostics expire after seven days. A 404 can mean absent or expired evidence. An operations 404 can mean no recorded deployments, not a missing policy. A 403 requires an authorized handoff, not a different endpoint.

Publication diagnostics can contain PUB- support references. Do not send these references to the validation-diagnostics endpoint. An operator with server access can correlate them with publication logs. An API-only caller should pass the reference to that operator.

Collect Optional Platform Evidence

Only a platform operator with namespace read access should run these commands. Replace pty-policy if your installation uses another namespace. Set and confirm the intended cluster context first:

export CTX='your-approved-kubernetes-context'
kubectl --context "${CTX:?Set CTX to the approved context}" cluster-info

Stop if the reported cluster differs from the incident’s deployment.

Collect only the platform evidence relevant to the incident:

1. List workload status and recent events.

   kubectl --context "${CTX:?Set CTX}" get pods,svc,events -n pty-policy
   

2. Inspect an affected pod from that list. Replace POD_NAME with its exact name:

   kubectl --context "${CTX:?Set CTX}" describe pod POD_NAME -n pty-policy
   

3. Read bounded logs from that pod.

   kubectl --context "${CTX:?Set CTX}" logs POD_NAME -n pty-policy --since=15m --tail=200
   

Review logs for secrets before attaching excerpts. Do not collect Secret contents or query the database as a routine diagnostic. Check previous-container logs only when the pod history requires them.

Prepare an Escalation

Provide the responsible administrator or your organization’s support contact with:

• The failed task, timestamp, time zone, status code, and sanitized message.
• The policy, draft, governed revision, deployment, and generation identifiers you can access.
• The support reference and authorized diagnostic result, including expiry or access refusal.
• The current state and last successful action.
• The selected playbook, actions already attempted, and observed results.
• The missing authority or evidence that prevents safe progress.

If a reconciliation request lost its response, include its request body and idempotency key after removing sensitive values. Keep that information in the approved incident record, not public logs. Ask the administrator handling reconciliation to check the current mapping before submitting another decision.

Verification

Confirm that the recipient can identify the failed task and next authorized action. Missing cluster access or expired diagnostics does not invalidate the report. Record those limits and preserve the original public error.