This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Protegrity Provisioned Cluster

Tech Preview: AI Team Edition for Microsoft Azure

1 - Prerequisites

Ensure that the following prerequisites are met before deploying the Protegrity Provisioned Cluster (PPC).

Microsoft Azure Resource Providers: The following Microsoft Azure resource providers are registered.

  • Microsoft.ContainerService
  • Microsoft.Network
  • Microsoft.Compute
  • Microsoft.Storage
  • Microsoft.KeyVault
  • Microsoft.ManagedIdentity
  • Microsoft.OperationsManagement
  • Microsoft.OperationalInsights

AKS Permissions: Contact the Infrastructure Team to get the necessary permissions to create an AKS cluster, typically Contributor and User Access Administrator roles on the target subscription or resource group.

Jump Box or Local Machine: Use a dedicated Debian jump box created in Microsoft Azure. Do not use a jump box hosted on any other cloud.

Microsoft Azure Resource IDs from Infrastructure Team: Obtain the following resource IDs from the Infrastructure Team. These resource IDs are prompted during installation.

  • UAMI Resource ID: User-assigned managed identity for the AKS cluster.

    For example:

    /subscriptions/<subscription-id>/resourceGroups/<it-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-aks-applianceframework

  • AKS Subnet Resource ID: Required subnet for deploying the AKS nodes.

    For example:

    /subscriptions/<subscription-id>/resourceGroups/<it-resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/snet-aks-applianceframework

  • Private DNS Zone Resource ID: Private DNS zone used by the AKS private cluster, must match the cluster region, for example, privatelink.<region>.azmk8s.io.

    For example:

    /subscriptions/<subscription-id>/resourceGroups/<dns-resource-group>/providers/Microsoft.Network/privateDnsZones/privatelink.eastus.azmk8s.io

  • Velero UAMI Resource ID: User-assigned managed identity used by Velero for backups to the storage account.

    For example:

    /subscriptions/<subscription-id>/resourceGroups/<velero-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/id-aks-velero

2 - Preparing for PPC deployment

Downloading and extracting the recipe for deploying Protegrity Cluster Template (PCT)

This section describes the steps to download and extract the recipe for deploying the PPC.

Note: If there is an existing cluster from a previous install, clean up your local repository on the jump box and any existing clusters by running tofu destroy -var-file=terraform.tfvars from scripts/iac/ before proceeding.

During installation, the system may prompt for the system password and require sign-in to Microsoft Azure. If the Azure CLI is not already logged in, the bootstrap script automatically runs az login. A device-code prompt similar to the following displays.

[YYYY-MM-DD HH:MM:SS] Azure CLI not logged in. Triggering az login...
To sign in, use a web browser to open the page https://login.microsoft.com/device and enter the code XXXXXXXX to authenticate.

To sign-in to Microsoft Azure, perform the following steps:

  1. Open the displayed URL in a browser, and enter the code shown in the terminal.
  2. Complete the SSO sign-in and follow the on-screen instructions.
  3. After successful authentication, the script continues automatically.

Download the release archive from the AWS S3 bucket and extract it on the jump box using the following commands:

# Install AWSCLI, Login using AWS credentials and Download the archive

aws configure set aws_access_key_id `YOUR_ACCESS_KEY_ID`

aws configure set aws_secret_access_key `YOUR_SECRET_ACCESS_KEY`

aws s3 cp s3://ai-team-edition-1.0-redwood-312310269473-us-west-1-an/PPC-K8S-64_x86-64_AZURE-AKS_1.1.0.4.tar .

# Extract the archive
tar -xvf PPC-K8S-64_x86-64_AZURE-AKS_1.1.0.4.tar

3 - Deploying PPC

Complete the steps provided in this section to deploy PPC in Azure.

Before you begin

The repository provides a bootstrap script that automatically installs or updates the following tools on the jump box:

  • Azure CLI - Required to communicate with your Microsoft Azure account.
  • OpenTofu - Required to manage infrastructure as code.
  • kubectl - Required to communicate with the Kubernetes cluster.
  • Helm - Required to manage Kubernetes packages.
  • Make - Required to run the OpenTofu automation scripts.
  • jq - Required to parse JSON.
  • oras: Required to pull non‑container, generic OCI artifacts from the registry that are not handled by standard container tooling.

The bootstrap script asks for variables to be set to complete the deployment. Follow the instructions on the screen:

./bootstrap-azure.sh

The script prompts for the following variables.

  1. Enter AKS Cluster Name

    The following characters are allowed:

    • Lowercase letters: a-z
    • Numbers: 0-9
    • Hyphens: -

    The following characters are not allowed:

    • Uppercase letters: A-Z
    • Underscores: _
    • Spaces
    • Any special characters such as: / ? * + % ! @ # $ ^ & ( ) = [ ] { } : ; , .
    • Leading or trailing hyphens
    • More than 31 characters

    Note: Ensure that the cluster name does not exceed 31 characters. Cluster names longer than this limit can cause the bootstrap script to fail in subsequent installation steps.
    If the installation fails because the cluster name exceeds the 31-character limit, correct the name and re-run the script.

    • Correction: Choose a cluster name with 31 characters or fewer.
    • Retry: Execute the installation command again with the updated name. The script will automatically handle the update and proceed with the bootstrap process.

  2. Querying for available Resource Groups

    The script queries for the available Resource Groups. Enter a Resource Group name from the table. The script then automatically detects the location and subscription ID of the resource group.

  3. Enter UAMI Resource ID

    Provide the complete Azure resource ID for the UAMI used by AKS in the following format:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>

    The UAMI client ID is detected automatically.

  4. Enter AKS Subnet Resource ID

    Provide the complete resource ID of the pre-existing subnet used for AKS nodes in the forllowing format:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>

  5. Enter Private DNS Zone Resource ID

    Provide the Private DNS zone ID used by the AKS private cluster in the following format:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/privateDnsZones/privatelink.<region>.azmk8s.io

    The script attempts to automatically detect network settings:

    • Virtual network address space
    • Service CIDR
    • DNS service IP

    If the detection fails, then default values configured in the variables.tf file are used.

  1. Enter FQDN

    This is the Fully Qualified Domain Name for the ingress.

    Warning: Ensure that the FQDN does not exceed 50 characters and only the following characters are used:

    • Lowercase letters: a-z
    • Numbers: 0-9
    • Special characters: - .

  2. Storage Account and Key Vault provisioning

    Choose whether to use existing resources or create new resources:

    1) Use existing
2) Provision new via Tofu

    Enter 1 if an encrypted Storage Account and Key Vault are already provisioned for this cluster. The installer prompts for the Storage Account name, Key Vault name, backup container, Key Vault key name, and the Velero UAMI Resource ID.

    Enter 2 to allow the installer to create a new Storage Account and Key Vault with the velero container, the pty-backup-key encryption key, and a Velero UAMI automatically. Only the new resource names are required.

  1. Enter Image Registry Endpoint

    The image repository from where the container images are retrieved. Use registry.protegrity.com:9443/azure-tech-preview for using the Protegrity Container Registry (PCR), else use the local repository endpoint for the local repository.

    Expected format: [:port].

    Do not include ‘https://’

  1. Enter Registry Username

    Enter the username for the registry mentioned in the previous step. Leave this entry blank if the registry does not require authentication.

  2. Enter Registry Password or Access Token

    Enter Password or Access Token for the registry.

    Input is masked with * characters. Press Enter to keep the current value.

    Leave this entry blank if the registry does not require authentication.

After the bootstrap script is completed, verify the cluster and workloads using the following commands:

# Confirm nodes are Ready
kubectl get nodes

# Confirm NFA workloads are Running
kubectl get pods -A

4 - Login to PPC

Steps to access the PPC UI

To access the Web UI, map the gateway hostname to the Microsoft Azure Load Balancer IP address in the local hosts file.

  1. Get gateway details: Find the hostname and the Microsoft Azure Load Balancer address.

    kubectl get gateway -A

    The output will look similar to:

    NAMESPACE     NAME       CLASS   ADDRESS       PROGRAMMED   AGE
api-gateway   pty-main   envoy   10.221.8.33   True         5h7m

  2. Update the hosts file: Sdd an entry mapping the ingress FQDN to the IP.

    • Linux: /etc/hosts
    • Windows: C:\Windows\System32\drivers\etc\hosts

    Example entry:

    10.221.8.33    <FQDN given during cluster installation>

    Use the same FQDN provided during bootstrap-azure.sh.

  3. Access the UI in the browser.

    • URL: https://<user-provided-fqdn>
    • Default credentials: user admin, password Admin123!

5 - Accessing the PPC CLI

Steps to access the PPC CLI

The deployment includes a CLI container that provides command-line access to the Protegrity Management CLI via SSH, on both Linux and Windows.

Prerequisites

  1. SSH key: The private key generated during bootstrap at ~/.ssh/<cluster_name>_user_svc, matches the public key configured in the pty-cli pod.
  2. Network access: Ensure you have connectivity to the AKS cluster’s ingress Load Balancer.
  3. Hosts file: Same as Web UI access. Map the ingress FQDN to the Load Balancer IP.

The private key is placed under ~/.ssh/<cluster_name>_user_svc after bootstrap completes, where <cluster_name> is the AKS cluster name provided during installation.

Linux

From the project root directory, run the following command:

ssh -i ~/.ssh/<cluster_name>_user_svc -p 22 ptyitusr@<your-fqdn>

To skip host-key checking on first connect, run the following command:

ssh -i ~/.ssh/<cluster_name>_user_svc \
    -o StrictHostKeyChecking=no \
    -o UserKnownHostsFile=/dev/null \
    -p 22 ptyitusr@<your-fqdn>

Windows

  1. OpenSSH (Windows 10/11): Copy the private key from the jump box (~/.ssh/<cluster_name>_user_svc) to Windows machine, then run the following command:

    ssh -i C:\path\to\<cluster_name>_user_svc -p 22 ptyitusr@<your-fqdn>

  2. PuTTY:

    • Host Name: <user-provided-fqdn>
    • Port: 22
    • Connection Type: SSH
    • Connection > SSH > Auth: Browse to your private key (.ppk format)
    • Username: ptyitusr

CLI usage

Once connected, the Protegrity CLI welcome banner is displayed, and a prompt appears for the password (default: Admin123!).

The CLI supports three command categories:

  • pim: Policy Information Management commands for data protection policies.
  • admin: User, role, permission, group, and email management commands.
  • insight: Log forwarding to external SIEM and syslog servers.

6 - Deleting PPC

Steps to delete the cluster

Cleaning up the AKS Resources

To destroy all created resources, including the AKS cluster and related components, run the following command:


# Navigate setup directory
cd iac_setup_azure/scripts/iac

# Clean up all resources
tofu destroy -auto-approve

Executing this command destroys the PPC and all related components.

7 - Installing Features

Installing the features

After the PPC deployment is complete, optional components can be installed to extend the functionality.

Note: Feature installation is decoupled from PPC and must be performed separately. For detailed installation instructions, refer to the documentation provided by the respective feature teams.

Policy Workbench

This section describes how to install, verify, and uninstall Policy Workbench on a Kubernetes cluster without deploying Karpenter resources.

Prerequisites

Before running the Helm command, ensure the following prerequisites are in place:

  • Helm 3.x installed and configured on your workstation.
  • kubectl installed and connected to the target Kubernetes cluster.
  • Access to the Protegrity OCI registry registry.protegrity.com:9443 with valid credentials.
  • Network connectivity to pull images from the registry.
  • Cluster has sufficient resources like CPU, memory, and storage to run Policy Workbench.

Authentication to Registry

Log in to the OCI registry to allow Helm to pull the chart and images:

helm registry login registry.protegrity.com:9443 \
    --username '<your-username>' \
    --password '<your-password>'

Installing Policy Workbench without Karpenter

Policy Workbench is installed from the Protegrity OCI Helm registry. On the jump box run the following command:

helm upgrade --install policy-workbench \
    oci://registry.protegrity.com:9443/azure-tech-preview/policy-workbench/1.11/helm/policy-workbench \
    --version 1.11.0 \
    --namespace policy-workbench \
    --create-namespace \
    --set keystore.backend=hsm \
    --set keystore.hsm.imageRef=registry.protegrity.com:9443/azure-tech-preview/protegrity-provisioned-cluster/third-party/softhsm:2.6.1-openssl-3.3.2 \
    --set karpenterResources.enabled=false

Here,

  • keystore.backend=hsm together with keystore.hsm.imageRef=…softhsm:2.6.1-openssl-3.3.2 configures Policy Workbench to use a SoftHSM keystore.

  • karpenterResources.enabled=false disables Karpenter-specific resource hints; AKS uses the Cluster Autoscaler, so Karpenter is not present.

  • If the OCI registry requires authentication, run helm registry login registry.protegrity.com:9443 first using the same credentials you supplied during bootstrap.

Verifying Installation

To check if the pods are running in the policy-workbench namespace, run the following command:

    kubectl get pods -n policy-workbench
    helm status policy-workbench -n policy-workbench

Post-Installation

After successful installation,

  • The Keystore Backend is configured to use HSM with SoftHSM image 2.6.1-openssl-3.3.2.

  • karpenterResources.enabled=false ensures no Karpenter resources are deployed.

Uninstalling Policy Workbench

To uninstall the Policy Workbench, run the following command:

    helm uninstall policy-workbench -n policy-workbench
    kubectl delete namespace policy-workbench

Protegrity Agent

This section describes how to install the Protegrity Agent using Helm, along with the required prerequisites and steps to verify a successful installation.

Prerequisites

Before installing the Protegrity Agent, ensure the following requirements are met:

  • A running Kubernetes cluster with access to create namespaces and deploy workloads.
  • kubectl installed and configured to connect to the target cluster.
  • Helm v3 installed on the jump box or workstation used for installation.
  • Access to the Protegrity OCI Helm registry registry.protegrity.com:9443.
  • A values file, for example, custom-values.yaml, containing the Protegrity Agent configuration.
  • The custom-values.yaml file should include:
karpenterResources:
  enabled: false

proagentService:
  secrets:
   # Main Endpoint
   OPENAI_API_ENDPOINT: ""
   OPENAI_API_KEY: ""
   OPENAI_API_VERSION: ""
   OPENAI_LLM_MODEL: ""

   # Embeddings
   OPENAI_EMBEDDINGS_API_ENDPOINT: ""
   OPENAI_EMBEDDINGS_API_KEY: ""
   OPENAI_EMBEDDINGS_API_VERSION: ""
   OPENAI_EMBEDDING_MODEL: ""

Note: Store sensitive data such as API keys securely and ensure the values file is protected according to the organization’s security guidelines.

Authentication to Registry

To log in to the OCI registry to allow Helm to pull the chart and images, run the following command:

helm registry login registry.protegrity.com:9443 \
    --username '<your-username>' \
    --password '<your-password>'

Installing Protegrity Agent without Karpenter

  1. Ensure the custom-values.yaml file is available in the working directory. The following entry must be present.

    karpenterResources:
  enabled: false

  2. To install or upgrade the Protegrity Agent, run the following Helm command:

    helm upgrade --install protegrity-agent   oci://registry.protegrity.com:9443/azure-tech-preview/protegrity-agent/1.0/helm/protegrity-agent   --version 1.0.0   --namespace pty-protegrity-agent   --create-namespace --set databaseService.nodepoolName=""  -f custom-values.yaml

  3. To label all nodes in the node pool, run the following command:

    kubectl get nodes -o name | xargs -I{} kubectl label {} karpenter.sh/nodepool=protegrity-agent --overwrite

Verifying Installation

After the Helm command completes, verify that all Protegrity Agent components are running:

  1. To list the pods in the Protegrity Agent namespace, run the following command:
    kubectl get pods -n pty-protegrity-agent
  1. Confirm that all pods are in the Running state and show READY as 1/1. A successful installation should display pods similar to the following:
NAME                                              READY   STATUS    RESTARTS   AGE
database-statefulset-0                            1/1     Running   0          2m4s
protegrity-agent-db-backup-init-r1-7m9n4          1/1     Running   0          2m4s
protegrity-agent-deployment-847c869c47-65sgz      1/1     Running   0          2m4s
protegrity-agent-ui-deployment-569c68c88f-4474n   1/1     Running   0          2m4s

If all pods are running and ready, the Protegrity Agent installation is complete and ready for use.

Uninstalling Protegrity Agent

To uninstall Protegrity Agent, run the following command:

helm uninstall protegrity-agent -n pty-protegrity-agent

8 - Troubleshooting

Accessing the PPC CLI

  • Permission denied (publickey): Ensure the correct private key (~/.ssh/<cluster_name>_user_svc) is used and matches the authorized_keys in the pod.
  • Connection refused: Verify the load balancer IP and hosts file configuration.
  • Key format issues: Ensure the private key is in the correct format (OpenSSH format for Linux/macOS, .ppk for PuTTY)

Component installation issues

  • Helm chart not found: Run helm repo update to refresh the repository cache.
  • Namespace already exists: Drop the --create-namespace flag if the namespace is already created.
  • CRD conflicts: If cert-manager CRDs already exist, skip the CRD installation step.
  • Pod not starting: Inspect logs with kubectl logs <pod> -n <namespace> and kubectl describe pod <pod> -n <namespace>.