In-cluster deployment

This section is intended for users who already have an EKS cluster provisioned and managed outside of the PPC installer. In a standard PPC installation, the installer provisions the EKS cluster and the required AWS resources. In an in-cluster deployment, however, the user creates the cluster. It already exists before the PPC installation begins. Cluster information must be provided to deploy PPC onto the existing EKS cluster. Unlike the automated script-based installation or the manual component-based installation, the installer does not create these AWS resources. They must already exist before you begin.

Complete the infrastructure prerequisites outside the PPC installer first. Then use the PPC installer to deploy the PPC application Helm charts to the existing EKS cluster.

Deploying PPC using In-Cluster Deployment for EKS

To install PPC, complete the following steps in order. Each step is described in detail in the sections below.

Before you begin

Ensure the following prerequisites are met before starting the installation.

Access and permissions

The following access and permissions are required for deploying PPC.

Values needed for terraform.tfvars

The values required to populate terraform.tfvars in are collected from two sources:

Values decided by user

These are existing or user-determined values that are available before prerequisite creation begins:

Values captured from created resources

These values are generated when creating the resources listed in the Cluster requirements for PPC deployment section. Record each value as you create the corresponding resource:

Cluster requirements for PPC deployment

Your EKS cluster is already in place. Before running tofu apply in 05_helm_releases, use this checklist. It confirms that the cluster meets all the requirements PPC deployment expects.

Note: If you are unsure whether a requirement is met, work through each item. Verify each item against your cluster configuration before running tofu apply.

IAM - roles and policies

EKS cluster and access

Compute: system node group

Networking

Add-on scheduling (required after tainted system node group exists)

Storage and backup

System node group taint value

Ensure that the CriticalAddonsOnly=true:NoSchedule taint is applied when creating the system node group. Apply it together with the role=system label. This taint prevents application workloads from being scheduled on the system nodes. It is required for the Add-on scheduling configuration.

Deploying PPC

To deploy PPC onto the existing EKS cluster, perform the following steps:

1. Preparing a jump box

Create a jump box or use an existing one that has network access to the EKS cluster. The jump box must be able to access the Kubernetes API server endpoint.

2. Downloading and extracting the release archive

To download and extract the PCT, refer to Preparing for PPC deployment.

3. Installing required tools

To install the required tools from the extracted release bundle, run the following command:

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

The script installs the following tools:

4. Configuring AWS credentials

Configure your AWS credentials so that CLI commands authenticate as your deployer identity. Either run aws configure to set up a named profile, or export the credentials directly.

Note: AWS SSO web-based login is not supported. However, AWS IAM Identity Center temporary credentials can be exported as environment variables.

Export IAM user credentials, temporary STS credentials, or AWS IAM Identity Center temporary credentials. Include the session token, as shown below:

export AWS_ACCESS_KEY_ID="<ACCESS_KEY_ID>"
export AWS_SECRET_ACCESS_KEY="<SECRET_ACCESS_KEY>"
export AWS_SESSION_TOKEN="<SESSION_TOKEN>"
export AWS_DEFAULT_REGION="<REGION>"

Note: The AWS_SESSION_TOKEN variable is required only when using temporary credentials, such as the STS or AWS IAM Identity Center. Omit it when using long-term IAM user credentials.

To verify that the credentials are working, run the following command:

aws sts get-caller-identity

5. Configuring EKS access

To retrieve the EKS credentials and configure kubectl to communicate with the cluster, run the following command:

aws eks update-kubeconfig --name <CLUSTER_NAME> --region <REGION>

6. Verifying cluster connectivity

To confirm that the jump box can reach the cluster API, run the following commands:

kubectl get pods -A
kubectl get nodes

All nodes should be listed and in Ready state before proceeding.

7. Gathering values for terraform.tfvars

Complete each of the following sub-steps to populate terraform.tfvars with the required cluster-specific values.

7.1 Storage class

Record the name of the storage class to use and update storage_class_name in terraform.tfvars.

kubectl get sc -A

Record the name of the storage class. Update only storage_class_name in terraform.tfvars with this value. Leave backup_storage_class_name set to its default value, pty-bkp, which is created by Stage 05.

Note: Create a custom storage class named pty-sc. Use the following properties: gp3 volume type, Retain reclaim policy, and WaitForFirstConsumer binding mode. Then set storage_class_name=pty-sc in terraform.tfvars. For a quick bring-up, the console’s default gp2 storage class may be used instead. Do not modify backup_storage_class_name, leave it as pty-bkp.

7.2 Registry credentials

When using an authenticated private registry, set harbor_secret to harbor-secret in terraform.tfvars. Also export the container registry credentials before running tofu apply. Otherwise, the apply fails while pulling PPC images and charts. Leave harbor_secret empty for an unauthenticated registry.

export TF_VAR_username="<REGISTRY-USERNAME>"
export TF_VAR_password="<REGISTRY-PASSWORD>"

Note: Registry credentials TF_VAR_username and TF_VAR_password are passed as environment variables and are not set directly in terraform.tfvars.

7.3 Add-on scheduling configuration

After the tainted system node group is active, apply the scheduling configuration to the four Deployment-based add-ons. This lets their pods land on system nodes. Set CLUSTER_NAME and REGION, then run the following commands:

export CLUSTER_NAME=<CLUSTER-NAME>
export REGION=<REGION>

# CoreDNS
aws eks update-addon \
  --cluster-name "$CLUSTER_NAME" \
  --addon-name coredns \
  --region "$REGION" \
  --resolve-conflicts OVERWRITE \
  --configuration-values '{"tolerations":[{"key":"CriticalAddonsOnly","operator":"Exists","effect":"NoSchedule"}],"affinity":{"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"role","operator":"In","values":["system"]}]}]}}}}'

# Amazon EBS CSI Driver (controller only)
aws eks update-addon \
  --cluster-name "$CLUSTER_NAME" \
  --addon-name aws-ebs-csi-driver \
  --region "$REGION" \
  --resolve-conflicts OVERWRITE \
  --configuration-values '{"controller":{"tolerations":[{"key":"CriticalAddonsOnly","operator":"Exists","effect":"NoSchedule"}],"affinity":{"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"role","operator":"In","values":["system"]}]}]}}}}}'

# metrics-server
aws eks update-addon \
  --cluster-name "$CLUSTER_NAME" \
  --addon-name metrics-server \
  --region "$REGION" \
  --resolve-conflicts OVERWRITE \
  --configuration-values '{"tolerations":[{"key":"CriticalAddonsOnly","operator":"Exists","effect":"NoSchedule"}],"affinity":{"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"role","operator":"In","values":["system"]}]}]}}}}'

# snapshot-controller
aws eks update-addon \
  --cluster-name "$CLUSTER_NAME" \
  --addon-name snapshot-controller \
  --region "$REGION" \
  --resolve-conflicts OVERWRITE \
  --configuration-values '{"tolerations":[{"key":"CriticalAddonsOnly","operator":"Exists","effect":"NoSchedule"}],"affinity":{"nodeAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":{"nodeSelectorTerms":[{"matchExpressions":[{"key":"role","operator":"In","values":["system"]}]}]}}}}'

To verify the add-on status after the updates complete, run the following commands:

for addon in coredns aws-ebs-csi-driver metrics-server snapshot-controller; do
  aws eks describe-addon \
    --cluster-name "$CLUSTER_NAME" \
    --addon-name "$addon" \
    --region "$REGION" \
    --query 'addon.[addonName,status]' \
    --output text
done

Expected: all four add-ons report ACTIVE. If an update is still in progress, wait for it to complete. Then run the verification again.

8. Updating terraform.tfvars

To update the terraform.tfvars file, perform the following steps:

1. Navigate to the Helm releases module directory.

cd iac/aws/cluster/modules/05_helm_releases

2. After completing Steps 7.1 through 7.3, set the following variables in 05_helm_releases/terraform.tfvars.

Note: Registry credentials are passed as environment variables (TF_VAR_username and TF_VAR_password). They are configured in Step 7.2. They are not set directly in terraform.tfvars. Leave backup_storage_class_name at its default value, pty-bkp, unless the deployment requires a different value.

3. Add the following variables to terraform.tfvars. Set each to the value shown before allowing Stage 05 to apply.

run_readiness_check = true
check_prev_stage    = false

These variables ensure that PPC performs a readiness check on the existing EKS environment. They skip the previous automated stage validation. That validation is not required because those resources were created outside the installer.

4. Save the file and exit the editor.

9. Running the readiness check

The readiness check verifies that the cluster is ready for the Stage 05 (Helm Releases) tofu apply. The same check runs automatically as a guard at the start of the Stage 05 apply. It runs because run_readiness_check is enabled in the terraform.tfvars file. If required prerequisites are missing, the apply stops before deploying any components.

Run the check independently now to identify and resolve any issues before starting the apply.

To run the readiness check, run the following command:

./bootstrap-scripts/readiness-helm-aws.sh

The script validates that all required EKS add-ons are ACTIVE. It also checks that the worker security group and subnet tags are present. It checks that Pod Identity associations exist, and that the backup bucket and KMS key are accessible.

Note: The readiness check is read-only and does not modify the cluster. Run it as often as needed, including after correcting reported errors. Repeat it until it completes successfully before proceeding to apply the OpenTofu configuration.

10. Applying the OpenTofu configuration

To deploy all PPC Helm charts onto the cluster, initialize and apply the OpenTofu configuration. Perform the following steps:

1. Navigate to the Helm releases module directory.

cd iac/aws/cluster/modules/05_helm_releases

Important: Before running tofu plan or tofu apply, review all values in terraform.tfvars. Confirm that they match your target environment.

2. To initialize, plan, and apply the OpenTofu configuration, run the following commands. They deploy all PPC Helm charts onto the cluster.

tofu init
tofu plan          # Review the planned resources that will be created.
tofu apply         # When prompted with "Enter a value:", type "yes".

3. To verify the resources created in this stage, run the following commands:

# Confirm nodes are Ready
kubectl get nodes

# Confirm pods are Running
kubectl get pods -A

11. Common misconfigurations in In-Cluster Deployment for EKS

When Stages 00–04 are created manually using the console or CLI, this repo’s OpenTofu does not create them. Every IAM role, policy, tag, and rule must match the exact names and permissions Stage 05 expects. These are the issues that break the install: