Upgrading the Agent to v1.2.0

• 1: Migrating conversation ownership
• 2: Preparing database credentials
• 3: Upgrading the Agent to v1.2.0
• 4: Decommissioning the connection to PIM
• 5: Migrating users

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.

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.

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

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.

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.