Installation

• 1: Prerequisites
• 2: Installing Policy Workbench

1 - Prerequisites

The following prerequisites apply to both resource-management paths. Both paths require access to the OCI registry to install the Helm chart.

• Ensure that the target EKS cluster is accessible and has a supported PPC installation.

  For more information, refer to PPC installation.

• Ensure that the jumpbox can connect to the required registries. If not already authenticated, then log in to the required registry.

• For connecting and deploying from the Protegrity Container Registry (PCR), use the following command and the credentials obtained from the My.Protegrity portal during account creation:

helm registry login registry.protegrity.com:9443

• For connecting and deploying to the local registry, use your local credentials and local registry endpoint as required.

Required Tools

Ensure that the following tools are available on the jump box on which Policy Workbench is installed.

Permissions

This section lists the permissions that are required to install Policy Workbench.

IAM Permissions

The following IAM permissions are required to provision AWS resources for Policy Workbench. For module-managed Workbench resources, these permissions are required by the AWS identity used to run the OpenTofu module. For self-managed Workbench resources, they are required by the identity used to provision the resources through your infrastructure automation or CLI commands.

EKS Permissions

The following EKS permissions are required to install Policy Workbench. In the OpenTofu-based installation, these permissions are used automatically by the module. In the in-cluster installation, the platform team must have these permissions to provision the resources manually.

Other Permissions

Helm deployment: The installer needs OCI registry access and Kubernetes RBAC to install or upgrade the chart. Helm access does not grant AWS or keystore access.

KMGW runtime: The KMGW pod uses the workbench-kms service account with a pod identity association to access the configured keystore. Grant this service account only the keystore permissions required by the configured backend. These permissions are separate from those required by the OpenTofu or Helm operator.

2 - Installing Policy Workbench

Policy Workbench is installed on an existing, supported PPC installation running on AWS EKS. Prepare the AWS and Kubernetes resources needs using one of two methods:

• Module-managed Workbench resources: Use the provided policy-workbench OpenTofu module to prepare the resources on the existing cluster.The OpenTofu installation procedure depends on whether a root module is available.
  For more information about OpenTofu modules and the root module, refer to Modules in the OpenTofu documentation.
• Self-managed Workbench resources: Prepare and manage those resources through the existing infrastructure process.
  For more information on deploying PPC onto an existing AWS EKS cluster, refer to In-cluster deployment.

Both methods install Policy Workbench with Helm. The following sections describe the prerequisites and steps for each method.

Installing Policy Workbench

To install Policy Workbench, select an installation path:

• Module-managed Workbench resources
• Self-managed Workbench resources

Module-managed Workbench resources

Use this path when the policy-workbench OpenTofu module should prepare the AWS and Kubernetes resources required by Policy Workbench on the existing EKS/PPC cluster. After OpenTofu completes, install the Helm chart using the generated Helm values file, policy-workbench-values.yaml.

Module prerequisites

• Ensure that the PPC installed and accessible, before installing Policy Workbench on PPC.

For more information about deploying the PPC cluster, refer to Automated script-based installation or Manual component-based installation.

• Before installing Policy Workbench, verify that the PPC worker security group’s AWS Name tag is set to <cluster-name>_SG, where <cluster-name> is the exact EKS cluster name used during PPC installation and SG must be in uppercase.
  Policy Workbench’s Karpenter EC2NodeClass discovers the worker security group by matching the tag Name = <cluster-name>_SG. This match is case-sensitive. If the tag value does not match exactly, Karpenter-provisioned nodes launch without the PPC worker security group attached. Those nodes cannot reach CoreDNS on the PPC system nodes, and Policy Workbench pods, such as, hubcontroller, will fail with DNS timeouts and enter CrashLoopBackOff.
  
  • In the Automated script-based installation, the bootstrap.sh script sets this tag automatically using the cluster name provided.

Configuring Credentials for the Policy Workbench

Perform the following steps to configure the credentials to access the Policy Workbench from the OCI registry.

1. Run the following command to create the configuration directory.

   mkdir -p ~/.config/containers
   

2. Obtain the username and access token from the My.Protegrity portal. For more information about obtaining the credentials from the My.Protegrity portal, refer to the section Configuring Authentication for Protegrity AI Team Edition.

3. Generate base64 encoded string with padding for username:accesstoken obtained from the My.Protegrity portal.

   Ensure that you specify the username and access token within single quotes when generating the base64 encoded value. For example, 'username:accesstoken'.

   Note: For the Protegrity Container Registry, set <Container_Registry_Path> to registry.protegrity.com:9443. For a local registry, set it to the local registry endpoint.

4. Create a file named ~/.config/containers/auth.json with the following content.

   {
       "auths": {
           "<Container_Registry_Path>": {
               "auth": "<base64 generated string from step-3>"
           }
       }
   }
   

Follow the instructions for the scenario that matches whether a root module is available. Refer to the appropriate section using the following links:

• Root module is not available.
• Root module is available.

Installing Policy Workbench when root module is not available

Install the Policy Workbench using the following steps:

1. Run the following command to create the deployment directory:

# must install from an empty directory
mkdir policy-workbench && cd policy-workbench

2. Create a root module with a single main.tf file.

terraform {
  required_version = "~> 1.10"

  required_providers {
    aws = {
      source  = "registry.opentofu.org/hashicorp/aws"
      version = "~> 6.0"
    }
    kubernetes = {
      source  = "registry.opentofu.org/hashicorp/kubernetes"
      version = "~> 2.35"
    }
  }
}

variable "cluster_name" {
  type        = string
  description = "EKS cluster name."
  nullable    = false

  validation {
    condition     = length(trimspace(var.cluster_name)) > 0
    error_message = "cluster_name must be provided and cannot be empty."
  }
}

variable "fips" {
  type        = bool
  description = "Use FIPS Bottlerocket AMI for Karpenter nodes."
  default     = true
}

variable "ami_id" {
  type        = string
  description = "Explicit AMI ID for Karpenter nodes. When set, overrides ami_family/fips-based AMI selection."
  default     = ""
}

variable "arch" {
  type        = string
  description = "CPU architecture for Karpenter nodes. Use 'amd64' or 'arm64'."
  default     = null

  validation {
    condition     = var.arch == null || contains(["amd64", "arm64"], var.arch)
    error_message = "arch must be 'amd64' or 'arm64'."
  }
}

data "aws_eks_cluster" "this" {
  name = var.cluster_name
}

data "aws_eks_cluster_auth" "this" {
  name = var.cluster_name
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.this.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.this.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.this.token
}

module "policy_workbench" {
  source = "oci://<Container_Registry_Path>/policy-workbench/opentofu/modules/policy-workbench/aws?tag=<version>"

  cluster_name = var.cluster_name
  oci_host     = "<Container_Registry_Path>"
  fips         = var.fips
  ami_id       = var.ami_id
  arch         = var.arch
}

output "helm_install" {
  value = module.policy_workbench.helm_install
}

In the main.tf file, specify the value of the following variable.

Note: For the Protegrity Container Registry, set <Container_Registry_Path> to registry.protegrity.com:9443. For a local registry, set it to the local registry endpoint.

3. Ensure that the credentials to install the Policy Workbench from the Protegrity Container Registry have been configured.

   For more information about configuring the credentials, refer to the section Configuring Credentials for the Policy Workbench.

4. Run the following commands to plan and install the Policy Workbench OpenTofu module:

# init, plan, and install
tofu init
tofu plan -var="cluster_name=<cluster_name>"
tofu apply -var="cluster_name=<cluster_name>"

In the cluster_name field, specify the name of the PPC cluster that you have specified in step 1 while deploying the PPC.

For more information about deploying the PPC, refer to the section Deploying PPC.

By default, the Policy Workbench is deployed on arm64-based environments such as AWS Graviton.

To deploy the Policy Workbench on amd64-based environments such as standard Intel or AMD servers, run the following tofu apply command:

tofu apply -var="cluster_name=<ppc-cluster-name>" -var="arch=amd64"

In this command, specify the value of the arch variable as amd64 to deploy the Policy Workbench on amd64-based environments.

To use a standard AMI, run the following tofu apply command:

tofu apply -var="cluster_name=<ppc-cluster-name>" -var="fips=false"

In this command, specify the value of the fips variable as false to use a standard AMI for Karpenter nodes.

To use a specific AMI, run the following tofu apply command:

tofu apply -var="cluster_name=<ppc-cluster-name>" -var="ami_id=<your AMI id>"

In this command, specify the value of the ami_id variable as the specific ID of the AMI for Karpenter nodes. If you specify this value, then it overrides the default secure AMI selection.

OpenTofu prints the plan and prompts for confirmation. Enter yes to proceed. To skip the prompt, add the -auto-approve option to the commands.

After completing this procedure, refer to Deploy Policy Workbench with Helm to continue with the installation.

Installing Policy Workbench when root module is available

Install the Policy Workbench using the following steps:

1. Add the policy-workbench OpenTofu module by adding the following code block to an existing root module:

module "policy_workbench" {
  source = "oci://<Container_Registry_Path>/policy-workbench/opentofu/modules/policy-workbench/aws?tag=<version>"

  cluster_name = "<cluster_name>"
  oci_host     = "<Container_Registry_Path>"
  # fips       = true                # set to false for non-FIPS AMI
  # ami_id     = "<your AMI id>"     # explicit AMI override
}

For more information about adding a module to an existing root module, refer to the section Module Blocks in the OpenTofu documentation.

In the root module, specify the values of the following variables.

In the cluster_name field, specify the name of the PPC cluster that you have specified in step 1 while deploying the PPC.

For more information about deploying the PPC, refer to the section Deploying PPC.

1. If the root module does not include the hashicorp/aws provider version >= 6.0 and hashicorp/kubernetes provider version >= 2.35, then add the following code block to the terraform {} block. Else navigate to the next step:

required_providers {
  aws = {
    source  = "registry.opentofu.org/hashicorp/aws"
    version = "~> 6.0"
  }
  kubernetes = {
    source  = "registry.opentofu.org/hashicorp/kubernetes"
    version = "~> 2.35"
  }
}

The kubernetes provider must be configured to connect to the target EKS cluster:

data "aws_eks_cluster" "this" {
  name = "<cluster_name>"
}
data "aws_eks_cluster_auth" "this" {
  name = "<cluster_name>"
}
provider "kubernetes" {
host                   = data.aws_eks_cluster.this.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.this.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.this.token
}

For more information about including the hashicorp/aws provider in the root module, refer to the OpenTofu Registry documentation.

For more information about including the hashicorp/kubernetes provider in the root module, refer to the OpenTofu Registry documentation.

3. Ensure that the credentials to install the Policy Workbench from the Protegrity Container Registry have been configured.

   For more information about configuring the credentials, refer to the section Configuring Credentials for the Policy Workbench.

4. Navigate to the directory containing the root module.

5. Run the following commands to plan and install the Policy Workbench OpenTofu module:

# init, plan, and install
tofu init
tofu plan
tofu apply

OpenTofu prints the plan and prompts for confirmation. Enter yes to proceed. To skip the prompt, add the -auto-approve option to the commands.

After completing this procedure, refer to Deploy Policy Workbench with Helm to continue with the installation.

Self-managed Workbench resources

Use this path when the existing infrastructure process manages Workbench resources instead of the policy-workbench OpenTofu module. This path does not require OpenTofu commands. After completing the prerequisites and configuration below, install the Helm chart using the shared Helm procedure.

Self-managed prerequisites

Ensure that the PPC installed and accessible, before installing Policy Workbench on PPC.

For more information about deploying PPC on to an existing AWS EKS cluster, refer to the section In-cluster deployment.

Self-managed Node Resources and Scheduling

If nodes are provisioned manually instead of using the provided Karpenter modules, size them to cover the Policy Workbench footprint.

AWS KMS Backend Resources for KMGW

The following resources must be provisioned manually:

• IAM policy.
• IAM role.
• EKS Pod Identity association.

The following table lists the actions required for the IAM policy.

Application tags help KMGW find and identify keys. The tags do not control IAM authorization.

Configuring Persistent Storage

Policy Workbench uses the default StorageClass of the cluster unless pvc.storageClassName is set. Verify the StorageClasses available in the target EKS cluster before installation.

1. Run the following command to list the StorageClasses in the cluster:

   kubectl get storageclass
   

2. If the cluster has no default StorageClass, or the default is not suitable for Policy Workbench, set the StorageClass name in the Helm values file, policy-workbench-values.yaml:

   pvc:
     storageClassName: "<storage-class-name>"
   

   For example, PPC creates a StorageClass named pty-sc.

   Note: Without a suitable default StorageClass or this setting, the Policy Workbench PVCs remain unbound and the StatefulSet pods cannot be scheduled. Retain this setting in the policy-workbench-values.yaml file used for installation and future upgrades.

Configuring Node Selection for Policy Workbench Pods

By default, Kubernetes can schedule Policy Workbench pods on any available node. To pin Policy Workbench pods to specific nodes in your EKS cluster, perform the following steps:

1. Run the following command to apply the policy-workbench label to each node where Policy Workbench pods are scheduled:

   kubectl label node <node-name> nodepool.protegrity.com/name=policy-workbench
   

   Replace <node-name> with the name of the target node. Repeat the command for each node.

2. In the policy-workbench-values.yaml file, add a nodeSelector entry under scheduling that matches the label applied in step 1:

   scheduling:
     nodeSelector:
       nodepool.protegrity.com/name: policy-workbench
   

3. If the target nodes have taints applied, apply a PreferNoSchedule taint and a matching toleration.

   Important: Use PreferNoSchedule, not NoSchedule. Velero backup and restore pods do not inherit the tolerations set for Policy Workbench. A NoSchedule taint on the workbench nodes blocks Velero restores.

   a. Run the following command to apply the taint on each target node:

   kubectl taint node <node-name> workload=policy-workbench:PreferNoSchedule
   

   b. Add the matching toleration under scheduling.tolerations in the policy-workbench-values.yaml file. The key, value, and effect must match the taint applied to the node:

   scheduling:
     tolerations:
       - key: "workload"
         operator: "Equal"
         value: "policy-workbench"
         effect: "PreferNoSchedule"
   

Applying Scheduling to Individual Services

To apply a different scheduling policy to a specific service instead of all services, add a scheduling block under that service’s key.

For example:

rpproxy:
  replicas: 3
  scheduling:
    topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: kubernetes.io/hostname
        whenUnsatisfiable: ScheduleAnyway
        labelSelector:
          matchLabels:
            app: rpproxy

Here, the Resilient Package Proxy or rpproxy, which delivers packages to Protectors, is the only service whose replica count can be scaled. When scaling rpproxy, add a topologySpreadConstraint to spread its pods across nodes, so that a single node failure does not take down every replica. In this example, the rpproxy replica has been increased from the default 1 to 3. If you change the value to 3, the minimum Workbench requirements will change.

The whenUnsatisfiable field accepts one of the following values:

• ScheduleAnyway : Spreads pods on a best-effort basis without blocking scheduling if the constraint cannot be satisfied.
• DoNotSchedule : Leaves a pod in Pending state rather than placing it on a node that violates the spread constraint.

Configuring the AWS KMS Backend and Helm Values

Complete the following steps if you use AWS KMS as the KMGW backend and configure the policy-workbench-values.yaml file:

1. Set the environment variables used by the following commands:

   export CLUSTER_NAME="<cluster-name>"
   export AWS_REGION="us-east-1"
   export POLICY_NAME="eks-${CLUSTER_NAME}-policy-workbench-kms-policy"
   export ROLE_NAME="eks-${CLUSTER_NAME}-policy-workbench-kms-role"
   export NAMESPACE="policy-workbench"
   export SERVICE_ACCOUNT="workbench-kms"
   

These example values use the policy-workbench namespace and the workbench-kms ServiceAccount.

2. Run the following command to check whether the eks-pod-identity-agent add-on is installed and active:

   aws eks describe-addon \
     --cluster-name "$CLUSTER_NAME" \
     --addon-name eks-pod-identity-agent \
     --query 'addon.{status:status,version:addonVersion}' --output table
   

   If AWS reports that the add-on is missing, install it using the following command:

   aws eks create-addon \
     --cluster-name "$CLUSTER_NAME" \
     --addon-name eks-pod-identity-agent
   

3. Create a file named kms-access-policy.json with the following policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "DiscoverKmgwKeys",
         "Effect": "Allow",
         "Action": ["tag:GetResources"],
         "Resource": "*"
       },
       {
         "Sid": "GenerateRandom",
         "Effect": "Allow",
         "Action": ["kms:GenerateRandom"],
         "Resource": "*"
       },
       {
         "Sid": "CreateKmgwKeys",
         "Effect": "Allow",
         "Action": ["kms:CreateKey"],
         "Resource": "*"
       },
       {
         "Sid": "UseKmgwKeys",
         "Effect": "Allow",
         "Action": [
           "kms:Decrypt",
           "kms:Encrypt",
           "kms:DescribeKey",
           "kms:TagResource"
         ],
         "Resource": "*"
       }
     ]
   }
   

4. Run the following command to create the IAM policy:

   export POLICY_ARN=$(aws iam create-policy \
     --policy-name "$POLICY_NAME" \
     --policy-document file://kms-access-policy.json \
     --query Policy.Arn --output text)
   

   This example uses "Resource": "*" for all statements. KMS does not support resource-level scoping for kms:GenerateRandom or kms:CreateKey. The tag:GetResources action applies across the AWS account.

5. Create a file named pod-identity-trust.json with the following trust policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "Service": "pods.eks.amazonaws.com" },
         "Action": ["sts:AssumeRole", "sts:TagSession"]
       }
     ]
   }
   

6. Run the following command to create the IAM role and attach the policy:

   export ROLE_ARN=$(aws iam create-role \
     --role-name "$ROLE_NAME" \
     --assume-role-policy-document file://pod-identity-trust.json \
     --query Role.Arn --output text)
   
   aws iam attach-role-policy \
     --role-name "$ROLE_NAME" \
     --policy-arn "$POLICY_ARN"
   

7. Run the following command to associate the role with the KMGW ServiceAccount:

   aws eks create-pod-identity-association \
     --cluster-name "$CLUSTER_NAME" \
     --namespace "$NAMESPACE" \
     --service-account "$SERVICE_ACCOUNT" \
     --role-arn "$ROLE_ARN"
   

8. Run the following command to verify that the association between the IAM role and KMGW ServiceAccount exists:

   aws eks list-pod-identity-associations \
     --cluster-name "$CLUSTER_NAME" \
     --namespace "$NAMESPACE" --output table
   

9. Set the following AWS backend values in the policy-workbench-values.yaml file:

   keystore:
     backend: aws
     serviceAccount:
       name: workbench-kms
     aws:
       region: <aws-region>
   

   Set <aws-region> to the AWS region used for AWS_REGION.

After completing this procedure, refer to Deploy Policy Workbench with Helm to continue with the installation.

Deploy Policy Workbench with Helm

Note: For the Protegrity Container Registry, set <Container_Registry_Path> to registry.protegrity.com:9443. For a local registry, set it to the local registry endpoint.

After completing either resource-preparation path, install Policy Workbench with Helm.

• Self-managed resources: Configure the policy-workbench-values.yaml file with the storage, scheduling, and keystore settings described in Self-managed workbench resources.
• Module-managed resources: The OpenTofu module generates the policy-workbench-values.yaml file with the required resource settings. The tofu output -raw helm_install command prints a ready-to-run Helm command with the version and namespace values filled in.

Set <version> to the Policy Workbench version being installed. If the namespace was overridden in the OpenTofu module, use the same namespace in the Helm command. Retain the values file for future upgrades.

1. Run the following command to complete the installation of the Policy Workbench using Helm:

helm upgrade --install policy-workbench \
  oci://<Container_Registry_Path>/policy-workbench/helm/policy-workbench \
  --version <version> \
  --namespace policy-workbench \
  --create-namespace \
  --values policy-workbench-values.yaml

In the command, specify the value of the following variable.

2. Run the following command to view the pods created in the policy-workbench namespace:

kubectl get pods -n policy-workbench

The following output appears:

NAME                        READY   STATUS    RESTARTS   AGE
bootstrap-bffb4b5d9-v6ww4   1/1     Running   0          13m
cert-7b88dcd84-zx7cv        1/1     Running   0          13m
devops-75755d87d4-qw9n6     1/1     Running   0          13m
hubcontroller-0             1/1     Running   0          13m
kmgw-0                      1/1     Running   0          13m
mbs-6b7dc765dd-brrfk        1/1     Running   0          13m
repository-0                1/1     Running   0          13m
rpproxy-79fc498d8-qp4fz     1/1     Running   0          13m
rps-8d79b7d98-svhdw         1/1     Running   0          13m

The number of rpproxy pods matches rpproxy.replicas if that value is overridden. Immediately after installation, the short-lived hubcontroller-init-* init job and kmgw-create-keystore-* pod may also appear.

Validating the deployment

Before validating the deployment of the Policy Workbench, ensure that the kubectl context is set to the target PPC cluster.

Note: The curl examples below assume that the server’s TLS certificate can be successfully verified. Do not use -k or --insecure in production, as these options disable certificate verification. For services using a private or self-signed CA, distribute the CA certificate to the client through a separate trusted channel and either install it in the client’s trusted certificate store or specify the CA certificate directly using curl --cacert.

Run kubectl config current-context to verify the current context. Run kubectl config use-context <context-name> to switch the context.

After installation, validate the Policy Workbench deployment using the following steps.

1. Run the following commands to retrieve the gateway host details and generate an admin JWT token:

Note: The admin user must change the default password on first login. Replace <password> with the new admin password.

export GW_HOST="$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')"

TOKEN=$(curl --silent --show-error --dump-header - --output /dev/null "https://$GW_HOST/pty/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'loginname=admin' \
  -d 'password=<password>' | grep -i 'pty_access_jwt_token:' | sed 's/pty_access_jwt_token: //' | tr -d '\r')

2. Create a workbench user using the following command: Due to separation of duties, the datastores API requires a user with workbench roles:

curl --silent --show-error -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "workbench",
    "password": "<password>",
    "roles": [
      "workbench_administrator",
      "security_administrator"
    ]
  }'

Note: The password policy requires a minimum of 14 characters, including at least one digit, one uppercase letter, one lowercase letter, and one special character.

The following output appears:

{"user_id":"397beecc-87bb-404e-85bb-f8a6d83984d6","username":"workbench"}

3. Run the following command to get a token for the workbench user:

TOKEN=$(curl --silent --show-error --dump-header - --output /dev/null "https://$GW_HOST/pty/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'loginname=workbench' \
  -d 'password=<password>' | grep -i 'pty_access_jwt_token:' | sed 's/pty_access_jwt_token: //' | tr -d '\r')

4. Run the Policy Management REST API to get datastores. Use the JWT token generated in step 4.

curl --silent --show-error "https://$GW_HOST/pty/v2/pim/datastores" \
  -H "Authorization: Bearer $TOKEN"

The expected output is []. This indicates that the Policy Workbench is initialized but the datastore is not yet created.

For more information about the workbench_administrator permissions, refer to Workbench Roles and Permissions.