Protegrity Agent

• 1: Prerequisites
• 2: Installing Protegrity Agent
• 3: Creating Agent Users
• 4: Configuring BYOM
• 5: Accessing the Agent
• 6: Upgrading the Agent to v1.2.0
• 6.1: Migrating conversation ownership
• 6.2: Preparing database credentials
• 6.3: Upgrading the Agent to v1.2.0
• 6.4: Decommissioning the connection to PIM
• 6.5: Migrating users
• 7: Uninstalling the Agent

1 - Prerequisites

The following requirements are met before installing Protegrity Agent v1.2.0 with PPC v1.2.0.

Infrastructure

• The jumpbox is registered and prepared.
  For more information, refer to Configuring Authentication for Protegrity AI Team Edition.

• Access to the OCI registry is available.

Protegrity Provisioned Cluster

A PPC cluster is installed and accessible.
For more information, refer to Installing PPC.

Protegrity Traverse and Policy

Ensure that the Protegrity Traverse and Policy Features must be installed.

To verify the Protegrity Traverse is installed, run the following command:

kubectl get pods -n discoverx

To verify the Policy is installed, run the following command:

kubectl get pods -n pty-policy

Tools

Ensure that the following tools are available.

Configuring kubectl

Ensure that the kubectl is configured against the target cluster.

• For AWS
• For Microsoft Azure

aws eks update-kubeconfig --name <cluster-name> --region us-east-1 --alias <cluster-name>

az aks get-credentials --resource-group <resource-group> --name <cluster-name>

Verifying cluster name

Verify that the correct cluster is used before proceeding.

kubectl config current-context

Note (Azure): The PPC AKS clusters are private (*.privatelink.<region>.azmk8s.io). After fetching credentials, confirm the API is reachable using kubectl get ns command.
If the system hangs, then the cluster needs a private network path, such as VPN, jumpbox, or private DNS.

Cloud Vendor ConfigMap

The Helm chart uses the CLOUD_VENDOR key to determine which cloud provider-specific resources are to be deployed.

Ensure that the CLOUD_VENDOR key is present and set to the appropriate value for the target environment, such as aws or azure. If the key is missing or incorrectly configured, the chart may render resources that are not supported by the target platform, causing the installation to fail.

To verify this before installing, run the following command:

kubectl get configmap nfa-config -n default -o jsonpath='{.data.CLOUD_VENDOR}{"\n"}'

• For Azure, the AKS: value must be "azure".
• For AWS, the AWS/EKS: value must be "aws" or empty.

The ARCHITECTURE key (amd64 | arm64, default amd64) for' arm64 architecture uses Azure Ampere nodes in Azure and AWS Graviton nodes in AWS.

Supported Models

The Protegrity Agent requires an administrator to configure the underlying LLM models before any usage. The model configuration is provided by the organization’s administrator. Both an LLM chat model and an embeddings models must be configured.

When configuring a model, the BYOM CLI requires several mandatory configuration fields. These values must be obtained from the selected model provider and supplied during the configuration process.

The following are the models supported by Agent v1.2.0.

Supported LLM providers

¹ For azure-openai, model is the Azure deployment name. ² For google-gemini, sa_json is the full contents of the Vertex AI service-account JSON key file.

Supported Embedding providers

Embedding models are a fixed allowlist — only the exact model shown below is accepted per provider.

¹ For azure-openai, model is the Azure deployment name. ² For google-gemini, sa_json is the full contents of the Vertex AI service-account JSON key file.

Note: Anthropic does not offer an embedding API. Use voyage, openai, or azure-openai for embeddings when your LLM is Anthropic.

2 - Installing Protegrity Agent

The Protegrity Agent v1.2.0 can be installed using helm chart 2.0.0. The helm chart deploys the following components.

Installing Protegrity Agent

Perform the following steps to install Protegrity Agent.

1. Creating Namespaces and Database Secrets

The namespaces and Database secrets must be created only once per cluster. These can be reused for subsequent upgrades and re-installs. Ensure to only replace the Secret when rotating credentials.

To create Namespaces and Database Secrets, run the following command:

kubectl create namespace pty-protegrity-agent --dry-run=client -o yaml | kubectl apply -f -

kubectl -n pty-protegrity-agent create secret generic database-secrets \
  --from-literal=postgres_user=agentuser \
  --from-literal=postgres_password="$(openssl rand -base64 32)"

2. Copying the Registry Pull Secret

Before installing the Helm chart, copy the registry pull secret into the pty-protegrity-agent namespace. By default, the secret is named harbor-secret in the default namespace:

kubectl get secret harbor-secret -n default -o json |
  jq '{
    apiVersion, kind, type, data,
    metadata: {name: "harbor-secret", namespace: "pty-protegrity-agent"}
  }' |
  kubectl create -f -

Note: This is one-time provisioning. When credentials are rotated, the destination secret in pty-protegrity-agent must be updated separately.

3. Verifying the secret exists

To verify that the secret exists and has the expected type kubernetes.io/dockerconfigjson, run the following command:

kubectl get secret harbor-secret -n pty-protegrity-agent

4. Installing the Helm Chart

To install the helm chart, run the following command:

helm upgrade --install protegrity-agent \
  oci://<Container_Registry_Path>/protegrity-agent/helm/protegrity-agent \
  --version 2.0.0 \
  --namespace pty-protegrity-agent

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443

Verifying the installation

To verify the installation, run the following command:

kubectl get pods -n pty-protegrity-agent -w

Ensure the status of the pods is Ready.

3 - Creating Agent Users

Agent users must have one or more roles that determine their permissions and capabilities.

The Protegrity Agent Helm chart creates the required roles during installation. Assign them to separate PPC user accounts or combine them with other roles on a single account. To assign multiple roles, provide a comma-separated list.

When assigning Agent roles to an account that already has roles for other PPC products or features, include every role the account should retain. Updating a user’s roles replaces the existing role list. For instructions on creating users and managing role assignments, see the PPC Admin CLI user-management instructions.

Each role grants the capabilities listed in the following table. The following roles are created during installation.

Note: To access the Insight logs, assign the security_viewer role.

Note: To access the Agent panel, assign the agent-user role.

Creating users

To create the users, perform the following steps:

1. Log in to the PPC CLI and sign in to the CLI Manager as the admin user. For instructions on connecting over SSH and signing in, see Accessing the PPC CLI.

   ssh -i ~/.ssh/<cluster_name>_user_svc -p 22 admin@<user-provided-fqdn>
   

2. To create a user with agent-user role, run the following command:

   admin create users --username <username> --email <user email> --first-name <firstname> --last-name <lastname> --password <"Password"> --roles "agent-user"
   

3. To create a user with agent-model-administrator role, run the following command:

   admin create users --username <username> --email <user email> --first-name <firstname> --last-name <lastname> --password <"Password"> --roles "agent-model-administrator"
   

Verifying the required users

To verify if the required users are successfully created, run the following command:

admin list users

4 - Configuring BYOM

Supported Models

When configuring a model, the BYOM CLI requires several mandatory configuration fields. These values must be obtained from the selected model provider and supplied during the configuration process.

For more information about the supported models and configurations, refer to Supported Models.

Configuring BYOM

Before you begin

If a PPC CLI session was opened before installing the Agent, it will not detect the new installation. After installing the Agent, start a new PPC CLI session before configuring BYOM. Do not reuse an existing session. This applies whenever you configure or update BYOM, not only immediately after installation. If the base Agent URL has changed, exit all existing sessions gracefully and start a new session so it uses the updated URL.

Configuring BYOM

To configure BYOM, perform the following steps:

1. Log in to the CLI using an user with agent-model-administrator permissions.

2. To fetch the current model, run the following command:

   agent get model-config
   

3. To configure the model configuration, run the following command:

   agent set model-config \
   --chat      '{"provider": "<provider-name>", "api_key": "<your-provider-key>", "model": "<required model>"}' \
   --embedding '{"provider": "<provider-name>", "api_key": "<your-provider-key>", "model": "<required model>"}'
   

   For more information about the required values, refer to Supported Models.

   The following is an example using Anthropic Claude and VoyageAI.

   agent set model-config \
    --chat      '{"provider": "anthropic", "api_key": "<your-anthropic-key>", "model": "claude-sonnet-4-6"}' \
    --embedding '{"provider": "voyage",    "api_key": "<your-voyage-key>",    "model": "voyage-3"}'
   

4. To patch the model configuration, run the following command:

   agent patch model-config \
    --chat '{"provider": "<provider-name>", "api_key": "<your-provider-key>", "model": "<required model>"}'
   

   The following is an example using Anthropic Claude and VoyageAI.

   agent patch model-config \
    --chat '{"provider": "anthropic", "api_key": "<your-anthropic-key>", "model": "claude-sonnet-4-6"}'
   

5 - Accessing the Agent

To access the Protegrity Agent in the Web UI, use a PPC user account assigned the agent-user role. For example, you can create an account named proagent-user. For instructions, refer to Creating Agent Users.

Access the Agent using the FQDN provided during the installation process.

https://<cluster-FQDN>

Enter the following parameters to log in and view the homepage.

• Username: Username of the user with agent-user role.
• Password: Password of the user with agent-user role.

For more information about the credentials and role management, refer to Log in to PPC.

The Agent window appears on the screen.

6 - Upgrading the Agent to v1.2.0

Upgrading from Protegrity Agent v1.0 (Helm chart 1.0.0 or 1.1.0) to v1.2.0 (Helm chart 2.0.0) performs a one-time migration of the embedded database from PostgreSQL 17 to PostgreSQL 18. The upgrade process also updates the database schema to the version required by Protegrity Agent v1.0.

6.1 - Migrating conversation ownership

Protegrity Agent v1.0 does not track conversation ownership. All users with access to the Agent share a single pool of conversations.

Protegrity Agent 1.2.0 introduces per-user conversation ownership. As a result, conversations are visible only to their respective owners.

Because Agent v1.0 did not record the original creator of each conversation, the migration process cannot restore conversations to their original owners.

To migrate the ownership, select one of the following options:

In both migration scenarios, users other than the designated owner lose access to the conversations that were available to them in Protegrity Agent v1.0.

The conversation ownership strategy should be selected before the migration and documented as part of the upgrade plan. After the migration is complete, the ownership assignment cannot be changed through the Protegrity Agent user interface or API. Modifying conversation ownership requires direct updates to the underlying database.

6.2 - Preparing database credentials

The helm chart v2.0.0 requires a pre-existing database credentials Secret and no longer creates the Secret from Helm values during installation.

For upgrades from Helm chart v1.1.0, the Helm-managed database-secrets resource is retained and can continue to use its default name. Helm chart v1.0.0 does not retain this Secret.

The following procedure creates a new unmanaged Secret by copying the existing database credentials. The procedure is applicable to upgrades from either version. It copies the encoded Secret data without exposing the database password in command output.

kubectl -n pty-protegrity-agent get secret database-secrets -o json \
  | jq '{apiVersion: "v1", kind: "Secret", metadata: {name: "protegrity-agent-db-credentials", namespace: .metadata.namespace}, type: .type, data: {postgres_user: .data.postgres_user, postgres_password: .data.postgres_password}}' \
  | kubectl apply -f -

Add --set databaseService.credentials.existingSecretName=protegrity-agent-db-credentials flag to both Helm commands in while upgrading to prevent credential loss.

6.3 - Upgrading the Agent to v1.2.0

Before you begin

• Ensure that the PPC is upgraded to v1.2.0.

• Verify that the platform publishes the application-node machine type required by chart 2.0.0, using the following command:

  kubectl get configmap nfa-config -n default \
  -o jsonpath='{.data.CLOUD_VENDOR}{"\t"}{.data.ARCHITECTURE}{"\t"}{.data.USERPOOL_INSTANCE_TYPE}{"\n"}'
  

  Do not proceed with the upgrade if the machine type is empty. Using a PPC user credentials, update the PPC ConfigMap to specify a valid machine type. Alternatively, provide a machine type override by adding the following parameter to both Helm commands used during the upgrade:

  --set karpenterResources.machineType=<exact-type-or-SKU>
  

  Do not use --reuse-values or --reset-then-reuse-values when upgrading from Helm chart v1.x to v2.0.0:

• --reuse-values preserves the existing 1.x values and does not incorporate the new chart defaults, which can cause template rendering failures.

• --reset-then-reuse-values applies the new defaults but can silently discard customizations stored under configuration keys that were renamed between chart versions.

For reliable upgrade behavior, explicitly define all required overrides in the new values-2.0.yaml file and provide that file to the upgrade commands.

Upgrading Agent to v1.2.0

To upgrade the Agent to v1.2.0, perform the following steps:

1. Execute the upgrade process with migration enabled. Ensure this step is performed only once while migrating the helm chart from v1.x to v2.0.0. Run the following command:

   helm upgrade protegrity-agent \
    oci://<Container_Registry_Path>/protegrity-agent/helm/protegrity-agent \
    --namespace pty-protegrity-agent \
    --version 2.0.0 \
    -f values-2.0.yaml \
    --set databaseService.credentials.existingSecretName=protegrity-agent-db-credentials \
    --set migration.enabled=true \
    --set backup.enabled=true \
    --set migration.legacyConversationOwner=<username>
   

   where, values-2.0.yaml is the file used for configuring the values required for Agent v1.2.0.

   Note: If installing using the Protegrity Container Registry, then for <Container_Registry_Path>, use registry.protegrity.com:9443.

2. After the initial v1.x-to-v2.0.0 upgrade completes successfully, disable migration for all subsequent upgrades by running the following command:

   helm upgrade protegrity-agent \
    oci://<Container_Registry_Path>/protegrity-agent/helm/protegrity-agent \
    --namespace pty-protegrity-agent \
    --version 2.0.0 \
    -f values-2.0.yaml \
    --set databaseService.credentials.existingSecretName=protegrity-agent-db-credentials \
    --set migration.enabled=false
   

The Helm waits for both the pre-upgrade and post-upgrade hooks to complete before reporting the upgrade status.

A successful initial helm upgrade confirms that the database dump, restore, and schema migration jobs completed successfully. After the successful completion of these jobs, they are automatically removed by the chart.

If the upgrade fails, inspect the failed job that was retained by the chart. To review its logs and determine the cause of the failure, run the following command.

kubectl get jobs -n pty-protegrity-agent \
  -l app.kubernetes.io/component=pg-migration
kubectl logs -n pty-protegrity-agent job/<failed-job-name> --tail=100

6.4 - Decommissioning the connection to PIM

Protegrity Agent v1.2.0 does not connect to a live PIM tenant. Agent responses are generated exclusively from the bundled Traverse and Policy product documentation.

The Agent operates in a read-only mode and does not perform create, modify, or delete operations against any Protegrity product. As a result, workflows in Agent v1.0 that depended on the Agent executing PIM operations are not supported in Agent v1.2.0.

As part of the upgrade, remove any PIM-specific endpoint configurations, credentials, and network egress rules that were provisioned solely for the Agent v1.0 integration.

6.5 - Migrating users

Agent access definitions are reapplied during every helm upgrade through the ProductConfiguration custom resource.

User-to-role assignments stored in the PPC authentication layer are not migrated automatically. Before removing any legacy assignments, assign the replacement Agent roles to all existing user accounts and verify that each user can successfully sign in and access the Agent.

Remove the legacy role assignments only after validating that the new assignments function as expected for all users.

Note: To access the Agent panel, assign the agent-user role.

The agent-model-administrator role is introduced in Protegrity Agent v1.2.0 and has no equivalent in Agent v1.0. Assign this role explicitly to users who need permission to configure and manage models.

Protegrity Agent v1.2.0 does not require any workbench_* roles. Existing Workbench role assignments may be retained or removed based on the Policy Workbench responsibilities of the required user. It has no impact on Agent access or permissions.

Migrating users

To migrate users, perform the following steps:

1. Complete the helm chart v2.0.0 upgrade. This ensures that the new Agent role definitions exist.
   For more information about upgrading the helm chart to v2.0.0, refer to Upgrading the Agent to v1.2.0.

2. Verify that the replacement PPC roles are available with GET /pty/v1/auth/roles.
   To inspect role definitions, run the following command:

   curl -sk "https://$FQDN/pty/v1/auth/roles" \
    -H "Authorization: Bearer $TOKEN" | jq .
   

3. Add the required PPC assignment for the replacement role to every existing user account. Assign agent-model-administrator explicitly to the accounts that should manage models. Ensure that any Agent v1.0 roles are attached to it.

4. Verify that users assigned the agent-user role can use conversations but receive a 403 error when running /model-config.

5. Verify that users assigned the agent-model-administrator role can use /model-config but receive a 403 error when running /conversations.

6. Remove the old proagent_administrator and agent_admin assignments only after all affected accounts successfully verify these checks.

7. Run admin list users command and confirm that every migrated account has the expected replacement assignments and no obsolete assignments.

7 - Uninstalling the Agent

The following procedure removes Protegrity Agent 1.2.0 (Helm chart 2.0.0) from supported AWS and Azure PPC environments. If custom resource names were used during installation, substitute the default names in the commands accordingly.

Before beginning the uninstallation process, verify that the correct Kubernetes context is selected and back up any required data, credentials, or configuration information stored outside the Agent volumes. The uninstallation process may remove resources such as the backup Persistent Volume Claim (PVC) and the database Secret created through External Secrets.

To uninstall Agent v1.2.0, perform the following steps:

1. Remove the Agent product registration before proceeding with the uninstallation. Ensure that the platform controllers remain operational throughout the process to support the successful removal of Agent resources. Run the following command.

   kubectl delete productconfigurations.pty.com proagent \
   -n pty-protegrity-agent --ignore-not-found --wait=true --timeout=120s
   

2. To uninstall the Helm release and wait for the cleanup, run the following command.

   helm uninstall protegrity-agent -n pty-protegrity-agent --wait --timeout=10m
   

3. To verify the Agent node cleanup before reinstalling or deleting the namespace, run the following command:

   kubectl get nodepool protegrity-agent --ignore-not-found
   kubectl get nodeclaims,nodes -l karpenter.sh/nodepool=protegrity-agent
   

   Additionally, verify the node class for the required cloud.

   Cloud	Verification Command
   AWS	kubectl get ec2nodeclass protegrity-agent-nodeclass --ignore-not-found
   Azure	kubectl get aksnodeclass protegrity-agent-nodeclass --ignore-not-found

   No resources should be returned by the verification commands. If cleanup is still in progress, wait for the associated resources to be removed and repeat the verification steps.

   If Karpenter resources are disabled, node class verification can be skipped. Any node classes that are managed outside of the Agent deployment should remain in place and must not be removed.

4. Optionally, delete the Agent namespace to perform a complete removal of all Agent resources. Deleting the namespace removes any remaining Persistent Volume Claims (PVCs), Secrets, and other namespace-scoped resources.

   Note: Skip this step if these resources must be retained for a future reinstallation or recovery scenario.

   Run the following command:

   kubectl delete namespace pty-protegrity-agent --wait=true --timeout=10m
   

   Note: If a command fails or times out, stop and ask your PPC administrator to investigate. Do not automatically remove finalizers; they protect controller cleanup. Neither AWS nor Azure requires a finalizer patch for normal uninstall.