Install

• 1: Prerequisites
• 1.1: Installation Accounts and Permissions
• 2: Installing Policy
• 3: Creating Policy Users

1 - Prerequisites

Complete these steps before installing Policy on a Protegrity Provisioned Cluster (PPC). Use a PPC user with administrator permissions to create users and assign roles. This guide calls that user a PPC administrator.

Required Products

Ensure that PPC, Policy Workbench, and Traverse are installed. Ensure that Policy Integration Manager (PIM) is initialized through the Workbench setup. Use the Workbench installation instructions for Amazon Web Services (AWS) or Microsoft Azure.

• Traverse is installed
• Traverse is not installed

If you configured directory connections before installing Policy, save those connection details again after Policy installation. See the IdP backfill issue for the identity provider (IdP) connection steps.

Connect to PPC

Use the Kubernetes connection established during PPC installation. Run the Bash examples in a terminal with Helm, kubectl, jq, and OpenSSL available. All installation commands use the active Kubernetes context:

kubectl config current-context

The output should identify your PPC cluster. For connection instructions, refer to your PPC installation documentation.

PPC Storage and Release Defaults

Policy uses the shared pty-main gateway in api-gateway and the nfa-config ConfigMap in default. These are PPC platform resources, not values you need to supply for a standard installation.

The chart uses PPC’s STORAGE_CLASS and BACKUP_STORAGE_CLASS settings. It creates separate persistent volume claims for the database and logical backups, each requesting 10Gi. It also configures the database accounts and permissions. You do not need to create storage classes, volumes, or database grants manually.

The installation command selects chart version 1.1.0. The chart supplies its application and database image versions and reads the workload registry from PPC. You only need the Open Container Initiative (OCI) chart-registry host from your release distribution. The installation procedure checks whether PPC requires an image-pull Secret and, if so, copies it into the Policy namespace.
For more information about provisioning registry pull secret, refer to Provision the Registry Pull Secret.

Create PPC Service Users

Helm creates database users, but it does not create PPC integration users. Create the two service users once during preparation:

1. Log in to the PPC command-line interface (CLI) as a PPC administrator. Follow Accessing the PPC CLI to connect and sign in to the CLI Manager.

2. Create the token-login role if it does not already exist:

   admin create roles --name policy_service_login --permissions "can_create_token"
   

3. Create the PIM service user:

   admin create users --username pmx.pim.service --roles "workbench_administrator,policy_service_login" --password "<pim-service-password>"
   

4. Create the Traverse service user:

   admin create users --username pmx.traverse.poller --roles "discoverx-automation-client,discoverx-admin,policy_service_login" --password "<traverse-service-password>"
   

   Replace the password placeholders with separate passwords that satisfy PPC’s password policy. Run credential-setting commands in a protected CLI Manager session without command recording. If PPC prompts for a first-login password change, use the final password in the files below.

5. List PPC users:

   admin list users
   

   The output includes the usernames and identifiers of the users you created. Roles are assigned during creation, so no separate user-identifier lookup or role-update command is required.

These users authenticate Policy’s background connections to PIM and Traverse. Policy obtains and refreshes their tokens using the credentials you provide. They are separate from the named PPC accounts people use to sign in. See accounts and permissions for the permission reference.

Prepare Credential Files

Return to the Bash terminal you will use for Helm installation. This guide stores local credential files under the following directory:

$HOME/.config/protegrity/policy/credentials

These are files you create, not preinstalled PPC files. The installation commands below use this location directly. Keep the directory private and outside source control.

Database Credentials

Run this block once to create three database usernames and generate their passwords:

(
  set -e
  set +x
  set -o noclobber
  umask 077
  mkdir -p "$HOME/.config/protegrity/policy/credentials"
  chmod 700 "$HOME/.config/protegrity/policy/credentials"
  for role in maintenance runtime backup; do
    printf '%s' "policy_${role}" > "$HOME/.config/protegrity/policy/credentials/${role}-username"
    password=$(openssl rand -base64 32)
    printf '%s' "$password" > "$HOME/.config/protegrity/policy/credentials/${role}-password"
  done
)

The block creates six files and refuses to overwrite existing files. Helm uses these credentials to create the database logins and their grants. Database provisioning automatically creates pmx_app, a PostgreSQL NOLOGIN permission role, and grants it to runtime. You do not create or validate these database accounts yourself.

PPC Service Credentials

Save the passwords you assigned to the PPC service users:

(
  set -e
  set +x
  set -o noclobber
  umask 077
  printf '%s' 'pmx.pim.service' > "$HOME/.config/protegrity/policy/credentials/pim-username"
  printf '%s' 'pmx.traverse.poller' > "$HOME/.config/protegrity/policy/credentials/traverse-username"
  for service in pim traverse; do
    read -r -s -p "Password for the ${service} service user: " password
    printf '\n'
    if [ -z "$password" ]; then
      printf 'A service-user password is required.\n' >&2
      exit 1
    fi
    printf '%s' "$password" > "$HOME/.config/protegrity/policy/credentials/${service}-password"
  done
)

The prompts hide each password. Use the existing PPC passwords. Do not generate replacements for these users.

Additional Prerequisites

Use the same Bash terminal and active Kubernetes context as the prerequisite steps. These instructions install a new Policy deployment. Set the Open Container Initiative (OCI) chart-registry host supplied with your release:

export POLICY_REGISTRY_HOST='<oci-registry-host>'

Replace the placeholder with the host, including a port if required. The following command installs chart version 1.1.0. Its other settings use PPC defaults. If the chart registry requires authentication, log in:

helm registry login "$POLICY_REGISTRY_HOST"

Helm prompts for registry credentials. The chart registry can differ from PPC’s workload-image registry.
This login authenticates Helm only. It does not authorize cluster nodes to pull workload images. For more information, refer to Provision the Registry Pull Secret.

Continue to Installation

Continue to install the Policy Helm chart.
For more information about installing Policy, refer to section Installing Policy. The procedure creates Kubernetes Secrets from these files and installs Policy with the standard PPC defaults.

1.1 - Installation Accounts and Permissions

Policy uses separate database logins, dependency users, and Kubernetes workload identities. These accounts serve different purposes and cannot replace one another. Protegrity Provisioned Cluster (PPC) administrators prepare dependency users before installation. Database operators prepare credentials for PostgreSQL inside the Policy stack.

Use this reference with installation preparation and fresh installation. Default Secret names below apply in the pty-policy release namespace. Use your configured names when the release overrides them.

Database Accounts

The chart defines default Secret names, but no default database usernames or passwords. Choose three distinct login names and independently managed passwords. The example usernames below are suggestions, not chart defaults. Each Secret contains postgres_user and postgres_password. The default database name is policy. Database provisioning also creates the fixed PostgreSQL pmx_app permission role and grants it to runtime. This NOLOGIN role is not a fourth login, platform user, or credential Secret.

The following table lists the database accounts, their permissions, and default Secrets:

Database startup creates missing workload roles from these credentials. The separate bootstrap Job installs the schema and application grants. Operators supply the Secrets. The chart handles account creation and permission checks. No manual database grants or account-validation steps are required. Do not create platform users for these PostgreSQL logins.

The chart creates all three logins without SUPERUSER, CREATEDB, CREATEROLE, REPLICATION, or BYPASSRLS. Maintenance owns objects within the Policy database, not the PostgreSQL cluster. Never use its credentials for ordinary application programming interface (API) traffic. Runtime and backup do not own application objects or assume administrator roles.

Runtime and Backup Privileges

This section explains the database permissions that installation configures automatically. Use it to understand the account separation or investigate a database privilege-check failure. It does not require additional account creation or manual permission grants.

The Policy API uses the runtime database login, such as policy_runtime, to read and update application data. Backup Jobs use a separate login, such as policy_backup, to read data for database dumps. The backup login does not need write access.

PostgreSQL roles can group permissions without serving as login accounts. Policy uses the fixed pmx_app role to group its restricted application permissions. Database provisioning creates this role and assigns membership to the runtime login. Membership lets that login use the role’s permissions. The bootstrap Job configures the grants listed below.

The NOLOGIN setting prevents direct sign-in as pmx_app. This role needs no password or Kubernetes Secret. Installation keeps the backup login outside this role so that it cannot inherit application write permissions. Supply credentials only for the maintenance, runtime, and backup logins described above.

The table compares the resulting permissions of the runtime and backup logins:

Runtime does not have unrestricted create, read, update, and delete access. Its grants preserve protected history while allowing necessary application operations. An allowlist means explicit grants on selected tables or columns, rather than a blanket write grant. For protected records, permitted updates include draft closure, revision supersession, and access-grant revocation metadata. They do not permit rewriting saved authored snapshots.

The derived and compatibility tables with insert, update, and delete grants are:

• policy_versions, policy_decisions, policy_statements, policy_element_refs, and policy_artifacts.
• product_policies, securequery_profiles, securequery_profile_revisions, securequery_capability_manifests, and harmonization_identity.

Bootstrap checks effective privileges, including inherited access. Extra role memberships or public grants can cause startup checks to fail. Do not add broad grants to bypass a failed check.

The postgres identity remains a separate local administration account. Database provisioning clears its network password. Do not expose it or supply it to application workloads.

Naming, Retained Storage, and Rotation

Choose nonempty, distinct usernames of at most 63 bytes. Do not use postgres, pmx_app, or the reserved pg_ prefix. Usernames and passwords must not contain control characters.

Keep the same usernames when reusing database storage. Provisioning rejects changes to the recorded workload names. Changing a Secret name does not migrate database ownership or split a legacy login. Ask the database administrator for a tested ownership-migration procedure before converting an existing database.

Coordinate password rotation across database provisioning and affected workloads. A Secret update alone does not update an existing PostgreSQL password or running environment. Preserve the current credentials and recovery evidence until verification succeeds. Follow configuration changes and backup and restore boundaries.

Dependency Service Users

Create two dedicated regular users in PPC. The following usernames are the documented installation convention. Helm does not create these users or enforce their names. The username in each Secret must match the actual provisioned account. Retain the compatibility identifiers exactly as shown when using this convention.

The following table lists integration users and their required access:

Each dependency Secret contains username and password. Policy supplies these values through the corresponding PIM_* or TRAVERSE_* environment. Both integrations default to the /pty/v1/auth/login/token endpoint. Token login accepts form fields named loginname and password. A successful check returns Hypertext Transfer Protocol (HTTP) 200 and a nonempty pty_access_jwt_token response header. Never print or retain that header in shared logs.

Shared Token-Login Role

The platform administrator creates policy_service_login before installing Policy. Its exact permission set contains only can_create_token. This permission permits token creation and refresh, not dependency access. Keep the role assigned after installation.

Manage this custom role outside the Policy chart’s product configuration. Dependency users do not need the human policy_viewer, policy_author, or policy_admin roles. Do not modify those chart-managed roles to obtain service login. Confirm custom-role support and effective access on the selected platform release.

PIM Permissions and Caller Attribution

The documented workbench_administrator role supplies these permissions:

This bundle grants broader access than a read-only inventory account. workbench_viewer supplies workbench_management_policy_read, not the required writes. Do not substitute that role merely because inventory reads or token login succeed. Before narrowing this mapping, ask the PIM administrator to test inventory reads, publication, and withdrawal with the replacement permissions. See Workbench roles and permissions.

Inventory reads, startup import, and background publication or withdrawal use the service user. Request-driven PIM mutations instead use the calling human’s forwarded token. That human needs their own Workbench permissions for the requested operation. Policy does not silently substitute the worker account after caller authorization fails.

Traverse Permissions and Visibility

The following table summarizes the Traverse roles and their permissions:

Traverse administrator access does not include the automation role’s state-write permission. Keep both dependency roles. Without administrator visibility, login can succeed while the datastore list remains empty. The current integration therefore retains a broad administrator compatibility requirement. Do not share this account with human users or unrelated workloads. Keep both roles until the Traverse integration supports narrower permissions for these operations.

Every Traverse interaction uses the service user, not a human’s forwarded token. Existing installations can use the legacy pmx.discoverx.poller username. Use its actual verified credentials rather than renaming a working account during installation.

Kubernetes and Directory Identities

Kubernetes ServiceAccounts are not PPC users or PostgreSQL logins. The chart creates policy-api, policy-panel, and policy-db by default. They follow the corresponding workload containerName settings. The chart disables service-account token automount for these identities.

Traverse also uses a scanner ServiceAccount for shared identity provider (IdP) metadata. The default scanner is discoverx-discoverx-scanner in the discoverx namespace. Configure idpSecret.writer for the actual scanner identity in your deployment. Policy grants that identity only patch on the named discoverx-idp-connections Secret in the Policy namespace. It does not grant general Secret read, list, create, or delete access. This Kubernetes permission does not replace the poller’s Traverse roles.

Directory bind and provider credentials remain separate, source-specific identities. Policy defines no default directory bind username. Do not reuse database or dependency service passwords for directory access. Registry pull credentials likewise remain platform-owned.

2 - Installing Policy

This section describes the steps to install and verify Policy. Ensure that all the prerequisites for installation have been met.
For more information about the prerequisites, refer to Prerequisites.

Create the Namespace

Create the Policy namespace:

kubectl create namespace pty-policy

Continue to Provision the Registry Pull Secret.

Provision the Registry Pull Secret

Policy workload images are downloaded from the PPC workload-image registry. This can differ from the chart registry you logged in to with helm registry login. This login enables Helm to download the chart. It does not let the cluster nodes pull images. If the Secret is needed and missing, then the pods fail with ErrImagePull or ImagePullBackOff.

Perform the following steps to provision the registry pull secret:

1. Read the Secret name configured by PPC:

export REGISTRY_SECRET_NAME="$(kubectl --namespace default get configmap nfa-config \
  -o jsonpath='{.data.REGISTRY_SECRET_NAME}')"
echo "REGISTRY_SECRET_NAME=${REGISTRY_SECRET_NAME:-<empty>}"

If the value is empty, the nodes authenticate to the registry themselves. Skip to Database Credentials.
For more information refer to Database Credentials.

2. If the value is set, copy the Secret into the Policy namespace. Replace default if your PPC platform namespace differs.

kubectl --namespace default get secret "$REGISTRY_SECRET_NAME" -o json \
  | jq -c '{apiVersion, kind, type, data, metadata: {name: .metadata.name, namespace: "pty-policy"}}' \
  | kubectl create -f -

If the command reports AlreadyExists, do not overwrite the Secret. Verify it in the next step.

3. Verify the Secret:

kubectl --namespace pty-policy get secret "$REGISTRY_SECRET_NAME"

The TYPE must be kubernetes.io/dockerconfigjson. Resolve any error before continuing.

The chart references only the Secret’s name and never reads or copies its data through Helm. The copy is not synchronized. When the platform Secret is renewed or replaced, update the copy in pty-policy.

Database Credentials

Create the three database Secrets from the files prepared in prerequisites:

(
  set -e
  for role in maintenance runtime backup; do
    kubectl --namespace pty-policy create secret generic "policy-db-${role}" \
      --from-file="postgres_user=$HOME/.config/protegrity/policy/credentials/${role}-username" \
      --from-file="postgres_password=$HOME/.config/protegrity/policy/credentials/${role}-password"
  done
)

The commands create policy-db-maintenance, policy-db-runtime, and policy-db-backup. They read passwords from the protected files without printing them. For managed credential delivery instead, see credential handling.

PPC Service Credentials

Create the integration Secrets from the prepared PPC user credentials:

(
  set -e
  for service in pim traverse; do
    kubectl --namespace pty-policy create secret generic "${service}-credentials" \
      --from-file="username=$HOME/.config/protegrity/policy/credentials/${service}-username" \
      --from-file="password=$HOME/.config/protegrity/policy/credentials/${service}-password"
  done
)

The commands create pim-credentials and traverse-credentials. Policy uses these users to obtain and refresh dependency access tokens.

Install the Chart

Run the following command:

helm install policy "oci://${POLICY_REGISTRY_HOST}/policy/helm/policy" \
  --version 1.1.0 \
  --namespace pty-policy \
  --wait --wait-for-jobs --timeout 15m

The standard installation does not require a separate values file. For nondefault settings, append --values customer-values.yaml with your configuration file. See configuration for supported overrides.

The chart automatically:

• Deploys the Policy API, Panel, and in-stack PostgreSQL.
• Creates the database logins from the supplied credentials.
• Configures pmx_app membership and database permissions.
• Initializes the application schema through the bootstrap Job.
• Registers the built-in Policy roles and gateway authorization resources.
• Creates storage claims using PPC’s configured storage classes.
• Configures startup, readiness, and liveness probes.

Database provisioning automatically creates pmx_app, a PostgreSQL NOLOGIN permission role, and grants it to runtime. The wait options keep Helm running until workloads and bootstrap Jobs are ready. You do not need to inspect database grants, repeat health probes, or recheck chart-created roles.

If Helm fails, use installation troubleshooting. Keep the credential files until installation completes and you store the credentials through your normal secret-management process.

After Helm completes, follow Creating Policy users to create or assign the named PPC account that will sign in. The chart registers the built-in roles. You assign them to people separately.

Verifying the Installation

Helm waits for workloads and database bootstrap through the command’s wait options. No separate installer checks of database grants, built-in roles, or health probes are required. Complete these steps with your assigned PPC account:

1. Get the Policy web address from PPC:

   kubectl --namespace default get configmap nfa-config \
     -o jsonpath='https://{.data.FQDN}/pty/policy/v1.0/ui/{"\n"}'
   

   The command uses the PPC cluster’s fully qualified domain name (FQDN). Use your configured path if your installation overrides the default.

2. Open that address in your browser and sign in with your named PPC account.

3. Open the Policy Library.

   The Library displays the policies you can access. An empty list is normal before anyone creates a policy.

If you cannot open Policy or sign in, use installation and access troubleshooting.

If you configured Traverse directory connections before installing Policy, the connection owner may need to save those details again. See the identity provider (IdP) backfill issue.

3 - Creating Policy Users

People sign in to Policy with named Protegrity Provisioned Cluster (PPC) accounts. The Policy Helm chart registers the built-in roles during installation. A PPC user with administrator permissions assigns these roles to people. Human accounts are separate from the integration service users prepared in prerequisites.

Prerequisites

Complete Policy installation before assigning its chart-created roles. Use a PPC account with administrator permissions to manage users.

Policy Roles

Choose the role required for the person’s tasks:

Use the authorization reference for capability details and policy-specific grants. Do not grant administrative access merely to provide author or read-only access.

Create a Policy User

Complete these steps in the PPC command-line interface (CLI):

1. Log in to the PPC CLI as a PPC user with administrator permissions. See Accessing the PPC CLI.

2. Create an author account:

   admin create users --username <username> --email <email> --first-name <first-name> --last-name <last-name> --password "<password>" --roles "policy_author"
   

   Replace the placeholders with the person’s account details. Run credential-setting commands in a protected CLI Manager session without command recording. For read-only access, use policy_viewer instead of policy_author.

3. List PPC users:

   admin list users
   

   The output includes the account you created.

For an existing user, follow PPC user management. Include every role the account must retain when changing its roles. Updating a user’s roles replaces the existing role list.