Additional Information

• 1: Understand Policy
• 1.1: Policy Overview
• 1.1.1: Role-Based Access Control and Artificial Intelligence Policies
• 1.2: States and Revisions
• 1.3: Roles and Permissions
• 1.4: Classifications, Principals, and Methods
• 1.5: Validation and Review Decisions
• 1.6: Policy Terminology
• 2: System Operations
• 2.1: Background Processing and Cadence
• 2.2: Automatic Recompilation of Approved Policies
• 2.3: Observe and Restart Policy
• 3: Policy Frequently Asked Questions

1 - Understand Policy

Policy connects authored intent to reviewed revisions and target-specific delivery. The Library helps users find policies and inspect their lifecycle history. Data and artificial intelligence (AI) authoring capture different protection inputs. The compiler validates those inputs and prepares target-specific artifacts.

Read by Concern

Choose the reference that matches your question:

• States and revisions distinguishes proposed work, approved content, and delivery.
• Roles and permissions explains command capabilities and policy grants.
• Classifications, principals, and methods explains catalog selections and target behavior.
• Validation and review decisions distinguishes blocking findings from reviewable conflicts.
• Architecture explains component responsibilities.
• Role-based access control and AI policies separates product access from authored runtime permissions.
• Policy terminology defines shared terms.

Keep Responsibilities Separate

An author can prepare a replacement while an approved revision remains governed. A reviewer must inspect the current submitted content before deciding. An operator follows delivery and recovery evidence after governance completes. An application developer must preserve API errors, identities, and concurrency tokens.

No single status label answers every question. Refer to states and revisions before interpreting a policy’s progress.

Continue with Work with policies or System operations.

1.1 - Policy Overview

Policy combines guided authoring, review decisions, governed revisions, and delivery evidence. Refer to Understand Policy for the canonical conceptual references. Refer to Start here for an ordered learning path.

Key Capabilities

Policy supports the following responsibilities:

• Find policies and inspect available detail and history through Policy Library.
• Author Data protection or artificial intelligence (AI) policies with lane-specific inputs.
• Save proposed work separately from the current governed revision.
• Submit, request changes, and approve with the appropriate authority.
• Publish approved artifacts and inspect target-specific delivery evidence.
• Refresh approved compilation output through background processing.

Policy Release Highlights

Supported authoring choices and available interface actions depend on your release and authority. Use the corresponding task guide rather than inferring support from a conceptual example. The API reference distinguishes operation contracts from interface presentation.

Documented Use Cases

Refer to use cases for author, reviewer, operator, and integration journeys.

Supported Platforms

The deployment guides target Kubernetes with the required Protegrity platform integrations. They do not establish support for arbitrary standalone platform combinations.

System Requirements

Operators need the release’s platform, storage, gateway, identity, and integration prerequisites. PostgreSQL runs inside the Policy stack. Authors and reviewers need the capabilities for their assigned tasks. Refer to installation and access preparation.

Architecture

Refer to Architecture for component responsibilities and delivery boundaries.

Definitions

Use these references for shared definitions:

• States and revisions
• Roles and permissions
• Classifications, principals, and methods
• Role-based access control and AI policies
• Policy terminology

1.1.1 - Role-Based Access Control and Artificial Intelligence Policies

Role-based access control (RBAC) governs access to Policy operations. An authored artificial intelligence (AI) policy governs a different concern: runtime behavior for the selected principals and classifications. Here, runtime means downstream processing of requests or data, not administration of the Policy service. Do not treat these two permission systems as interchangeable.

RBAC in Policy

The platform authenticates users through its supported gateway integration. Policy maps trusted authorities to command capabilities. Editing and rollback also require applicable policy access grants.

The policy_author bundle does not provide review or approval authority. An owner grant does not add either capability. Different authenticated users can therefore perform the author and reviewer responsibilities. This capability separation does not itself enforce mandatory two-person approval.

Refer to roles and permissions for the canonical role and capability tables. Refer to API authentication for the request-level identity contract.

AI Policy in Policy

AI authoring captures classification and principal-specific runtime permissions. Its permissions matrix describes the selected principals’ allowed behavior. It does not assign those principals administrative roles in Policy.

For example, a principal can receive a runtime unprotect permission. Unprotect means allowing supported runtime access to protected content. It does not remove a governed policy. That permission does not allow the principal to submit or approve a Policy draft. Likewise, a Policy approver does not automatically receive runtime unprotect access.

Preview output, saved content, approval, and consumer receipt remain distinct checkpoints. A delivered Federated Guardrails artifact does not prove execution against real traffic. Refer to validation and review decisions and delivery verification.

Verification

Verify product access and authored runtime permissions independently. Refer to authoring procedures for the selected lane. Refer to lifecycle and governance for the review handoff.

1.2 - States and Revisions

A policy can have governed content and an open replacement draft simultaneously. Saving that replacement does not make it the approved policy. Publication and observed protection remain separate from both authoring and approval.

Three Independent Questions

The following table distinguishes the questions answered by draft, governance, and delivery evidence:

Before first approval, no governed revision or protection evidence may exist. An empty protection value does not mean protection succeeded or failed. Do not derive these independent concerns from one displayed status.

Drafts and Saved Snapshots

The policy identifier remains stable across its lifecycle. A draft identifies proposed work for that policy. Each successful save creates a retained snapshot of that work. Repeated saves do not create repeated governed revisions. The draft head is its current saved snapshot, not the governed revision. A snapshot records saved content. The draft’s head changes when later work supersedes it.

Submission puts the current proposal into review. A request for changes returns editable work with the reviewer’s reason. The author can correct that proposal and submit it again. Reviewing a draft does not publish its contents.

Governed Revisions and Compilation Minors

Approval creates a governed revision from the exact reviewed draft. It also starts asynchronous delivery work. A later authored replacement must pass through the review workflow again.

Automatic recompilation serves a different purpose. It recompiles approved intent against fresh context without requiring author edits. Changed output creates a compilation minor under the governed revision. Approved intent means the reviewed classifications, principals, methods, and permission selections. A compilation minor changes generated target configuration, not those authored selections. It preserves the original approval identity and leaves open drafts unchanged. Unchanged output creates no compilation minor or publication work.

For example:

1. Alex saves and submits a draft. The draft remains proposed work until an authorized approval succeeds.
2. Morgan approves the current submission. Policy creates the first governed revision and queues publication.
3. A later automatic cycle detects changed compilation output. Policy records a compilation minor and queues new delivery work.
4. Alex edits the authored policy. The new draft remains separate from the governed revision and its compilation minors.

Refer to automatic recompilation for scheduling, failures, and observation.

Delivery Generations and Evidence

A deployment generation identifies a particular publication or withdrawal operation. A retry continues retained work for that generation. It does not approve new authored content or substitute a corrected draft. The deployment identifier selects the retained operation. Its generation distinguishes successive publication or withdrawal operations for the policy. Inspect operation history rather than deriving either value from the governed revision number.

For Data protection, verify the expected location scope and positive protection observations. For Federated Guardrails, a consumer receipt records retrieval of the currently generated configuration. A receipt does not prove execution against real traffic or activation by every replica. A policy using both targets needs complete Data observations and the matching Guardrails receipt.

Publication failure does not undo the approval that created the governed revision. Withdrawal can also remain incomplete after an archive request succeeds. Do not treat archive acceptance as completed deprotection.

Concurrency Tokens Identify Different Resources

Application programming interface (API) clients must retain server-issued validators. An entity tag (ETag) is an opaque validator for one resource version. Send the exact value, including quotes, in the operation’s required If-Match header. It is not an authentication token, policy identifier, or interchangeable revision number.

The table identifies each resource’s validator and the distinction API clients must preserve:

The API reference defines each operation’s exact token and error contract. Continue with lifecycle and governance for the author and reviewer tasks.

1.3 - Roles and Permissions

Authentication establishes who is making a request. Authorization determines whether that identity can perform the requested operation. Some commands also require access to the particular policy. A command capability answers whether an identity may perform an operation at all. A policy access grant answers whether that operation may affect this specific policy. Commands that require both checks must satisfy both.

Responsibilities Are Not New Roles

An author prepares and submits proposed work. A reviewer inspects a submission and can request changes with the required authority. An approver accepts the reviewed content with approval authority. An operator observes delivery and performs specifically authorized recovery tasks.

One person can hold multiple responsibilities. Different users can also perform them with separate authenticated accounts. The capability model does not itself enforce mandatory two-person approval. There is no separate policy_reviewer role in the role bundles below.

Product Role Bundles

The following table summarizes each product role bundle and its key limitation:

Platform permissions can map to capabilities separately from these role bundles. Their membership does not necessarily match the product bundles exactly. Ask the platform administrator to verify the effective authorities for your task. Unknown authorities do not create capabilities. An authority is a permission asserted by the trusted platform gateway. It is not a request field that clients may choose for themselves.

Command Capabilities

Use this table to identify the capability and policy boundary for each task:

Retry authority follows the retained operation. Publishing retry requires approval authority. Withdrawal retry requires archive authority. Refer to recovery and reconciliation for the complete operation-specific rules.

Policy Access Grants

An owner or editor grant determines access to particular authored work. It does not create review, approval, archive, or system configuration capabilities. An author role also does not automatically grant edit access to every policy. For example, policy:edit without an applicable owner/editor grant does not authorize an existing-policy edit. An owner grant without policy:approve does not authorize approval.

Refer to policy access management for grant changes. Do not remove the last active owner during routine access maintenance. Administrator recovery is a separate audited path, not an ordinary grant substitute.

Identity and Downstream Access

Use the supported platform sign-in or gateway authentication path. Policy records the authenticated actor. Clients must not impersonate another reviewer. Do not supply submittedBy or approvedBy as a workaround.

Policy authority does not automatically create permission in a downstream system. An operator may need separate integration and target access. Refer to security settings and API authentication.

Continue with lifecycle and governance.

1.4 - Classifications, Principals, and Methods

Authoring combines the data or runtime scope with intended principals and permissions. Catalog choices have operational meaning. They are not interchangeable display labels.

Classifications and Scope

A classification identifies a category of discovered data. For Data protection, its resolved locations determine where protection applies. Review that scope before submission, particularly after catalog changes. The same display name does not prove the same current location set. Scope is the resolved set of locations or runtime subjects to which the selected inputs apply. Record identifiers and representative locations, not just a classification’s display name.

An empty selection and an unresolved classification are different problems. An empty selection supplies no classification. An unresolved classification supplies an identifier that current discovery cannot match to the required input. Correct the selected input when it is wrong. Ask an operator to inspect discovery when expected catalog data is missing.

Principals and Permissions

A principal identifies an intended runtime subject, such as a configured group. Select it from the available catalog and verify its intended membership. Do not confuse a policy’s runtime principals with the users administering Policy.

For example, an application group may receive an unprotect permission. That permission does not allow the group to approve Policy drafts. Conversely, approval authority does not automatically grant runtime data access.

Protection Methods and Authoring Lanes

Data authoring captures protection choices supported by the selected release and target. Artificial intelligence (AI) authoring uses its own principal-permission matrix. Do not infer that every method listed in a catalog supports both lanes. Do not treat hidden, unsupported, or unavailable choices as tutorial prerequisites.

Preview helps inspect target-specific output. Saving retains authored inputs, including supported incomplete work. Submission and approval require current validation and the appropriate review decisions.

Changing Context

Discovery, configured identities, and native target inventory can change over time. Policy therefore validates current context during governance operations. Automatic recompilation can also generate updated artifacts from approved intent. Neither mechanism authorizes silently changing an author’s proposed policy.

Continue with Data and AI authoring or validation and review decisions.

1.5 - Validation and Review Decisions

Each checkpoint answers a different question about a policy. A successful earlier checkpoint does not guarantee success at the next one.

Checkpoint Meanings

The following table explains what each checkpoint establishes and what to verify next:

Blocking and Reviewable Findings

Some findings require correction before the operation can continue. Other findings permit an explicitly recorded review acknowledgement. An acknowledgement records an authorized acceptance of a specifically reviewable finding. It does not suppress validation, widen permissions, or override a blocking finding. Use the returned conflict identifiers and the current operation contract. Do not acknowledge every finding merely to make a request succeed.

Review notes explain an approval. A request-changes reason explains what the author must correct. Neither text field replaces a missing capability or stale concurrency token.

Fresh Validation and Stale Work

Current dependencies can change after a preview or earlier save. That context includes discovered locations, identity metadata, and current native target inventory. Submission and approval therefore validate current inputs and governed context. A reviewer must load the submitted draft and its current validation results before approving.

If a command reports changed work, refresh the policy and review the new content. Do not blindly replace the token and replay a consequential decision. Refer to API error handling.

Diagnostics and Escalation

An error can provide a support reference without disclosing restricted diagnostics. An ordinary author may need an authorized operator to inspect that reference. Record the operation, policy identifier, time, and safe error details. Never include access tokens or sensitive payload values in a support request. The reference identifies retained evidence. It neither contains that evidence nor grants permission to read it.

Refer to diagnostics for evidence collection and access boundaries. Continue with lifecycle and governance.

1.6 - Policy Terminology

Policy uses different records for authored work, approved content, and target delivery. Similar names do not make those records interchangeable. This reference explains the distinctions used in task instructions and error messages.

Authoring and Governance

The following table defines terms for authoring and governance:

For example, saving a corrected draft changes proposed work. Approval creates governed content. Automatic recompilation can then change generated output without another author edit. Refer to states and revisions.

Identity and Request Evidence

The following table defines identity and request-evidence terms:

An application programming interface (API) request can require authentication, a command capability, a policy grant, and a resource validator. Each satisfies a different condition. Refer to roles and permissions and API authentication.

Compilation, Delivery, and Protection

The following table defines compilation, delivery, and protection terms:

Refer to background processing and delivery verification.

Ownership and Recovery

The following table defines ownership and recovery terms:

For recovery actions and authority requirements, use the recovery directory. For installation limitations, consult known issues.

2 - System Operations

Policy continues work after users save, approve, or archive policies. Background services refresh discovery, generate approved configuration, publish it, and check delivery progress. Platform operators maintain these services. Authors and approvers decide policy content.

Choose an Operational Task

Choose the task that matches the required evidence or change:

• Refer to background processing to distinguish the workers, their effective cadence, and their stop controls.
• Refer to automatic recompilation to understand fresh-input cycles, compilation minors, unchanged output, and failed-cycle recovery.
• Refer to observation and restarts to inspect process health, metrics, operation history, and restart boundaries.
• Refer to backup and restore for database recovery. Do not restore data merely to clear a publication warning.

Follow an Incident From Evidence to Recovery

Complete the following steps:

1. Record the affected policy identifier, approved version, error message, and time.
2. Check API logs for the last recompilation outcome using observation and restarts. If compilation succeeded but delivery stopped, inspect the policy’s latest request in Operations.
3. Use the reported error to select recompilation troubleshooting or publication troubleshooting. Each guide identifies the administrator who can resolve the problem.
4. Repeat the failed check after the administrator corrects the cause.
5. Follow the Data or Guardrails verification guide after publication succeeds.

Deployment retry resends retained artifacts. It does not request recompilation. Policy exposes no public automatic-recompilation run-now endpoint. Do not restart the API as a forced compilation trigger.

Continue to recovery playbooks for publication or ownership incidents, and API recovery for authorized inspection and commands.

2.1 - Background Processing and Cadence

The application programming interface (API) process owns Policy’s background services. They are not separate Kubernetes Deployments. Each service performs a different task. One successful worker does not prove another worker completed its work. Native import and publication use Policy Integration Manager (PIM).

Services and Defaults

The following table summarizes each background service, its default cadence, and its purpose:

The configuration guide explains the distinction between chart values, process environment, and credentials. Record effective settings for the running release rather than relying on this table.

Periodic services sleep before work and run serial cycles within each task. Execution and dependency waits add time to the configured interval. These intervals are not activation guarantees or service-level commitments. The current chart requires one API replica. Do not scale it for faster processing.

Startup Import and Discovery Freshness

PIM startup import defaults to enabled independently of periodic import. A startup import failure does not itself block API startup. Disabling periodic import does not disable that startup attempt. Periodic import also requires a configured PIM base address.

Import discovers existing native policies. It does not automatically adopt them into governed publication. Resolve ownership and legacy adoption through authorized workflows.

Disabling periodic catalog refresh leaves lazy first-request loading. A failed ordinary refresh can leave the prior snapshot available. Automatic recompilation applies a stricter fresh-input gate: it cannot silently compile from that retained snapshot.

Publication and Protection

Approval queues publication rather than performing every target write synchronously. The publication worker processes bounded batches of retained events. These events form the outbox, a database-backed queue that survives a process restart. The worker can finish a request, schedule another attempt, or stop after failure. A processed-event count is not a successful-publication count.

Default retry delays are 5, 15, 30, 60, and 300 seconds. Deterministic refusals can stop earlier than transient connectivity failures. Worker ownership leases default to 300 seconds. A lease temporarily reserves work for one worker. Terminal means automatic attempts have stopped, not that publication succeeded or the policy disappeared. After process loss, reclaiming unfinished work can wait for lease expiry. Restarting does not retry work whose automatic attempts have stopped.

Protection reconciliation evaluates revision-scoped evidence independently. It compares observations with the current governed revision and deployment generation. That generation distinguishes delivery operations. It is not the policy’s authored revision number. For Data, missing, old, or incomplete observations keep Policy from reporting Enforced. For Federated Guardrails, a matching receipt records consumer retrieval, not runtime activation. A policy using both targets needs complete Data observations and the matching Guardrails receipt. Refer to lifecycle and delivery.

Disablement and Stopping

A nonpositive polling interval disables the corresponding periodic service. It does not erase durable work, withdraw native policies, or grant a manual trigger. Stopping the API stops scheduling all its background services and interrupts user access. It does not stop independent consumers or undo native writes.

Use the configuration workflow for supported cadence changes. Refer to monitoring and restarts for a controlled process change. Do not repurpose database restore mode as an ordinary pause mechanism.

2.2 - Automatic Recompilation of Approved Policies

Policy’s application programming interface (API) periodically recompiles approved policies against fresh discovery and live Policy Integration Manager (PIM) inventory. Source changes can alter generated output without changing an author’s intent. This background check does not replace human review or approval.

For example, fresh discovery can associate another location with an existing classification. The same approved intent can then produce different target artifacts. The worker validates the refreshed set before accepting compilation changes. It does not react immediately to each discovery change event.

Scheduling and Effective Configuration

The backend setting policy_recompile_interval_seconds defaults to 300 seconds. The environment variable POLICY_RECOMPILE_INTERVAL_SECONDS supplies that setting. The shipped chart also defaults to 300 through this value:

apiService:
  environment:
    POLICY_RECOMPILE_INTERVAL_SECONDS: "300"

Nonpositive values disable periodic recompilation. The worker sleeps before its first cycle and between cycles. Execution time adds to the interval. Five minutes is not a completion deadline. Disabling scheduling preserves stored revisions and queued publication work. It neither withdraws policies nor disables the other workers.

Check the actual release values, generated configuration, and startup message. Do not assume source defaults match an existing installation. Refer to observation and restarts for nonsecret checks.

There is no public run-now endpoint for automatic recompilation. Restarting the API is not a supported immediate-trigger mechanism. The next process also sleeps before its periodic cycle.

Fresh Inputs and Set-Wide Validation

An eligible cycle refreshes discovery, then reads live PIM inventory. It pins those fresh inputs for compilation and peer validation. Pinning means using the captured inputs throughout that cycle, rather than mixing later refreshes into the same result. It validates both individual policies and their combined generated output. Changed source context can reveal conflicts that earlier inputs did not expose.

Failed discovery refresh does not permit recompilation from cached discovery. Unavailable live inventory also prevents acceptance. The catalog’s separate ability to retain an old snapshot does not relax this rule. An apparently usable catalog can therefore coexist with blocked recompilation.

Blocking compilation, validation, or persistence failures preserve the previous governed set. Policy does not accept a partially refreshed subset. This preservation concerns local governed state and queued work. It does not certify target availability or undo earlier external changes. Here, fail-closed means refusing an unsafe replacement while retaining previous governed state. It does not mean automatically denying all target traffic.

What Stays Unchanged

Automatic recompilation preserves:

• The author’s saved intent and the approval that authorized it.
• The original approval identity and decision information.
• Any open replacement draft, including unfinished or in-review work.
• Earlier governed revisions and their historical evidence.

System compilation history remains distinct from a person’s approval event. The worker records its compilation action rather than impersonating an approver. An author still needs the ordinary submission and approval workflow to change intent. Refer to states and revisions.

Changed and Unchanged Output

Changed accepted output creates compilation minor versions under the existing governed major revision. It also queues asynchronous publication work. This is not a new authored major revision or a new human approval.

Unchanged output creates neither compilation minors nor publication work. A successful cycle with no new version can therefore be normal. Do not treat an unchanged version number as proof that the worker stopped.

Successful compilation establishes that Policy accepted refreshed artifacts. Queued publication does not establish delivery. Publication and consumer receipt do not independently establish actual target protection. Continue through the delivery and lifecycle guidance for target-specific verification.

Outcomes and Operator Interpretation

Use this table to interpret recompilation outcomes and choose an operator response:

Concurrent governance can supersede work during compilation or persistence. Deferred work can include active publication constraints or legacy adoption requirements. Legacy deployments do not gain automatic governed adoption or publication. Some safe source-preserving scope updates can proceed automatically. Do not infer authorization for every native ownership change.

Observation and Recovery

An operator should collect the following evidence before changing configuration:

• Effective interval, process start time, and recent cycle timestamps.
• Policy count, failed-policy count, completion flag, and diagnostic phase.
• Superseded or deferred indicators and any returned reason.
• Current governed revision, compilation minor, and relevant open draft.
• Dependency availability, request identifiers, and later deployment generation.

The API logs an Approved policy recompilation summary for owned cycles. Inspect structured log fields where your logging platform retains them. Metrics count cycle outcomes. API logs provide the phase and reason. A blocked metric can represent blocked, superseded, or deferred work. Read the logged reason before changing a setting or retrying publication.

For a transient dependency failure, restore access and observe a later scheduled cycle. Do not substitute cached inventory or reduce the interval to bypass validation. For missing policy inputs or conflicts, ask the policy author and reviewer to correct and approve the proposed change. For legacy adoption or missing PIM mappings, ask the Policy administrator to follow ownership recovery. Do not edit database records, erase checkpoints, or manufacture approval evidence.

Publication retry sends the configuration saved for that delivery request. It does not incorporate corrected drafts or fresh discovery. The reviewer’s validation request checks a saved draft. It does not start automatic recompilation.

Refer to monitoring and restarts, publication recovery, and API recovery and reconciliation.

2.3 - Observe and Restart Policy

Use this task as the platform operator during routine checks or incidents. These diagnostic checks are not installation steps. Read the error before restarting. Restarting does not correct policy fields or missing Policy Integration Manager (PIM) object mappings. The application programming interface (API) process also owns background scheduling.

Prerequisites

Prepare the following:

• Set CTX to the intended Kubernetes context.
• Obtain workload-read access for logs, events, and configuration references.
• Obtain policy:observability for metrics and policy:audit for restricted operation evidence.
• Obtain separate deployment authority only when a restart requires it.
• Obtain your platform hostname, trusted certificate authority (CA) bundle, and current access token.

Configure API Access

Complete the credential-safe request setup with your own user token in a dedicated Bash session. Then set the deployment endpoint and trusted CA file in that same shell:

export FQDN='your-platform-hostname'
export PPC_CA_FILE='your-platform-ca.pem'
export POLICY_BASE_URL="https://${FQDN}/pty/policy/v1.0"
POLICY_API="$POLICY_BASE_URL"
: "${POLICY_AUTH_HEADER:?Complete authentication setup}"

Use the configured API root if your platform overrides the default. All requests use the protected POLICY_AUTH_HEADER file from the shared setup. Do not include token values in logs or support records. Follow credential cleanup when you finish.

Neither audit access nor a support reference grants recovery mutation authority. Do not grant policy_admin merely to collect evidence. Use the permission reference.

Inspect Effective Scheduling

Complete the following steps:

1. Read the release’s nonsecret values.

   helm --kube-context "$CTX" --namespace pty-policy get values policy
   

   Keep credentials out of the evidence record. Review approved image identities alongside these values.

2. Read the generated recompilation interval.

   kubectl --context "$CTX" --namespace pty-policy get configmap policy-api-config \
     -o jsonpath='{.data.policy_recompile_interval_seconds}{"\n"}'
   

   The default chart produces 300. A nonpositive value disables scheduling. Use the configured name if your release changes apiService.containerName.

3. Verify the deployment binds POLICY_RECOMPILE_INTERVAL_SECONDS to that key. Inspect only the relevant nonsecret section of the workload specification. A value elsewhere in a file does not establish the running process’s configuration.

4. Read recent API logs.

   kubectl --context "$CTX" --namespace pty-policy logs \
     deployment/policy-api --container policy-api --since=30m
   

   Look for the startup interval message and subsequent cycle summaries. Retain timestamps, diagnostic phases, and superseded or deferred reasons. Redact sensitive details before sharing logs.

Source defaults and generated configuration can differ from a process that has not restarted after a change. Do not print the full process environment. For supported deployment settings, refer to configuration.

Inspect Health and Progress

Complete the following steps:

1. Inspect health through the authenticated gateway.

   curl --cacert "$PPC_CA_FILE" --fail-with-body --include \
     --header "@${POLICY_AUTH_HEADER:?Complete authentication setup}" "$POLICY_BASE_URL/live"
   curl --cacert "$PPC_CA_FILE" --fail-with-body --include \
     --header "@${POLICY_AUTH_HEADER:?Complete authentication setup}" "$POLICY_BASE_URL/ready"
   curl --cacert "$PPC_CA_FILE" --fail-with-body \
     --header "@${POLICY_AUTH_HEADER:?Complete authentication setup}" "$POLICY_BASE_URL/health"
   curl --cacert "$PPC_CA_FILE" --fail-with-body \
     --header "@${POLICY_AUTH_HEADER:?Complete authentication setup}" "$POLICY_BASE_URL/version"
   

   Liveness returns Hypertext Transfer Protocol (HTTP) 204 for a responding process. Readiness returns empty 204, or 503 when a startup prerequisite fails. Health and version return JavaScript Object Notation (JSON) responses. Structured health can report lifecycle degradation with HTTP 200. A 401 requires valid authentication. A 403 requires the appropriate permissions.

2. Inspect metrics with observability authority.

   curl --cacert "$PPC_CA_FILE" --fail-with-body \
     --header "@${POLICY_AUTH_HEADER:?Complete authentication setup}" "$POLICY_BASE_URL/metrics"
   

   Expect Prometheus text, not JavaScript Object Notation (JSON). The outbox is the durable queue of publication and withdrawal events. Terminal work has stopped automatic attempts. An operator must investigate before selecting recovery. The following metrics help distinguish stalled work:

   Metric	Interpretation
   pmx_policy_recompilation_total	Count cycle outcomes as complete, blocked, skipped, or error.
   pmx_policy_recompilation_last_pass_success	Report whether the last owned cycle completed.
   pmx_policy_recompilation_failed_policies	Count failed policies in the last owned cycle.
   pmx_policy_recompilation_last_success_timestamp_seconds	Record the current process’s last successful cycle time.
   pmx_policy_outbox_pending	Count retained pending publication or withdrawal work.
   pmx_policy_outbox_oldest_age_seconds	Measure age since the oldest pending event’s creation.
   pmx_policy_outbox_terminal	Count retained terminal work requiring investigation.

   Recompilation counters and last-success metrics reset with the process. Skipped cycles do not replace the last owned result. Repository-backed queue gauges refresh on scrape.

3. Inspect affected policies through permitted history and operation reads. Use the recovery API guide. Record revision, deployment generation, attempts, diagnostics, and replacement information.

4. Use the error message to select recompilation troubleshooting or publication recovery. Send connection failures to the named integration’s administrator and policy conflicts to the policy author and reviewer.

Do not infer protection from healthy services, an empty queue, or a successful cycle. Verify target-specific evidence and actual target behavior independently. Refer to automatic recompilation outcomes to distinguish unchanged, blocked, superseded, and deferred work.

Restart Under Change Control

Complete the following steps:

1. Capture current logs, metrics, deployment generations, and pending work. If a PIM request lost its response, ask the PIM administrator to check whether the change completed before restarting.

2. Confirm the restart uses the same approved image and database schema.

3. Restart the default API Deployment during the approved outage window.

   kubectl --context "$CTX" --namespace pty-policy rollout restart deployment/policy-api
   

   Expect service interruption with the single-instance deployment. This restarts all process-owned background services.

4. Wait for rollout completion.

   kubectl --context "$CTX" --namespace pty-policy rollout status \
     deployment/policy-api --timeout=5m
   

   If startup waits or fails, inspect schema checks, credentials, and events. Do not weaken readiness or runtime privileges to bypass the failure.

5. Repeat authenticated verification and inspect later worker cycles. Check that pending operations resume after existing worker leases expire. Use publication recovery for operations that stopped after failure.

Normal shutdown waits for active recompilation and publication work. The chart’s termination grace period is 30 seconds. Long external calls can exceed it. Shutdown does not guarantee every write drained. Preserve uncertain-write evidence and follow recovery.

For an approved extended stop, use your deployment-management pause procedure. Confirm no controller or Helm reconciliation will restart the API unexpectedly. Do not delete credentials, claims, or database rows to stop processing. On resumption, recheck external state and retained work before declaring recovery.

Related: Background processing, automatic recompilation, and backup and restore.

3 - Policy Frequently Asked Questions

These answers cover the application programming interface (API), governance, delivery, and administration. For terms such as draft head, compilation minor, and native binding, use the glossary.

Where Is the Policy API Exposed?

Use the gateway base configured for your installed release. Find the route and discovery links in the API guide. Do not assume the API base from the documentation URL.

Can Different People Submit and Approve?

Yes. The author and reviewer can use different authenticated accounts. Each needs the capabilities for the operation they perform. Policy ownership alone does not grant approval authority. Refer to roles and permissions.

Does Approval Mean Data Protection Is Active?

No. Approval commits a governed revision and queues asynchronous delivery. Publication and target-specific evidence require separate verification. Refer to states and revisions.

Can a Draft Change the Current Governed Policy?

Saving proposed work does not replace the governed revision. The replacement must complete its own review and approval. Refer to lifecycle and governance.

Why Did a Compilation Minor Appear Without Another Approval?

Automatic recompilation can generate changed output from already approved intent. It preserves approval identity and leaves open drafts unchanged. Refer to automatic recompilation.

Does Retry Compile My Corrected Draft?

No. Deployment retry continues retained work for the existing generation. Corrected authored input requires the applicable save, submission, and approval workflow. Refer to recovery playbooks.

Can I Inspect Diagnostics With Only a Support Reference?

No. Restricted diagnostics also require audit authority. An author can collect safe error context and ask an authorized operator for help. Refer to diagnostics.

Does Policy Require PostgreSQL?

Yes. PostgreSQL runs inside the deployed Policy stack. Back up retained state before consequential recovery or removal. Refer to Installation.

Is pmx_app Another Account That I Must Create?

No. pmx_app is a fixed PostgreSQL permission role, not a login account. Database startup creates it with NOLOGIN and grants membership to the configured runtime login. Bootstrap applies the restricted application grants. It has no password or credential Secret, and backup must not inherit it. Refer to database accounts.

What if Policy Is Installed After Traverse?

Check the known identity provider (IdP) backfill issue. Save the existing IdP connection details again in Traverse.

How Do I Verify Policy Is Healthy?

Distinguish process liveness, readiness, dependency checks, and completed delivery. A healthy service does not prove that a particular policy protects its targets. Refer to installation verification and System operations.

How Is Authentication Handled?

Use the platform’s supported sign-in or gateway authentication path. Do not impersonate forwarded identities or share another user’s credentials. Refer to API authentication.

How Do I Remove Policy Completely?

Decide retention and downstream withdrawal requirements before uninstalling. Removing a release does not itself prove downstream deprotection. Refer to Uninstallation.

Return to Policy or Troubleshoot.