Deploying PPC

• 1: Configuring PPC for Non-FIPS Deployment on AWS
• 2: Automated script-based installation
• 3: Manual component-based installation

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.

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