Protegrity Synthetic Data on

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

This section explains why organizations use Synthetic Data and how Protegrity Synthetic Data preserves statistical utility while reducing privacy risk.

Organizations need realistic datasets for model training, testing, and cross-team collaboration without exposing sensitive information. Traditional methods such as masking and redaction can reduce data utility for analytics and machine learning.

Protegrity Synthetic Data learns patterns and distributions from source data. It then generates new records that reflect these patterns without reproducing the original personal records.

Understanding the Architecture and Components

Mon, 01 Jan 0001 00:00:00 +0000

Protegrity Synthetic Data generates realistic, privacy-safe synthetic datasets using machine learning models. It learns patterns and distributions from real data, then produces new records with similar statistical properties.

Protegrity Synthetic Data uses Kubernetes for scalable Synthetic Data generation and supports deployment on AWS EKS.

Component Diagram

The following diagram shows the deployment architecture and communication between components.

graph TD
 User([User / Client Application]) -->|HTTPS :443| GW[PPC Gateway]
 User --> SDK[Synthetic Data Python SDK]
 SDK -->|HTTPS :443| GW

 GW -->|:8000 /pty/syntheticdata/v2| App[Synthetic Data
REST Server + ML Engine]

 App -->|:5432 jobstatedb + mlopsdb| DB[(PostgreSQL)]

 subgraph EKS [EKS Cluster · synthetic-data-ns]
 GW
 App
 DB
 end

 subgraph AWS
 S3[(S3 Bucket
Data Storage)]
 IAM[IAM Role
Pod Identity]
 end

 App -.->|assumes| IAM
 IAM -.->|grants access| S3
 App <-->|read / write| S3

Communication Ports

Port	Direction	Description
443	User and SDK → PPC Gateway	HTTPS entry point for user and SDK traffic
8000	Gateway → Synthetic Data REST Server	Synthetic Data REST API (`/pty/syntheticdata/v2`)
5432	Synthetic Data REST Server → PostgreSQL	Stores job state (`jobstatedb`) and MLOps model tracking (`mlopsdb`); internal only

Components

PPC Gateway: Exposes the external HTTPS endpoint and routes requests to the Synthetic Data REST API.

Prerequisites for Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Ensure the following prerequisites are met:

Tools

Install and configure the following tools on the jumpbox:

opentofu 1.10 or later. Refer to OpenTofu Installation.
helm 3.12+, kubectl 1.27+, and aws CLI v2 with access to the Protegrity Provisioned Cluster (PPC).

AWS Setup

Ensure that the following AWS requirements are met:

A Protegrity Provisioned Cluster (PPC) is available. For more information, refer to Protegrity Provisioned Cluster.
AWS CLI credentials are configured by using aws configure.

Server Installation

Mon, 01 Jan 0001 00:00:00 +0000

Note: This guide uses version 2.1.0 throughout. Replace 2.1.0 with the version you are installing, including in the Python SDK Installation section.

This section describes how to deploy Protegrity Synthetic Data on Amazon EKS as part of Protegrity AI Team Edition.
It uses OpenTofu to provision cloud infrastructure, such as S3, IAM, and Karpenter. It also generates the syntheticdata-values.yaml file that Helm uses to deploy Kubernetes workloads.

Deployment Steps

1. Provision Cloud Infrastructure with OpenTofu

The OpenTofu module creates the S3 bucket, IAM role, EKS Pod Identity association, and Karpenter NodePool. It also writes syntheticdata-values.yaml with cloud-specific Helm overrides.

Upgrading Protegrity Synthetic Data

Mon, 01 Jan 0001 00:00:00 +0000

This section describes how to upgrade Protegrity Synthetic Data to the latest version.

Note: If upgrading across major versions, review the release notes for any breaking changes before proceeding.

Upgrade Protegrity Synthetic Data by running helm upgrade with the new --version value.

Note: Passwords are preserved during upgrades. Omit the --set database.auth.* flags.

helm upgrade synthetic-data \
 oci://registry.protegrity.com/synthetic-data/helm/synthetic-data \
 --version <NEW_VERSION> \
 --namespace synthetic-data-ns \
 --values <VALUES_FILE>

After upgrading, verify that all pods are in the Running state:

User Creation in PPC

Mon, 01 Jan 0001 00:00:00 +0000

Warning: Use the -k flag only in development or trusted internal environments. Do not use it in production, where valid certificates must be configured.

Role Update and User Creation

After deployment, update the default syntheticdata_administrator role to include can_create_token permission. Then create a user with this role.

1. Update `syntheticdata_administrator` role permission

export GATEWAY_URL="https://$(kubectl get configmap/nfa-config -n default -o jsonpath='{.data.FQDN}')"

# 1. Obtain an Authentication Token
TOKEN=$(curl -sk -X POST "${GATEWAY_URL}/api/v1/auth/login/token" \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'loginname=admin&password=Admin123!' \
 -D - -o /dev/null | grep -i 'pty_access_jwt_token' | awk '{print $2}' | tr -d '\r\n')

curl -sk -X PUT \
 "${GATEWAY_URL}/pty/v1/auth/roles" \
 -H 'accept: application/json' \
 -H "Authorization: Bearer ${TOKEN}" \
 -H 'Content-Type: application/json' \
 -d '{
 "name": "syntheticdata_administrator",
 "description": "Administrator role",
 "permissions": [
 "can_create_token",
 "syntheticdata_operations_admin"
 ]
 }'

2. Create a user with the `syntheticdata_administrator` role attached

Use the following request payload when creating the user:

Uninstalling and Cleanup

Mon, 01 Jan 0001 00:00:00 +0000

To remove the Synthetic Data service and all associated Kubernetes and AWS resources:

1. Uninstall the Helm release

# Removes all chart resources. PVC data is RETAINED by default (retentionPolicy: whenDeleted=Retain).
helm uninstall synthetic-data -n synthetic-data-ns

# To also delete the database PVC:
kubectl delete pvc -n synthetic-data-ns -l app.kubernetes.io/name=synthetic-data

Optionally, delete the namespace after all resources are deleted:

kubectl delete namespace synthetic-data-ns

2. Destroy OpenTofu infrastructure

# Destroys Karpenter nodes, IAM role, Pod Identity association, and S3 bucket.
tofu destroy -var="cluster_name=<CLUSTER_NAME>"

Note: By default, tofu destroy prompts for confirmation before deleting resources. Add -auto-approve to skip the prompt.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Diagnostic Flowchart

Use the following flowchart to identify the cause of common issues.

flowchart TD
 Start[Problem?] --> ServerRunning{Server pods Running?}
 ServerRunning -->|No| PodIssue[Check pod logs<br/>kubectl logs -n synthetic-data-ns]
 ServerRunning -->|Yes| APIWorks{Does API respond?}
 APIWorks -->|No| NetworkIssue[Check Service and Gateway<br/>kubectl get svc -n synthetic-data-ns]
 APIWorks -->|Yes| ValidationFails{Request fails?}
 ValidationFails -->|Yes| ConfigIssue[Review request config<br/>Check model and data parameters]
 ValidationFails -->|No| OtherIssue[Check logs or open a support ticket]
 style Start fill:#e1f5ff

Common Issues

Pods not reach the `Running` state

kubectl describe pod -n synthetic-data-ns <POD_NAME>
kubectl logs -n synthetic-data-ns <POD_NAME>

Check that the Karpenter NodePool provisioned the required nodes. Ensure that OpenTofu created the S3 bucket and IAM role.

Protegrity Synthetic Data on

Introduction

Understanding the Architecture and Components

Component Diagram

Communication Ports

Components

Prerequisites for Deployment

Tools

AWS Setup

Server Installation

Deployment Steps

1. Provision Cloud Infrastructure with OpenTofu

Upgrading Protegrity Synthetic Data

User Creation in PPC

Role Update and User Creation

1. Update syntheticdata_administrator role permission

2. Create a user with the syntheticdata_administrator role attached

Uninstalling and Cleanup

1. Uninstall the Helm release

2. Destroy OpenTofu infrastructure

Troubleshooting

Diagnostic Flowchart

Common Issues

Pods not reach the Running state

1. Update `syntheticdata_administrator` role permission

2. Create a user with the `syntheticdata_administrator` role attached

Pods not reach the `Running` state