Installing PPC on Amazon Web Services (AWS)

• 1: Prerequisites
• 2: Preparing for PPC deployment
• 3: Deploying PPC
• 3.1: Configuring PPC for Non-FIPS Deployment on AWS
• 3.2: Automated script-based installation
• 3.3: Manual component-based installation
• 4: Installing Features and Protectors
• 5: Accessing the PPC CLI
• 5.1: Prerequisites
• 5.2: Accessing the PPC CLI
• 6: Login to PPC
• 6.1: Prerequisites
• 6.2: Log in to PPC
• 7: Upgrading the PPC
• 8: Backing up the PPC
• 9: Restoring the PPC
• 10: Deleting PPC
• 11: Accessing PPC using a Linux machine
• 12: Restoring the SSH keys and PCT from backed up Terraform state file

1 - Prerequisites

Updating the Roles and Permissions using JSON

The roles and permissions are updated using the JSONs.

From the AWS Console, navigate to IAM > Policies > Create policy > JSON, and create the following JSONs.

Note: Before using the provided JSON, replace the AWS_ACCOUNT_ID and REGION values with those of the account and region where the resources are being deployed.

1. Creating KMS key and S3 bucket.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "ReadOnlyAccess",
			"Effect": "Allow",
			"Action": [
				"eks:DescribeClusterVersions",
				"ec2:DescribeInstances",
				"ec2:DescribeVolumes",
				"s3:ListAllMyBuckets",
				"iam:ListUsers",
				"ec2:RunInstances",
				"ec2:DescribeInstances",
				"ec2:DescribeVolumes",
				"ec2:CreateKeyPair",
				"ec2:DescribeImages"
			],
			"Resource": "*"
		},
		{
			"Sid": "ScopedS3AndKMS",
			"Effect": "Allow",
			"Action": [
				"s3:ListBucket",
				"s3:PutEncryptionConfiguration",
				"s3:GetEncryptionConfiguration",
				"kms:CreateKey",
				"kms:PutKeyPolicy",
				"kms:GetKeyPolicy"
			],
			"Resource": [
				"arn:aws:s3:::*",
				"arn:aws:kms:*:<AWS_ACCOUNT_ID>:key/*"
			]
		},
		{
			"Sid": "SelfServiceIAM",
			"Effect": "Allow",
			"Action": [
				"iam:ListSSHPublicKeys",
				"iam:ListServiceSpecificCredentials",
				"iam:GetLoginProfile",
				"iam:ListAccessKeys",
				"iam:CreateAccessKey"
			],
			"Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:user/${aws:username}"
		},
        {
			"Sid": "EC2KeyPairPermission",
			"Effect": "Allow",
			"Action": [
				"ec2:CreateKeyPair",
				"ec2:DescribeKeyPairs"
			],
			"Resource": [
				"*"
			]
		}
	]
}

2. Creating EC2 Service Policy.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "DenyEC2Instances",
			"Effect": "Deny",
			"Action": "ec2:RunInstances",
			"Resource": "arn:aws:ec2:*:*:instance/*",
			"Condition": {
				"StringLike": {
					"ec2:InstanceType": [
						"p*",
						"g*",
						"inf*",
						"trn*",
						"x*",
						"u-*",
						"z*",
						"mac*"
					]
				}
			}
		},
		{
			"Sid": "ReadOnlyDescribeListEC2RegionRestricted",
			"Effect": "Allow",
			"Action": [
				"ec2:DescribeVpcs",
				"ec2:DescribeSubnets",
				"ec2:DescribeVpcAttribute",
				"ec2:DescribeTags",
				"ec2:DescribeSecurityGroups",
				"ec2:DescribeSecurityGroupRules",
				"ec2:DescribeLaunchTemplates",
				"ec2:DescribeLaunchTemplateVersions",
				"ec2:DescribeNetworkInterfaces",
				"ec2:DescribeAccountAttributes"
			],
			"Resource": "*",
			"Condition": {
				"StringEquals": {
					"aws:RequestedRegion": [
						"<REGION>"
					]
				}
			}
		},
		{
			"Sid": "EC2LifecycleAndSecurity",
			"Effect": "Allow",
			"Action": [
				"ec2:CreateSecurityGroup",
				"ec2:DeleteSecurityGroup",
				"ec2:AuthorizeSecurityGroupIngress",
				"ec2:AuthorizeSecurityGroupEgress",
				"ec2:RevokeSecurityGroupIngress",
				"ec2:RevokeSecurityGroupEgress",
				"ec2:CreateLaunchTemplate",
				"ec2:DeleteLaunchTemplate",
				"ec2:CreateTags",
				"ec2:DeleteTags"
			],
			"Resource": [
				"arn:aws:ec2:*:*:security-group/*",
				"arn:aws:ec2:*:*:launch-template/*",
				"arn:aws:ec2:*:*:instance/*",
				"arn:aws:ec2:*:*:network-interface/*",
				"arn:aws:ec2:*:*:subnet/*",
				"arn:aws:ec2:*:*:vpc/*",
				"arn:aws:ec2:*:*:image/*",
				"arn:aws:ec2:*:*:volume/*",
				"arn:aws:ec2:*:*:snapshot/*"
			]
		}
	]
}

3. Creating EKS Service Policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ReadOnlyDescribeListEKSVersionsRegionRestricted",
            "Effect": "Allow",
            "Action": [
                "eks:DescribeAddonVersions"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:RequestedRegion": [
                        "<REGION>"
                    ]
                }
            }
        },
        {
            "Sid": "ReadOnlyDescribeListEKS",
            "Effect": "Allow",
            "Action": [
                "eks:DescribeCluster",
                "eks:DescribeAddon",
                "eks:DescribePodIdentityAssociation",
                "eks:DescribeNodegroup",
                "eks:ListAddons",
                "eks:ListPodIdentityAssociations"
            ],
            "Resource": [
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:cluster/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:nodegroup/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:addon/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:podidentityassociation/*"
            ]
        },
        {
            "Sid": "EKSLifecycleAndTag",
            "Effect": "Allow",
            "Action": [
                "eks:CreateCluster",
                "eks:UpdateClusterVersion",
                "eks:UpdateClusterConfig",
                "eks:CreateNodegroup",
                "eks:UpdateNodegroupConfig",
                "eks:UpdateNodegroupVersion",
                "eks:DeleteNodegroup",
                "eks:CreateAddon",
                "eks:UpdateAddon",
                "eks:DeleteAddon",
                "eks:CreatePodIdentityAssociation",
                "eks:DeletePodIdentityAssociation",
                "eks:TagResource",
                "eks:ListClusters"
            ],
            "Resource": [
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:cluster/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:nodegroup/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:addon/*",
                "arn:aws:eks:*:<AWS_ACCOUNT_ID>:podidentityassociation/*"
            ]
        },
        {
            "Sid": "AllowEKSNodegroupSLR",
            "Effect": "Allow",
            "Action": [
                "iam:GetRole",
                "iam:CreateServiceLinkedRole"
            ],
            "Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/aws-service-role/eks-nodegroup.amazonaws.com/AWSServiceRoleForAmazonEKSNodegroup"
        },
        {
            "Sid": "EKSDeleteClusterV6",
            "Effect": "Allow",
            "Action": "eks:DeleteCluster",
            "Resource": "arn:aws:eks:*:<AWS_ACCOUNT_ID>:cluster/*"
        }
    ]
}

4. Creating IAM Service Policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyAdminPolicyAttachment",
            "Effect": "Deny",
            "Action": [
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy"
            ],
            "Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*",
            "Condition": {
                "ArnLike": {
                    "iam:PolicyARN": [
                        "arn:aws:iam::aws:policy/AdministratorAccess",
                        "arn:aws:iam::aws:policy/PowerUserAccess",
                        "arn:aws:iam::aws:policy/*FullAccess"
                    ]
                }
            }
        },
        {
            "Sid": "DenyInlinePolicyEscalation",
            "Effect": "Deny",
            "Action": [
                "iam:PutRolePolicy",
                "iam:PutUserPolicy",
                "iam:PutGroupPolicy"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ReadOnlyDescribeListIAMScoped",
            "Effect": "Allow",
            "Action": [
                "iam:GetRole",
                "iam:ListRolePolicies",
                "iam:ListAttachedRolePolicies",
                "iam:ListInstanceProfilesForRole",
                "iam:GetInstanceProfile",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:ListPolicyVersions",
                "iam:ListAccessKeys"
            ],
            "Resource": [
                "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*",
                "arn:aws:iam::<AWS_ACCOUNT_ID>:instance-profile/eks-*",
                "arn:aws:iam::<AWS_ACCOUNT_ID>:policy/eks-*"
            ]
        },
        {
            "Sid": "ReadOnlyDescribeListUnavoidableStar",
            "Effect": "Allow",
            "Action": "iam:ListRoles",
            "Resource": "*"
        },
        {
            "Sid": "IAMLifecycleRolesPoliciesInstanceProfiles",
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:TagRole",
                "iam:CreatePolicy",
                "iam:DeletePolicy",
                "iam:DeletePolicyVersion",
                "iam:TagPolicy",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:CreateInstanceProfile",
                "iam:TagInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:DeleteInstanceProfile"
            ],
            "Resource": [
                "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*",
                "arn:aws:iam::<AWS_ACCOUNT_ID>:policy/eks-*",
                "arn:aws:iam::<AWS_ACCOUNT_ID>:instance-profile/eks-*"
            ]
        },
        {
            "Sid": "EKSDeleteRoles",
            "Effect": "Allow",
            "Action": "iam:DeleteRole",
            "Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks*"
        },
        {
            "Sid": "PassRoleOnlyToEKS",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": [
                        "eks.amazonaws.com",
                        "ec2.amazonaws.com",
                        "eks-pods.amazonaws.com",
                        "pods.eks.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Sid": "PassRoleForEKSPodIdentityRoles",
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": [
                "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*-karpenter-role",
                "arn:aws:iam::<AWS_ACCOUNT_ID>:role/eks-*-backup-recovery-utility-role"
            ]
        }
    ]
}

5. Creating KMS Service Policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "KMSCreateAndList",
            "Effect": "Allow",
            "Action": [
                "kms:CreateKey",
                "kms:ListAliases"
            ],
            "Resource": "*"
        },
        {
            "Sid": "KMSKeyManagementScoped",
            "Effect": "Allow",
            "Action": [
                "kms:PutKeyPolicy",
                "kms:GetKeyPolicy",
                "kms:DescribeKey",
                "kms:GenerateDataKey",
                "kms:Decrypt",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:EnableKeyRotation",
                "kms:GetKeyRotationStatus",
                "kms:ListResourceTags",
                "kms:ScheduleKeyDeletion",
                "kms:CreateAlias",
                "kms:DeleteAlias"
            ],
            "Resource": [
                "arn:aws:kms:*:<AWS_ACCOUNT_ID>:key/*",
                "arn:aws:kms:*:<AWS_ACCOUNT_ID>:alias/*"
            ]
        }
    ]
}

6. Creating AWS S3 Service Policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3EncryptionConfigAndStateScoped",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetEncryptionConfiguration",
                "s3:PutEncryptionConfiguration",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:CreateBucket",
                "s3:GetBucketTagging",
                "s3:GetBucketPolicy",
                "s3:GetBucketAcl",
                "s3:GetBucketCORS",
                "s3:PutBucketTagging",
                "s3:GetBucketWebsite",
                "s3:GetBucketVersioning",
                "s3:GetAccelerateConfiguration",
                "s3:GetBucketRequestPayment",
                "s3:GetBucketLogging",
                "s3:GetLifecycleConfiguration",
                "s3:GetReplicationConfiguration",
                "s3:GetBucketObjectLockConfiguration",
                "s3:DeleteBucket",
                "s3:PutBucketVersioning",
                "s3:ListBucketVersions",
                "s3:DeleteObjectVersion",
                "s3:GetObjectTagging"
            ],
            "Resource": "arn:aws:s3:::*",
            "Condition": {
                "StringEquals": {
                    "aws:RequestedRegion": [
                        "<REGION>"
                    ],
                    "aws:PrincipalAccount": "<AWS_ACCOUNT_ID>"
                }
            }
        }
    ]
}
 
 

Description for the JSON components

This section provides information for the permissions mentioned in the JSON file.

IAM Roles

Contact the IT team to create the necessary IAM roles with the following permissions to create and manage AWS EKS resources.

These policies are managed by AWS. For more information about AWS managed policies, refer to AWS managed policies for Amazon Elastic Kubernetes Service in the AWS documentation.

AWS IAM Permissions

The AWS IAM user or role to install PPC must have permissions to create and manage Amazon EKS clusters and the required supporting AWS resources.

EC2 Permissions

EKS Permissions

IAM Permissions

AWS S3 Permissions

KMS Permissions

Jump box or local machine

• A newly provisioned EC2 instance must be used as the jump box for PPC deployment.

• The jump box must be provisioned in the same AWS region where the PPC cluster will be deployed to ensure proper connectivity and access to regional resources.

• Supported operating systems: RHEL 10, Debian 13, or Debian 12.

Note: Ensure to retain the original jump box used for installation. The Terraform state files required for cleaning and upgrading the cluster are available on this jump box. A snapshot of the jump box must be maintained to prevent data loss.

AWS Account Details

• A valid AWS account where Amazon EKS is deployed.

• The AWS account ID and AWS region must be identified in advance, as all resources are provisioned in the selected region.

Service Quotas

Verify that the AWS account has sufficient service quotas to support the deployment. At a minimum, ensure adequate limits for the following:

• EC2 instances based on node group size and instance types.
• VPC and networking limits, including subnets, route tables, and security groups.
• Elastic IP addresses and Load balancers.

If required, request quota increases through the AWS Service Quotas console before proceeding.

Service Control Policies (SCPs)

The AWS account must not have SCPs that restrict required permissions. In particular, SCPs must not block the following actions:

• eks:*
• ec2:*
• iam:PassRole

Restrictive SCPs may prevent successful cluster creation and resource provisioning.

Virtual Private Cloud (VPC)

• An existing VPC must be available in the target AWS region.
• The VPC should be configured to support Amazon EKS workloads.

Subnet Requirements

• At least two private subnets must be available.
• Subnets must be distributed across two or more Availability Zones (AZs).

Creating AWS KMS Key and AWS S3 Bucket

Amazon S3 Bucket: An Amazon S3 bucket is required to store critical data such as backups, configuration artifacts, and restore metadata used during installation and recovery workflows. Using a dedicated AWS S3 bucket helps ensure data durability, isolation, and controlled access during cluster operations.

AWS KMS Key: An AWS KMS customer‑managed key is required to encrypt data stored in the AWS S3 bucket. This ensures that sensitive data is protected at rest and allows customers to manage encryption policies, key rotation, and access control in accordance with their security requirements.

Note: The KMS key must allow access to the IAM roles used by the EKS cluster and related services.

The following section explains how to create AWS KMS Key and AWS S3 Bucket. This can be done from the AWS Web UI or using the script.

• Using AWS Web UI
• Using the bootstrap script

cat > kms-key-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Id": "key-resource-policy-0",
  "Statement": [
    {
      "Sid": "Allow KMS administrative actions only, no key usage permissions.",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<<ADMIN_AWS_ACCOUNT>>:root"
      },
      "Action": [
        "kms:Create*",
        "kms:Describe*",
        "kms:Enable*",
        "kms:List*",
        "kms:Put*",
        "kms:Update*",
        "kms:Revoke*",
        "kms:Disable*",
        "kms:Get*",
        "kms:Delete*",
        "kms:ScheduleKeyDeletion",
        "kms:CancelKeyDeletion"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Allow user running bootstrap.sh script of the PPC to use the KMS key.",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<<SSO_OR_IAM_USER_ACCOUNT_ARN>>"
      },
      "Action": [
        "kms:DescribeKey",
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncryptFrom",
        "kms:ReEncryptTo",
        "kms:GenerateDataKey",
        "kms:GenerateDataKeyWithoutPlaintext"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Allow backup recovery utility and EKS Node roles KMS key usage permissions, Replace <<<<CLUSTER_NAME>>>> with the name of your EKS cluster.",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<<DEPLOYMENT_AWS_ACCOUNT>>:root"
      },
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:ReEncryptFrom",
        "kms:ReEncryptTo",
        "kms:GenerateDataKey",
        "kms:GenerateDataKeyWithoutPlaintext",
        "kms:GenerateDataKeyPair",
        "kms:GenerateDataKeyPairWithoutPlaintext",
        "kms:DescribeKey"
      ],
      "Resource": "*",
      "Condition": {
        "ArnLike": {
          "aws:PrincipalArn": [
            "arn:aws:iam::<<DEPLOYMENT_AWS_ACCOUNT>>:role/eks-<<CLUSTER_NAME>>-backup-recovery-utility-role",
            "arn:aws:iam::<<DEPLOYMENT_AWS_ACCOUNT>>:role/eks-<<CLUSTER_NAME>>-node-role"
          ]
        }
      }
    }
  ]
}
EOF

aws sts get-caller-identity --query Arn --output text

Do you want to use an existing AWS S3 bucket, or provision a new one (with KMS key)?
  1) Use existing
  2) Provision new via Tofu (backup-infra)

Blocking Public Access to the AWS S3 Bucket

The PPC bootstrap script does not configure AWS S3 Block Public Access at the per-bucket level. This is by design because many AWS Organizations enforce AWS S3 Block Public Access through Service Control Policies (SCPs) at the account or organization level. This causes per-bucket s3:PutBucketPublicAccessBlock calls to fail with AccessDenied. AWS enabled S3 Block Public Access by default for all new accounts created after April 2023. However, verify the settings manually before proceeding.

Warning: The AWS S3 backup bucket stores highly sensitive data. Ensure that AWS S3 Block Public Access is enforced at the AWS account or organization level to prevent accidental public exposure.

Verify that AWS S3 Block Public Access is enabled at the account level before deploying PPC:

1. Navigate to the Amazon AWS S3 console.

2. Click Account and organization settings from the left navigation.

3. Ensure all four settings are enabled and set to On:

   • Block public access to buckets and objects granted through new access control lists (ACLs)
   • Block public access to buckets and objects granted through any access control lists (ACLs)
   • Block public access to buckets and objects granted through new public bucket or access point policies
   • Block public and cross-account access to buckets and objects through any public bucket or access point policies

4. If it is set to Off, then click Edit, select the check boxes, and click Save changes.

5. Verify that the Block Public Access settings for this account are enabled using the following command:

   aws s3control get-public-access-block --account-id $(aws sts get-caller-identity --query Account --output text)
   

   All four fields BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy, RestrictPublicBuckets should be set to true.

Note: To block the permissions at the bucket level, navigate to Buckets > General purpose buckets > select the bucket > Permissions > Block public access (bucket settings).

Zone Requirements

The cluster requires a minimum of two availability zones for high availability. It is required to have two zones available while deploying a PPC.

Zones are derived from the private subnets which are provided. Each subnet maps to exactly one availability zone. During the installation, the bootstrap script validates that the selected subnets are in different Availability Zones.

Note: Zones cannot be changed after cluster creation.

2 - Preparing for PPC deployment

If the jump box is already set previously, run the ./bootstrap.sh --cloud aws destroy command in the directory where the cluster is installed. This ensures that the local repository on the jump box and the clusters are cleaned up before proceeding with a new installation.

Warning: Do not install or manage multiple clusters from the same working directory. Each cluster deployment maintains its own Terraform/OpenTofu state, and reusing a directory can overwrite state files, causing loss of cluster tracking and unintended cleanup behavior.
Use a dedicated directory, and jump box, where possible, per cluster, and always verify the active kubectl context before running cleanup commands such as ./bootstrap.sh --cloud aws destroy.

1. Log in to the My.Protegrity portal.

2. Navigate to Product Management > Explore Products > AI Team Edition > Platform & Features.

3. Navigate to Platform Installation.

4. From the Actions column for Protegrity Provisioned Cluster, click the Download Product icon to download the PPC 1.1 archive.

5. Create a deployment directory on the jumpbox.

   mkdir deployment && cd deployment
   

6. Copy the PCT to the deployment directory on the jump box.

7. Extract the PCT.

   tar -xvf PPC-K8S-ALL_1.1.0.97.tar
   

3 - Deploying PPC

By default, the PCT is configured to deploy a FIPS-enabled cluster using FIPS-compliant Bottlerocket AMIs.

Non-FIPS deployment: Before proceeding with the installation, complete the steps in Configuring PPC for Non-FIPS Deployment on AWS to modify the required Terraform configuration files. Then proceed with either the automated or component-based installation below.

FIPS deployment: No additional configuration is required. Proceed directly with either the automated or component-based installation below.

The PPC cluster can be deployed using one of the following methods:

Automated script-based installation: This method requires the bootstrap.sh script to deploy the PPC cluster. The script installs the required software and dependencies, prompts to provide the required information, and deploys the cluster automatically.

Manual component-based installation: This method requires to perform the deployment of each component to install the PPC cluster. The configuration files are edited to provide the required information and then deploy the cluster.

3.1 - Configuring PPC for Non-FIPS Deployment on AWS

Before you begin

By default, the PCT is configured to deploy a FIPS-enabled cluster using FIPS-compliant Bottlerocket AMIs. To deploy a standard, non-FIPS cluster, the following Terraform configuration files must be modified to use the standard (non-FIPS) Bottlerocket AMI types and SSM parameter paths before running the bootstrap script or the component-based installation.

Perform these steps after downloading and extracting the PCT and before proceeding with either the Script-based installation or the Component-based installation.

Configuring PPC for Non-FIPS Deployment on AWS

For a non-FIPS PPC deployment on AWS EKS, perform the following steps:

1. Update the node group AMI type map in the /03_node_group/variables.tf file.

The node_group_ami_type_map variable defines the fallback EKS AMI type used per node architecture when node_group_ami_type is not explicitly set. The FIPS-enabled defaults must be replaced with the corresponding standard Bottlerocket AMI types.

a. Navigate to /03_node_group directory.

cd iac/aws/cluster/modules/03_node_group/

b. Edit the variables.tf file to make the following changes.

Change from (FIPS defaults):

variable "node_group_ami_type_map" {
  description = "Fallback EKS AMI type per architecture, used when node_group_ami_type is empty."
  type        = map(string)
  default = {
    amd64 = "BOTTLEROCKET_x86_64_FIPS"
    arm64 = "BOTTLEROCKET_ARM_64_FIPS"
  }
}

Change to (non-FIPS values):

variable "node_group_ami_type_map" {
  description = "Fallback EKS AMI type per architecture, used when node_group_ami_type is empty."
  type        = map(string)
  default = {
    amd64 = "BOTTLEROCKET_x86_64"
    arm64 = "BOTTLEROCKET_ARM_64"
  }
}

2. Update the Karpenter AMI SSM parameter path in the /05_helm_releases/main.tf file.

The karpenter_fips_ami_ssm_parameter value specifies the AWS Systems Manager (SSM) parameter path that Karpenter uses to resolve the correct Bottlerocket AMI for worker nodes. The default path targets the FIPS AMI. For a non-FIPS cluster, remove the -fips segment from the EKS version portion of the path.

a. Navigate to /05_helm_releases directory.

cd iac/aws/cluster/modules/05_helm_releases/

b. Edit the main.tf file to make the following changes.

Change from (FIPS SSM path):

karpenter_fips_ami_ssm_parameter = "/aws/service/bottlerocket/aws-k8s-${data.aws_eks_cluster.this.version}-fips/${local.karpenter_ami_arch}/latest/image_id"

Change to (non-FIPS SSM path):

karpenter_fips_ami_ssm_parameter = "/aws/service/bottlerocket/aws-k8s-${data.aws_eks_cluster.this.version}/${local.karpenter_ami_arch}/latest/image_id"

After completing all these configuration changes, proceed with deploying the cluster using one of the following methods:

• Script-based installation: Run the bootstrap.sh script to deploy the cluster automatically.

• Component-based installation: Apply each Terraform module individually.

3.2 - Automated script-based installation

Note for non-FIPS deployments: If you completed the steps in Configuring PPC for Non-FIPS Deployment on AWS, then the required Terraform configuration files have already been updated with non-FIPS values. The bootstrap script reads these files directly. Do not modify 03_node_group/variables.tf or 05_helm_releases/main.tf files back to FIPS defaults. Reverting those changes will result in a FIPS cluster being deployed instead of a non-FIPS cluster.

Before you begin

• Before running the bootstrap or resiliency scripts as the root user on RHEL, ensure that /usr/local/bin, and the AWS CLI binary path, if applicable, is included in the $PATH. Alternatively, run the script using a non-root user, such as ec2-user, where /usr/local/bin is already part of the default PATH.

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

• AWS CLI - Required to communicate with the AWS account.
• OpenTofu - Required to manage infrastructure as code.
• kubectl - Required to communicate with the Kubernetes cluster.
• Helm - Required to manage Kubernetes packages.
• skopeo - Required to copy and inspect container images across registries without requiring a daemon.
• jq - Required to parse JSON.

The bootstrap script also checks if you have the required permissions on AWS. It then sets up the EKS cluster and installs the microservices required for deploying the PPC.

Architecture Selection

The step [1b] Select Node Architecture in the bootstrap script prompts to select the node architecture interactively during deployment.

• amd64 (x86-64-based environments such as standard Intel or AMD servers)

• arm64 (ARM-based environments such as AWS Graviton)

Deploying the PPC

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

./bootstrap.sh --cloud aws --arch amd64

The script prompts for the following variables.

1. Enter 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
   • Names longer than 31 characters (the cluster name must be 31 characters or fewer)

   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, specify a cluster name that is 31 characters or fewer and re-run the script. The script automatically applies the updated value and continues the bootstrap process.

   After the cluster name is accepted, the script prompts you to select the node architecture.

   [1b] Select Node Architecture

   [1b] Select Node Architecture
     1) amd64 (x86_64) — e.g. t3, m5, c5 instances
     2) arm64 (Graviton) — e.g. t4g, m7g, c7g instances
   

   Enter 1 to select amd64 or 2 to select arm64.

   Note: Select amd64 for standard Intel/AMD 64-bit environments. Select arm64 for ARM-based environments such as AWS Graviton instances.

2. Enter a VPC ID from the table

   The script automatically retrieves the available VPCs. Enter the VPC ID where the cluster must be created.

3. Querying for subnets in VPC…

   The script queries for the available VPC subnets and prompts to enter two private subnet IDs. Specify two private subnet IDs from different availability zones.
   The script automatically updates the VPC CIDR block based on the VPC details.

4. Enter FQDN

   This is the Fully Qualified Domain Name (FQDN) 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: - .

5. Select S3 Backup Bucket Option

   The script prompts to choose how to provide the AWS S3 bucket encrypted with SSE‑KMS used for storing cluster backups for disaster recovery.

   Do you want to use an existing S3 bucket, or provision a new one (with KMS key)?
     1) Use existing
     2) Provision new via Tofu (backup-infra)
   

6. Enter S3 bucket name

   • Option 1 – Use existing: Enter the name of an existing S3 bucket in your AWS account. The bucket must already be encrypted with SSE‑KMS.
   • Option 2 – Provision new via Tofu: The script uses OpenTofu (backup-infra) to create the S3 bucket and the corresponding KMS key on your behalf. Provide a globally unique bucket name when prompted:
     • Lowercase letters, digits, and hyphens only
     • Between 3 and 63 characters
     • Must not already exist

   Use a dedicated S3 bucket per cluster for backup and restore operations to ensure data and encryption isolation. Sharing a bucket across clusters increases the risk of cross-cluster data access or decryption due to IAM misconfiguration. Dedicated buckets with unique IAM policies eliminate this risk.

   During disaster management, OpenSearch restores only those snapshots that are created using the daily-insight-snapshots policy. For more information, refer to Backing up and restoring indexes.

7. Enter Image Registry Endpoint

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

   Expected format: <hostname>[:port].
   Do not include ‘https://’

   Note: The container registry endpoint must be a Fully Qualified Domain Name (FQDN). Sub-paths like, my-registry.com/v2/path, are not supported by the Open Container Initiative (OCI) distribution specification.

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

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

10. Enter Owner Email (for cluster tagging)

    Enter email address in the format name@domain.tld. This email is used for the cluster ‘Owner’ tag and the platform owner contact.

Note: The cluster creation process can take 10-15 minutes.

If the session is terminated during installation due to network issues, power outage, and so on, then the installation stops. To restart the installation, run the script again:

# Navigate to setup directory 
./bootstrap.sh --cloud aws

Important Information

• Do not install or manage multiple clusters from the same working directory. Each cluster deployment maintains its own Terraform/OpenTofu state, and reusing a directory can overwrite state files, causing loss of cluster tracking and unintended cleanup behavior.

• Use a dedicated directory, and jump box, where possible, per cluster, and always verify the active kubectl context before running cleanup commands such as ./bootstrap.sh --cloud aws destroy.
  To check the active kubectl context, run the following command:
  kubectl config current-context

• Do not delete the original cluster deployment directory, as it contains the Terraform state files required for managing the deployment.

3.3 - Manual component-based installation

Before you begin

Ensure to have the following prerequisites before proceeding with the installation.

Jump box requirement

Ensure that the entire process is performed using the same jump box.

Parameter values

Deploying PPC using component-based installation

To deploy PPC using the component-based installation, perform the following steps

1. Exporting AWS credentials

The installation process uses Terraform to provision and manage AWS resources, such as VPCs, EKS clusters, IAM roles, and S3 buckets. The AWS credentials must be exported as environment variables to authenticate these operations.

Note: While using temporary credentials, such as, using AWS STS, ensure the session token is included and that the credentials have not expired before proceeding.

If the components are installed by different users, ensure that each user must export their AWS credentials. This ensures that all the required access and permissions are available.

To export the AWS credentials, run the following commands.

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_SESSION_TOKEN=<your-session-token>

2. Installing the tools

The following tools and minimum versions are required for the component-based installation. Ensure they are installed on your jump box before proceeding, or use the bootstrap.sh install-tools command to install them automatically.

After downloading and extracting the PPC-K8S-ALL_1.1.0.97.tar, run the following command to install the required tools.

./bootstrap.sh install-tools --cloud aws

Alternatively, the following tools must be installed and available on the jump box before starting.

3. Provisioning the S3 bucket

This step is required if a new S3 bucket is to be provisioned for storing the backup data. If an existing S3 bucket is to be used, note the bucket name and KMS key ARN required for the installation process and skip to the next step.

a. To navigate to 00_backup_bucket directory, run the following command.

cd iac/aws/cluster/modules/00_backup_bucket

b. Edit the terraform.tfvars file to provide the following information.

cluster_name                = "<cluster-name>" 
s3_bucket_name              = "<globally-unique-bucket-name>" 
kms_key_alias_name          = "alias/pty-backup-<cluster-name>-key" 
aws_region                  = "<region>" 

c. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

After the S3 bucket is provisioned successfully, note the bucket name and KMS key ARN. These values are required during the installation process.

d. To sync the Terraform state file to the S3 bucket, run the following command.

# Navigate to the bootstrap-scripts directory
cd <package-root>/bootstrap-scripts

# Run the script to sync the backup data to the S3 bucket
./sync-backup-bucket-state-to-s3.sh

4. Modifying and applying terraform.tfvars files

The iac/aws/cluster/modules/ directory contains the Terraform modules for the PPC installation. To enter details in the terraform.tfvars file, navigate to the appropriate module directory and edit the file accordingly.

After modifying the terraform.tfvars file, apply the changes

01_iam_roles module

a. To navigate to 01_iam_roles directory, run the following command.

cd iac/aws/cluster/modules/01_iam_roles

b. Edit the terraform.tfvars file to provide the following information.

aws_region            = "<region>"          
eks_cluster_name      = "<cluster-name>"
backup_bucket         = "<s3-bucket-name>"
backup_bucket_kms_arn = "<kms-key-arn>"    

c. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

d. After the configurations are successfully applied, verify the required resources are created.
To verify if the resources are created successfully, run the following command.

aws iam list-roles --query "Roles[?contains(RoleName, 'doc-test')].[RoleName, Arn]" --output table

The EKS cluster IAM role, Node group IAM role, and Service account IAM roles must be created.

Additionally, note the role ARNs from the Terraform output. These values are required in subsequent modules.

02_eks_cluster module

a. To navigate to 02_eks_cluster directory, run the following command.

cd iac/aws/cluster/modules/02_eks_cluster

b. Edit the terraform.tfvars file to provide the following information.

Ensure that the security group name must not start with sg.

aws_region          = "<region>"
eks_cluster_name    = "<cluster-name>"
backup_bucket       = "<s3-bucket-name>" 

# --- Networking ---
vpc_id              = "<vpc-id>" 
security_group_name = "<security-group-name>" 
private_subnet_ids  = [
  "<subnet-a>",
  "<subnet-b>"
]

# --- Tagging ---
owner_email = "<owner_email>"

# --- Access Entries (optional) ---
# Add IAM users/roles that need kubectl / tofu access beyond the original installer.
additional_access_entries = [
  # {
  #   principal_arn = "<principal-arn>"
  # },
]

c. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

d. After the configurations are successfully applied, verify the required resources are created.
To verify if the resources are created successfully, run the following command.

# Confirm the cluster is ACTIVE
aws eks describe-cluster --name <cluster-name> --region <region> \
  --query "cluster.{Name:name, Status:status, Version:version, Endpoint:endpoint}" \
  --output table
 
# Verify kubectl can reach the API server
kubectl get nodes          # expected: no nodes yet (node group is Stage 03)
 
# Verify the worker security group exists
aws ec2 describe-security-groups \
  --filters "Name=group-name,Values=<security-group-name>*" \
  --region <region> \
  --query "SecurityGroups[].{Name:GroupName, ID:GroupId}" \
  --output table
 
# Verify VPC CNI and kube-proxy add-ons are ACTIVE
aws eks list-addons --cluster-name <cluster-name> --region <region> --output table

03_node_group module

a. To navigate to 03_node_group directory, run the following command.

cd iac/aws/cluster/modules/03_node_group

b. Edit the terraform.tfvars file to provide the following information.

Note: Use the private subnet IDs from the VPC where the EKS cluster is provisioned while installing the 02_eks_cluster module.

aws_region       = "<region>" 
eks_cluster_name = "<cluster-name>" 
backup_bucket    = "<s3-bucket-name>" 

# --- System Node Group ---
node_group_name    = "<node-group-name>" 
private_subnet_ids = [
  "<subnet-a>",
  "<subnet-b>"
]
architecture            = "<amd64/arm64>"
node_group_desired_size = 2      
node_group_max_size     = 2
node_group_min_size     = 1

Note for non-FIPS deployments: If you completed the steps in Configuring PPC for Non-FIPS Deployment on AWS, the node_group_ami_type_map default values in variables.tf file have already been changed to BOTTLEROCKET_x86_64 (amd64) or BOTTLEROCKET_ARM_64 (arm64). Do not add or override node_group_ami_type with a FIPS value in terraform.tfvars, as this will reintroduce FIPS AMIs.

c. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

d. After the configurations are successfully applied, verify the required resources are created.
To verify if the resources are created successfully, run the following command.

aws eks describe-nodegroup --cluster-name <cluster-name> --nodegroup-name <node-group-name> --query "nodegroup.status"
kubectl get nodes

Ensure that the Node group status is ACTIVE and the desired number of nodes are in Ready state.

04_eks_addons module

a. To navigate to 04_eks_addons directory, run the following command.

cd iac/aws/cluster/modules/04_eks_addons

b. Edit the terraform.tfvars file to provide the following information.

aws_region       = "<region>"
eks_cluster_name = "<cluster-name>"
backup_bucket    = "<s3-bucket-name>" # 

# --- Upgrade mode only ---
# Set to "~/.kube/config" when upgrading an existing cluster;
# leave empty ("") for a fresh install.
kubeconfig_path  = ""

c. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

Note: This stage waits for all nodes from Stage 03 to reach Ready status before installing add-ons.

d. After the configurations are successfully applied, verify the required resources are created.
To verify if the resources are created successfully, run the following command.

# List all EKS add-ons and confirm they are ACTIVE
aws eks list-addons --cluster-name <cluster-name> --region <region> --output table
 
# Check add-on health details
for addon in coredns metrics-server aws-ebs-csi-driver snapshot-controller eks-pod-identity-agent; do
  echo "--- $addon ---"
  aws eks describe-addon --cluster-name <cluster-name> --addon-name $addon --region <region> \
    --query "addon.{Name:addonName, Status:status, Version:addonVersion}" --output table
done
 
# Verify the default storage class exists
kubectl get storageclass
 
# Confirm CoreDNS and Metrics Server pods are running
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl get pods -n kube-system -l k8s-app=metrics-server

05_helm_releases module

a. To navigate to 05_helm_releases directory, run the following command.

cd iac/aws/cluster/modules/05_helm_releases

b. Edit the terraform.tfvars file to provide the following information.

The default node OS is BOTTLEROCKET_x86_64_FIPS. While providing the node_os value, ensure that the value must be the same as nnode_group_ami_type value obtained from the 03_node_group module.

For obtaining the value of node_os, run the following command.

kubectl get nodes -o jsonpath='{.items[0].status.nodeInfo.osImage}'; echo

Provide the node_os value in the terraform.tfvars file.

aws_region            = "<region>"
eks_cluster_name      = "<cluster-name>"
backup_bucket         = "<s3-bucket-name>" 
backup_bucket_kms_arn = "<kms-key-arn>"
architecture          = "<amd64/arm64>"
node_os               = "<node-os>"

# --- Registry ---
global_image_reg = "<registry-endpoint>"
harbor_secret    = "harbor-secret" 

# --- Ingress ---
ingress_fqdn = "<fqdn>" 

# --- Owner ---
owner_email = "<owner-email>" 

# --- Networking (used to derive internal proxy CIDRs) ---
vpc_cidr_block = "<cidr>" 

# --- Envoy Gateway (LoadBalancer subnet discovery) ---
# Populated automatically by bootstrap.sh from stage 02 state.
private_subnet_ids = []

# --- Restore ---
restore              = false                               
backup_name          = "authnz-postgresql-schedule-backup" 
insight_backup_name  = ""                                  

# --- Upgrade mode only ---
# Set to "~/.kube/config" when upgrading an existing cluster;
# leave empty ("") for a fresh install.
kubeconfig_path = ""
is_upgrade      = false
skip_validations = false

c. To enter registry credentials using the environment variables, run the following commands.

export TF_VAR_username="<registry-username>"
export TF_VAR_password="<registry-password>"

d. To apply the terraform configuration, run the following command.

tofu init 
tofu plan          # review the role assignments that will be created
tofu apply         # type "yes" when prompted

Note: This process may take 15–20 minutes to get completed. Karpenter nodes are provisioned on demand after the NodePool is created.

e. After the configurations are successfully applied, verify the required resources are created.
To verify if the resources are created successfully, run the following command.

# Confirm all Helm releases are deployed
helm list -A
 
# Verify Karpenter controller is running
kubectl get pods -n karpenter
 
# Verify Karpenter NodePool and EC2NodeClass exist
kubectl get nodepools
kubectl get ec2nodeclasses
 
# Verify Velero is running
kubectl get pods -n pty-backup-recovery
 
# Verify PPC platform pods
kubectl get pods -A 
 
# Verify Insight pods
kubectl get pods -n pty-insight
 
# Verify Envoy Gateway
kubectl get pods -n api-gateway
 
# Check all pods across the cluster are healthy
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded

5. Verifying the installation

To verify the installation, run the following command.

kubectl get nodes
kubectl get pods -A

All the nodes should be in the Ready state and all the pods should be in the Running state.

4 - Installing Features and Protectors

Before you begin

Ensure that PPC is successfully installed before installing the features or protectors.

Installing Features

The following table lists the available features.

Installing Protectors

The following table lists the available protectors.

5 - Accessing the PPC CLI

5.1 - Prerequisites

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

To access the PPC CLI, ensure that the following prerequisites are met.

• SSH Keys: The SSH private key that corresponds to the public key configured in the pty-cli pod is required.

• Network Access: Ensure to have network connectivity to the cluster.

• Resolve FQDN: Use Route 53 configuration on AWS to resolve the PPC FQDN specified during the installation to the internal load balancer. For more information, refer to Prerequisites.

• Linux/macOS
• Windows

ssh -i /home/admin/.ssh/<cluster_name>_user_svc ptyitusr@<user-provided-fqdn>

5.2 - Accessing the PPC CLI

Once connected, the Protegrity CLI welcome banner is displayed. Enter the following parameters when prompted:

• Username: Application username
• Password: Application password

For more information about the default credentials, refer to the Release Notes.

The CLI supports three main command categories:

• pim: Policy Information Management commands for data protection policies.
• admin: User, Role, Permission, and Group management commands.
• insight: Log forwarding to external SIEM and syslog servers.

Note: Ensure that at least one additional backup administrator user is configured with the same administrative privileges as the primary admin user.
If the primary admin account is locked or its credentials are lost, restoring the system from a backup is the only recovery option.

6 - Login to PPC

6.1 - Prerequisites

Use Route 53 configuration on AWS to resolve the PPC FQDN specified during the installation to the internal load balancer.

• Ensure that the instance is using the AWS-provided DNS server, such as, VPC CIDR + 2.
• Verify that enableDnsHostnames and enableDnsSupport are set to true in the VPC settings.
• Verify the Security Group of the load balancer. Ensure that Inbound traffic is allowed on the required ports, such as, 80 and 443, from the client instance’s IP or Security Group.
• Keep the following information ready:
  • VPC ID: The ID of the VPC for the client instances and the Load Balancer. For example, vpc-0123456789.
  • Internal ELB DNS Name: The DNS name of the load balancer. For example, internal-abcdefghi123456-123456789.us-east-1.amazonaws.com.
  • Target FQDN: The FQDN for PPC. For example, mysite.aws.com.

1. Find the AWS Load Balancer address.

    kubectl get gateway -A

The output appears similar to the following:

    NAMESPACE     NAME       CLASS   ADDRESS                                                                         PROGRAMMED   AGE
    api-gateway   pty-main   envoy   a814fae40464d462da9ca685921699c0-1ccfcf98919adf90.elb.us-east-1.amazonaws.com   True         34m

2. Verify that the gateway address resolves to an internal IP, using the following command.

    ping <gateway_address>

Where <gateway_address> is the ADDRESS value from the previous step.

The output confirms that the hostname resolves to a private VPC IP address (10.x.x.x range), indicating the load balancer is internal and accessible only within the AWS VPC.

The output appears similar to the following:

    PING a814fae40464d462da9ca685921699c0-1ccfcf98919adf90.elb.us-east-1.amazonaws.com (10.31.4.172) 56(84) bytes of data.

3. Map the PPC FQDN to the load balancer using Route 53.

For more information about configuring Route 53, refer to the AWS documentation.

6.2 - Log in to PPC

Access the PPC using the FQDN provided during the installation process.

Enter the following parameters to log in and view the Insight Dashboard.

• Username: Application username
• Password: Application password

For more information about the default credentials, refer to the Release Notes.

If Protegrity Agent is installed, then the Protegrity Agent dashboard appears. Click Insight to open the Insight Dashboard. For more information about Protegrity Agent, refer to Using Protegrity Agent.

7 - Upgrading the PPC

Before you begin

Before starting an upgrade, ensure the following conditions are met:

• Access to the jump box associated with the PPC v1.0.0 cluster is required. This must be the same jump box used during the PPC v1.0.0 installation.

• Maintain both, previous and current installation directories. Do not delete the original cluster deployment directory, as it contains the Terraform state files required for managing the deployment.

• Create a Velero backup and an OpenSearch snapshot to ensure data recovery is possible, in case of an upgrade failure.

• Maintain a backup of the state file in the AWS S3 backup bucket.

• If logs are forwarded to an external SIEM, then from the PPC CLI, run the insight delete syslog or the insight delete fluentd as per your configuration. After the upgrade is complete, re-configure the SIEM. For more information about SIEM configuration, refer to Sending logs to a SIEM.

• The context is set to the cluster where the upgrade operation is to be performed. Run the following command.

  kubectl config current-context
  

  The cluster name in the output must match the cluster installed with PPC v1.0.0.

Note: Before running the bootstrap or resiliency scripts as the root user on RHEL, ensure that /usr/local/bin, and the AWS CLI binary path, if applicable, is included in the $PATH. Alternatively, run the script using a non-root user, such as ec2-user where /usr/local/bin is already part of the default $PATH.

Upgrading PPC

To upgrade the PPC from v1.0.0 to v1.1.0, perform the following steps:

1. Create a deployment_110 directory on the jump box and navigate to it.

   mkdir deployment_110 && cd deployment_110
   

2. Log in to the My.Protegrity portal.

3. Navigate to Product Management > Explore Products > AI Team Edition > Platform & Features.

4. Navigate to Platform Installation.

5. From the Actions column for Protegrity Provisioned Cluster, click the Download Product icon and download the PPC 1.1 archive to the deployment_110 directory.

6. Extract the archive contents.

   tar -xvf PPC-K8S-ALL_1.1.0.97.tar
   

7. Copy the Terraform state file from the v1.0.0 cluster installation to the deployment_110 directory created for upgrade.

   cp /<v1.0.0-cluster-dir>/deployment/iac_setup/scripts/iac/terraform.tfstate /<v1.1.0-cluster-dir>/deployment_110/terraform.tfstate
   

   where <v1.0-cluster-dir> is the path to the original PPC v1.0.0 cluster installation directory on the jump box, and <v1.1.0-cluster-dir> is the path to the new directory created for upgrade.

8. Verify the active context points to the correct cluster using the following command.

    kubectl config current-context
   

9. Initiate the upgrade from the deployment_110 directory using the following command.

   bash upgrade.sh --cloud aws --v1.0-state-file /<v1.1.0-cluster-dir>/deployment_110/terraform.tfstate
   

   where /<v1.1.0-cluster-dir>/deployment/terraform.tfstate is the path to the Terraform state file copied in Step 6.

   After the upgrade is successful, a PPC upgrade completed successfully. message is displayed.

The cluster upgrade process can take 10–15 minutes approximately and may differ accordingly.

Post Upgrade Steps

Verify all nodes are Ready

To verify if all nodes are in the ready state, run the following command.

kubectl get nodes -o wide

Verify all pods are Running

To verify if all pods are in the running state, run the following command.

kubectl get pods -A

Verify Helm releases

To verify if the helm releases are in the deployed state, run the following command.

helm list -A

Password Policy After Upgrade

PPC v1.1.0 upgrade enforces the following behavior.

• If the minimum password length was set to a value less than 14 characters, or was not configured, the upgrade sets it to 14 characters.

• If the minimum password length was already set to 14 characters or greater, that value is preserved and remains unchanged after the upgrade.

For more information about the password policy, refer to Password Policy APIs or CLI reference for get password_policy.

Configuring SIEM

If logs were forwarded to an external SIEM before the upgrade, then SIEM log forwarding was disabled as part of the pre-upgrade prerequisites. After completing the upgrade, update the settings to resume sending logs to the external SIEM.

For more information about configuring SIEM, refer to Sending logs to an external security information and event management (SIEM).

Directory Maintenance after Upgrade

During upgrade, both the previous and the new PPC installation directories must be retained.

• The original directory contains Terraform state and deployment metadata.
• The new directory contains the updated configuration and binaries.

Both directories are required for proper management of the deployment.

Recovering from a Failed Upgrade

If the session is terminated during upgrade due to network issues, power outage, or any such issues, then the upgrade process stops. The ./upgrade.sh script resumes the upgrade.

To restart the process, run the following command:

   bash upgrade.sh --cloud aws --v1.0-state-file /<v1.1.0-cluster-dir>/deployment_110/terraform.tfstate

Warning: Do not install or manage multiple clusters from the same working directory. Each cluster deployment maintains its own Terraform or OpenTofu state, and reusing a directory can overwrite state files, causing loss of cluster tracking and unintended cleanup behavior.
Use a dedicated directory, and jump box, where possible, per cluster, and always verify the active kubectl context before running cleanup commands such as ./bootstrap.sh --cloud aws destroy.
To check the active kubectl context, run the following command:
kubectl config current-context

Reverting to a previous version of PPC

To revert to a previous version of PPC, restore the cluster using the steps in Restoring the PPC.

8 - Backing up the PPC

Protegrity Provisioned Cluster (PPC) supports backup of Insight indexes and cluster configurations. Use the procedures below to update the scheduled backups of your PPC deployment.

Backing up Velero backup schedule

To take a backup at an interval of 10 minutes, the cron job must be executed before the schedule. This ensures that the latest configurations are included and are available in the Storage Account.
By default, the cron job is executed after every 3 hours and schedule is executed after every 3.5 hours.

For taking the backups, the frequency of schedule and cron job can be changed, as required.

Perform the following steps to update the frequency.

1. To update the frequency of the cron job, run the following command.

   $ kubectl patch cronjob authnz-postgresql-backup-recovery-cron-job \
   -n api-gateway \'
   --type=merge -p '{"spec":{"schedule":"<required frequency>"}}'
   

2. To update the frequency of the schedule, run the following command.

   $ kubectl patch schedule authnz-postgresql-schedule-backup \   
   -n pty-backup-recovery \
   --type=merge -p '{"spec":{"schedule":"<required frequency>"}}' 
   

For instance, to update the frequency of the backup schedule to 10 minutes, perform the following steps.

1. To update the cron job to every 8 minutes, run the following command.

   $ kubectl patch cronjob authnz-postgresql-backup-recovery-cron-job \
    -n api-gateway \
    --type=merge -p '{"spec":{"schedule":"8-58/10 * * * *"}}'
   

2. To update the schedule to every 10 minutes, run the following command.

   $ kubectl patch schedule authnz-postgresql-schedule-backup \
    -n pty-backup-recovery \
    --type=merge -p '{"spec":{"schedule":"*/10 * * * *"}}'
   

Backing up indexes

Insight indexes are backed up automatically using a scheduled job. To manually back up the indexes, perform the following steps:

1. Log in to the Insight Dashboard.
2. Select the main menu.
3. Navigate to Management > Snapshot Management > Snapshot policies.
4. Click the daily-insight-snapshots policy.
5. Click Edit.
6. Update the following parameters:
   • Snapshot schedule
     • Frequency: Custom (Cron expression)
     • Cron expression: */15 * * * *
7. Click Update.
8. Wait for the next scheduled snapshot to complete. Verify that the snapshot is created from the snapshot status.

Note: The snapshot schedule is set to run every 15 minutes for creating the manual backup. Restore the default settings after the manual backup is complete. Before upgrading, disable the scheduler job after the backup is created. Ensure that the default parameters are restored and the job is re-enabled after the upgrade.

9 - Restoring the PPC

Before you begin

Before starting a restore, ensure the following conditions are met:

• An existing backup is available. Backups are taken automatically as part of the default installation using scheduled backup mechanisms. These backups are stored in an AWS S3 bucket configured during the original installation.

• Access to the original backup AWS S3 bucket. During restore, the same S3 bucket that was used during the original installation must be specified.

• Before initiating the restore, review and update the KMS key policy to reflect the restore cluster name. Even if the policy was already configured for the source cluster, it must be updated for the new restore cluster. If the policy continues to reference the source cluster name, the IAM role created during restore cannot decrypt the backup data, causing the restore to fail.

• Permissions to read from the S3 bucket. The user performing the restore must have sufficient permissions to access the backup data stored in the bucket.

• A Kubernetes cluster is created. Restore is performed as part of creating a cluster, not on an existing one. Restore is only supported during a fresh installation flow.

• While the backup is taken from the source cluster, do not perform Create, Read, Update, or Delete (CRUD) operations on the source cluster. This ensures backup consistency and prevents data corruption during restore.

• Before restoring to a new cluster, if the source cluster is accessible, disable the backup operations on the source cluster by setting the backup storage location to read‑only. This ensures that no additional backup data is written during the restore process.

  To disable the backup operation on the source cluster, run the following command:

  kubectl patch backupstoragelocation default -n pty-backup-recovery --type merge -p '{"spec":{"accessMode":"ReadOnly"}}'
  

  If the source cluster is not accessible, this step can be skipped.

During Disaster management, the backup data is used to restore the cluster and the OpenSearch indexes using snapshots. However, Insight restores OpenSearch data only from the most recent snapshot created by the daily-insight-snapshots policy.
For more information, refer to Backing up and restoring indexes.

Warning: Do not install or manage multiple clusters from the same working directory. Each cluster deployment maintains its own Terraform or OpenTofu state, and reusing a directory can overwrite state files, causing loss of cluster tracking and unintended cleanup behavior.
Use a dedicated directory, and jump box, where possible, per cluster, and always verify the active kubectl context before running cleanup commands such as ./bootstrap.sh --cloud aws destroy.

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

• AWS CLI - Required to communicate with your AWS account.
• bc - Required for version comparisons and resource calculations.
• cmctl - Required to validate and manage TLS certificates.
• Helm - Required to manage Kubernetes packages.
• jq - Required to parse JSON.
• kubectl - Required to communicate with the Kubernetes cluster.
• OpenTofu - Required to manage infrastructure as code.
• ORAS - Required to pull OCI artifacts such as deployment packages.
• skopeo - Required to copy container images between registries.
• ssh-keygen - Required to secure SSH access to deployment environments.

The bootstrap script also checks if you have the required permissions on AWS. It then sets up the EKS cluster and installs the microservices required for deploying the PCS on a PPC.

Note: Before running the bootstrap or resiliency scripts as the root user on RHEL, ensure that /usr/local/bin (and the AWS CLI binary path, if applicable) is included in the $PATH. Alternatively, run the script using a non-root user (such as ec2-user) where /usr/local/bin is already part of the default PATH.

Architecture Selection

• amd64 (x86-64-based environments such as standard Intel or AMD servers)
• arm64 (ARM-based environments such as AWS Graviton)

The bootstrap script prompts you to select the node architecture interactively during deployment (step 1b).

Restoring the PPC

Ensure that the PCT is downloaded and extracted on the jump box. For more information, refer to Preparing for PPC deployment.

Run the following command to initiate restore using an existing backup:

./bootstrap.sh --cloud aws --restore

To deploy PPC on ARM-based infrastructure, specify the architecture explicitly:

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

The --restore command enables the restore mode for the installation. It initiates restoration of data from the configured AWS S3 backup bucket. This process must be followed on a fresh jump box.

The script prompts for the following variables.

1. Enter Cluster Name

   • Ensure that the cluster name does not match the name of the source cluster. Reusing an existing cluster name during restore can lead to discrepancies during cluster installation.
     
   • This same cluster name must already be updated in the KMS key policy. If this update is not performed, the restore process fails because the new cluster cannot decrypt the backup data.
     
   • 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.

   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

   After the cluster name is accepted, the script prompts you to select the node architecture.

   [1b/10] Select Node Architecture

   [1b/10] Select Node Architecture
     1) amd64 (x86_64) — e.g. t3, m5, c5 instances
     2) arm64 (Graviton) — e.g. t4g, m7g, c7g instances
   

   Enter 1 to select amd64 or 2 to select arm64.

   Note: Select amd64 for standard Intel/AMD 64-bit environments. Select arm64 for ARM-based environments such as AWS Graviton instances.

2. Enter a VPC ID from the table

   The script automatically retrieves the available VPCs. Enter the VPC ID where the cluster must be created.

3. Querying for subnets in VPC…

   The script queries for the available VPC subnets and prompts to enter two private subnet IDs. Specify two private subnet IDs from different availability zones.
   The script then automatically updates the VPC CIDR block based on the VPC details.

4. Enter FQDN

   This is the Fully Qualified Domain Name (FQDN) for the ingress.

   While entering the FQDN, ensure that:

   • contains at least two labels separated by a dot, such as, app.example.com
   • does not start or end with a dot or hyphen
   • does not contain consecutive dot character
   • label length must be between 1–63 characters
   • each label must start and end with a letter or digit
   • the last label must start only with a letter

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

5. Restore mode requires an existing S3 bucket. Proceeding to existing bucket validation in Step 6.

6. Select S3 Backup Bucket Option

   An AWS S3 bucket encrypted with SSE‑KMS containing backup artifacts used during the restore process.

   Use a dedicated S3 bucket per cluster for backup and restore operations to ensure data and encryption isolation. Sharing a bucket across clusters increases the risk of cross-cluster data access or decryption due to IAM misconfiguration. Dedicated buckets with unique IAM policies eliminate this risk.

   Select backup

   During restore, the script prompts to manually select a backup from the available backups stored in the S3 bucket. User input is required to either restore from the latest backup or choose a specific backup from the list.

   [restore] Backup selection — schedule: authnz-postgresql-schedule-backup
   Restore from latest backup? [Y/n]
   

   • Enter Y to restore from the most recent backup.
   • Enter n to manually select a backup.

   If n is selected, then the script displays a list of available backups (latest first) and prompts to select one by number:

   Available backups (latest first):
   [1] <timestamp> authnz-postgresql-schedule-backup-xxxxxxx
   [2] <timestamp> authnz-postgresql-schedule-backup-xxxxxxx
   
   Select a backup number (1-2):
   

   After entering the backup number, the chosen backup is used for the restore, and the installation continues.

   Enter Insight backup

   During restore, the script prompts to manually select the required insight backup from the available backups stored in the S3 bucket. User input is required to either restore from the latest backup or choose a specific backup from the list.

   [restore] Insight backup selection — schedule: insight-configmaps-secrets
   Restore from latest backup? [Y/n]
   

   • Enter Y to restore from the most recent backup.
   • Enter n to manually select a backup.

   If n is selected, then the script displays a list of available backups (latest first) and prompts to select one by number:

   Available backups (latest first):
   [1] <timestamp>  insight-configmaps-secrets-xxxxxxxxx
   [2] <timestamp>  insight-configmaps-secrets-xxxxxxxxx
   
   Select a backup number (1-2):
   

   After entering the backup number, the chosen backup is used for the restore, and the installation continues.

7. Enter Image Registry Endpoint

   The image repository from where the container images are retrieved.

   Expected format: <hostname>[:port].
   Do not include ‘https://’

   Note: The container registry endpoint must be a FQDN (Fully Qualified Domain Name). Sub-paths like, my-registry.com/v2/path, are not supported by the OCI distribution specification.

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

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

10. Enter Owner Email (for cluster tagging)

    Enter email address in the format name@domain.tld. This email is used for the cluster ‘Owner’ tag and the platform owner contact.

Note: The cluster creation process can take approximately 15-20 minutes.

If the session is terminated during restore due to network issues, power outage, and so on, then the restore stops. To restart the process, run the following commands:

# Navigate to deployment directory and run the following command
./bootstrap.sh --cloud aws destroy

# Restore the cluster
./bootstrap.sh --cloud aws --restore

Warning: Do not install or manage multiple clusters from the same working directory. Each cluster deployment maintains its own Terraform or OpenTofu state, and reusing a directory can overwrite state files, causing loss of cluster tracking and unintended cleanup behavior.
Use a dedicated directory, and jump box, where possible, per cluster, and always verify the active kubectl context before running cleanup commands such as ./bootstrap.sh --cloud aws destroy.
To check the active kubectl context, run the following command:
kubectl config current-context

After the restore to the new cluster is completed successfully and all required validation and migration activities are finished, the source cluster can be deleted.

10 - Deleting PPC

Prerequisites

Authentication

The deletion process uses OpenTofu to destroy AWS resources, such as EKS clusters, IAM roles, S3 buckets, and KMS keys. The AWS credentials must be exported as environment variables to authenticate these operations.

Note: While using temporary credentials, such as, using AWS STS, ensure the session token is included and that the credentials have not expired before proceeding.

To export the AWS credentials, run the following commands.

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_SESSION_TOKEN=<your-session-token>

To verify that the credentials are valid and the correct AWS identity is being used, run the following command.

aws sts get-caller-identity

Required Permissions

The same IAM principal (or one with equivalent permissions) that installed the cluster, can delete the cluster. The principal must have cluster-creator admin access to the EKS Kubernetes API.

The required IAM Permissions are listed in the following table:

Required tools

The following tools must be installed and available on the machine before proceeding with deletion:

• tofu (OpenTofu)
• kubectl (configured with cluster context)
• aws CLI
• helm

Cleaning up the EKS Resources

There are two ways to destroy all created resources, including the EKS cluster and related components.

Method 1: Using the bootstrap script

From the folder where bootstrap script is present, run the following command:

./bootstrap.sh --cloud aws destroy

Method 2: Using OpenTofu to delete all modules

This method displays how to delete a PPC cluster on AWS by destroying the OpenTofu modules in reverse order. Destroying modules one at a time gives full control and visibility over each stage.

Warning: This process is irreversible. All cluster resources, data, and backups stored in the S3 bucket will be permanently deleted.

The modules are located at:

~/iac/aws/cluster/modules/
├── 00_backup_bucket
├── 01_iam_roles
├── 02_eks_cluster
├── 03_node_group
├── 04_eks_addons
└── 05_helm_releases

These modules must be destroyed in reverse order: 05 → 04 → 03 → 02 → 01 → 00.

To delete the modules, perform the following steps:

1. To delete the helm releases resource, perform the following steps:

# Navigate to 05_helm_releases directory
cd /iac/aws/cluster/modules/05_helm_releases

# Initialize providers
tofu init  

# Delete the helm release
tofu destroy        # type "yes" when prompted

2. To delete the EKS Addons resource, run the following command.

# Navigate to 04_eks_addons directory
cd /iac/aws/cluster/modules/04_eks_addons

# Initialize providers
tofu init  

# Delete the eks addons
tofu destroy        # type "yes" when prompted

3. To delete the Node Group resource, run the following command.

# Navigate to 03_node_group directory
cd /iac/aws/cluster/modules/03_node_group

# Initialize providers
tofu init 

# Delete the node group
tofu destroy        # type "yes" when prompted

4. To delete the EKS Cluster resource, run the following command.

# Navigate to 02_eks_cluster directory
cd /iac/aws/cluster/modules/02_eks_cluster

# Initialize providers
tofu init 

# Delete the eks cluster
tofu destroy        # type "yes" when prompted

5. To delete the IAM Roles resource, run the following command.

# Navigate to 01_iam_roles directory
cd /iac/aws/cluster/modules/01_iam_roles

# Initialize providers
tofu init 

# Delete the iam roles
tofu destroy        # type "yes" when prompted

6. To delete the Backup Bucket (S3 + KMS) resource, perform the following steps.

# 1.Navigate to 00_backup_bucket directory
cd /iac/aws/cluster/modules/00_backup_bucket

# 2. Download the state file from S3 (synced there during install)
aws s3 cp \
  s3://<bucket-name>/infrastructure-manifest/<cluster-name>/states/00_backup_bucket.tfstate \
  ./terraform.tfstate

# 3. Initialize providers
tofu init

# 4. Enable force_destroy on the bucket (updates only the flag)
tofu apply -var="force_destroy_bucket=true"

# 5. Destroy all resources
tofu destroy -var="force_destroy_bucket=true"        # type "yes" when prompted

Note: After destroying all the modules, delete the CloudWatch Logs group created by EKS control plane logging using the following command.

aws logs delete-log-group \
 --log-group-name "/aws/eks/<cluster-name>/cluster" \
 --region <region>

11 - Accessing PPC using a Linux machine

Access to the PPC cluster from a separate Linux machine may be required in the following situations:

• The original jump box used during installation is no longer available or has been decommissioned.
• A different team member or administrator needs cluster access without setting up a new jump box.
• Operational tasks, such as troubleshooting or monitoring, are being performed from a dedicated management machine.
• The organization requires cluster access to be restricted to specific machines for security or compliance reasons.

Before you begin

Ensure that the following prerequisites are met.

• A Linux machine is available and running.
• AWS CLI is installed and configured.
• Kubernetes command-line tool is installed.

Perform the following steps to access PPC using a separate Linux machine.

1. Log in to Linux machine with root credentials.

2. Configure AWS credentials, using the following command.

   aws configure
   

3. Verify that AWS credentials are working, using the following command.

   aws sts get-caller-identity
   

4. If the Kubernetes command-line tool is not available, then install the Kubernetes command-line tool, using the following command.

   kubectl version --client 2>/dev/null || {
    echo "Installing kubectl..."
    curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
    chmod +x kubectl
    sudo mv kubectl /usr/local/bin/
    kubectl version --client
   }
   

5. Set up the Kubernetes command-line tool and access the cluster, using the following command.

   aws eks update-kubeconfig --region <region_name> --name <cluster_name>
   

6. Verify the access to the cluster, using the following command.

   kubectl get nodes
   

12 - Restoring the SSH keys and PCT from backed up Terraform state file

This section describes the procedure to rebuild a usable PPC v1.1.0 deployment workspace on a jump box from an existing cluster and a backed up Terraform state file.

Before you Begin

Ensure the following requirements are met.

• The state file from all the following modules must be available on the AWS S3 backup bucket.

  • 00_backup_bucket
  • 01_iam_roles
  • 02_eks_cluster
  • 03_node_group
  • 04_eks_addons
  • 05_helm_releases

• Access to the same AWS account and target EKS cluster.

• AWS CLI credentials with required permissions.

Perform the following steps to recover PPC

1. Create a workspace.

   To create a working directory for PCT, run the following command.

   mkdir -p deployment
   cd deployment
   

2. Download and extract the PCT

   Download the PCT package into the deployment directory and extract it.
   For more information about downloading and extracting the PCT, refer to Preparing for PPC deployment.

   After successfully extracting the template, this directory behaves as recovered installation workspace.

3. Install required dev tools

   Run the following script.

   cd bootstrap-scripts/
   ./setup-devtools-aws.sh
   

4. Set kubectl to the target EKS cluster

   To set kubectl to the target EKS cluster, run the following command.

   aws eks update-kubeconfig --region <aws-region> --name <cluster-name>
   

   Example:

   aws eks update-kubeconfig --region us-east-1 --name <cluster-name>
   

   Verify the current cluster

   Before proceeding, verify the context and cluster connectivity. Run the following command.

   kubectl config current-context
   

5. Initialize OpenTofu

   To initialize OpenTofu for the cluster module, run the following command,

   cd deployment/iac/aws/cluster/modules/05_helm_releases
   tofu init
   

6. Generate the SSH key for CLI access

   To generate the SSH key for CLI access

   tofu output -raw user_svc_private_key > ~/.ssh/user_svc.pem
   chmod 600 ~/.ssh/user_svc.pem