Installing Policy Workbench on PPC in Amazon Elastic Kubernetes Service (EKS)

Before installing Policy Workbench, ensure that the prerequisites are met. For more information about the prerequisites, refer to the section Prerequisites.

To install Policy Workbench, first provision the AWS resources using the policy-workbench OpenTofu module and then deploy the Policy Workbench using Helm. The policy-workbench OpenTofu module is published to the Protegrity Container Registry and must be consumed from a root module. A root module is the working directory for executing the OpenTofu commands.

For more information about OpenTofu modules and the root module, refer to the section Modules in the OpenTofu documentation.

The Policy Workbench is installed depending on one of the following scenarios:

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

Prerequisites

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.

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

For more information about installing PPC, refer to the section Installing PPC.

Required Tools

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

IAM Permissions

The following IAM permissions are automatically created by the OpenTofu script.

EKS Permissions

The following EKS permissions are automatically created by the OpenTofu script.

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'.

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

    {
        "auths": {
                "registry.protegrity.com:9443": {
                        "auth": "<base64 generated string from step-3>"
                }
        }
}

Installing Policy Workbench when root module is not available

Install the Policy Workbench using the following commands:

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     = ""
}

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_Hostname>"
  fips         = var.fips
  ami_id       = var.ami_id
}

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

In the main.tf file, specify the values of the following variables.

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 command to navigate to the deployment directory.

   cd policy-workbench
   

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

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

To use a non-FIPS AMI, run the following tofu apply command:

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

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

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

tofu apply -var="cluster_name=<your-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 FIPS-based AMI selection.

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.

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

6. 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 values of the following variables.

The OpenTofu module writes a policy-workbench-values.yaml file in your working directory with cloud-specific keystore settings. Pass it to Helm with the --values parameter.

Note: The tofu output -raw helm_install command prints a ready-to-run Helm command with the correct version and namespace values already filled in.

Important: You need to pass the <ami-id> in the command only if you are deploying the feature in regions other than us-east-1.

Option A (Recommended): Run the following AWS CLI command to retrieve the AMI ID dynamically.

aws ssm get-parameter \
  --name /aws/service/bottlerocket/aws-k8s-1.34/x86_64/latest/image_id \
  --region <region> \
  --query "Parameter.Value" \
  --output text

Alternatively, refer to these example AMI IDs.

Option B: The following table provides the list of AMI IDs.

7. 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
rpproxy-79fc498d8-s9k5p     1/1     Running   0          13m
rpproxy-79fc498d8-tbdtb     1/1     Running   0          13m
rps-8d79b7d98-svhdw         1/1     Running   0          13m

Installing Policy Workbench when root module is available

Install the Policy Workbench using the following commands:

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 = "<PPC-cluster-name>"
  oci_host     = "<Container_Registry_Hostname>"
  # 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.

2. 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 = "<PPC-cluster-name>"
}
data "aws_eks_cluster_auth" "this" {
  name = "<PPC-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 -var="cluster_name=<PPC-cluster-name>"
tofu apply -var="cluster_name=<PPC-cluster-name>"

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

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.

6. 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 values of the following variables.

The OpenTofu module writes a policy-workbench-values.yaml file in your working directory with cloud-specific keystore settings. Pass it to Helm with the --values parameter.

Note: The tofu output -raw helm_install command prints a ready-to-run Helm command with the correct version and namespace values already filled in.

Important: You need to pass the <ami-id> in the command only if you are deploying the feature in regions other than us-east-1.

Option A (Recommended): Run the following AWS CLI command to retrieve the AMI ID dynamically.

aws ssm get-parameter \
  --name /aws/service/bottlerocket/aws-k8s-1.34/x86_64/latest/image_id \
  --region <region> \
  --query "Parameter.Value" \
  --output text

Alternatively, refer to these example AMI IDs.

Option B: The following table provides the list of AMI IDs.

7. 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
rpproxy-79fc498d8-s9k5p     1/1     Running   0          13m
rpproxy-79fc498d8-tbdtb     1/1     Running   0          13m
rps-8d79b7d98-svhdw         1/1     Running   0          13m

Validating the deployment

Note: Before validating the deployment of the Policy Workbench, ensure that the kubectl context is set to the target PPC cluster. 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. The desired outcome of these steps is to get a [] response from the datastores API call using a dedicated workbench user.

1. Run the following command to retrieve the gateway host details.

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

2. Run the following command to generate the JWT token.

TOKEN=$(curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=admin" \
  -d "password=Protegrity123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:' \
  | sed 's/pty_access_jwt_token: //' \
  | tr -d '\r') && echo "${TOKEN:0:10}"

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

curl -sk -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"
    ]
  }'

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"}

Use the JWT token generated in step 2.

4. Ensure that the user with the workbench_administrator roles has the following permissions:

• workbench_management_policy_write
• workbench_deployment_immutablepackage_export
• workbench_deployment_certificate_export
• cli_access
• can_create_token

To ensure the required permissions, run the following command:

curl -sk -X PUT "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workbench_administrator",
    "permissions": [
      "workbench_management_policy_write",
      "workbench_deployment_immutablepackage_export",
      "workbench_deployment_certificate_export",
      "cli_access",
      "can_create_token"
    ]
  }'

The following output appears.

{"role_name":"workbench_administrator","status":"updated"}

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

For more information about the cli_access and can_create_token permissions, refer to the section Roles and Permissions.

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

export TOKEN=$(curl -k -s https://$GW_HOST/pty/v1/auth/login/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'loginname=workbench' \
  -d 'password=<Password>' \
-D - -o /dev/null 2>&1 | grep -i 'pty_access_jwt_token:' | sed 's/pty_access_jwt_token: //' | tr -d '\r')

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

curl -k -v 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.

Post-Installation steps

After installing PPW, rotate the certificates to ensure that the certificates on the PPW and PPC are sychronized.

Perform the following steps to rotate the certificates.

1. Run the following command to rotate all the certificates.

# Renew all certificates using eclipse-issuer
kubectl get certificates --all-namespaces -o json | \
jq -r '.items[] | select(.spec.issuerRef.name=="eclipse-issuer") | "\(.metadata.namespace) \(.metadata.name)"' | \
while read -r ns cert_name; do
  echo "Renewing certificate: $cert_name in namespace: $ns"
  cmctl renew "$cert_name" -n "$ns"
done

2. Run the following command to verify that the certificates have been rotated.

kubectl get certificates --all-namespaces

The following output appears.

NAMESPACE          NAME                           READY   SECRET                                AGE
api-gateway        ingress-certificate-secret     True    ingress-certificate-secret            5h46m
cert-manager       eclipse-ca                     True    eclipse-ca                            5h46m
policy-workbench   bootstrap-certificate          True    bootstrap-certificate-secret          17m
policy-workbench   cert-certificate               True    cert-certificate-secret               17m
policy-workbench   devops-certificate             True    devops-certificate-secret             17m
policy-workbench   hubcontroller-certificate      True    hubcontroller-certificate-secret      17m
policy-workbench   kmgw-certificate               True    kmgw-certificate-secret               17m
policy-workbench   mbs-certificate                True    mbs-certificate-secret                17m
policy-workbench   protector-certificate          True    protector-certificate-secret          17m
policy-workbench   pty-main-backend-client-cert   True    pty-main-backend-client-certificate   17m
policy-workbench   repository-certificate         True    repository-certificate-secret         17m
policy-workbench   rpproxy-certificate            True    rpproxy-certificate-secret            17m
policy-workbench   rps-certificate                True    rps-certificate-secret                17m
pty-insight        hubcontoller-client-secret     True    hubcontoller-client-secret            5h46m
pty-insight        tls-for-insight                True    tls-for-insight-key-pair              5h46m
pty-loginui        ingress-certificate-secret     True    ingress-certificate-secret            5h46m

The Ready column displays the value True for all the certificates indicating that they have been rotated.