Deploy on AWS

Use Terraform to prepare Amazon RDS for PostgreSQL, Amazon S3, and a workload identity for PIG on your existing EKS cluster. Then bootstrap PIG with Helm. Terraform continues to own cloud infrastructure; PIG maintains its application releases.

Before you begin

Complete deployment planning, including your Promptless registration, Instruction Hub, and model access.
Have Terraform, Git, the AWS CLI, Helm, and kubectl available. Use the tool versions required by the selected infrastructure release.
Prepare an existing VPC, private database subnets across the availability zones required by RDS, and the security group used by your EKS workloads. Enable an IAM OIDC provider for the cluster so the analyzer can assume its dedicated IAM role.
Have permission to provision the dedicated database, trace storage, and workload identity in that network.
Choose database capacity, availability, backup retention, trace retention, and encryption settings for your recovery requirements.

This guide reuses your cluster and network. It does not create a new cluster or install an ingress controller. Use your existing secret-delivery and certificate-management systems.

1. Get the versioned Terraform example

Choose a release from PIG deployment releases, then check out that exact tag:

PIG_INFRA_RELEASE='vREPLACE_WITH_RELEASE'
git clone --branch "$PIG_INFRA_RELEASE" --depth 1 \
  https://github.com/Promptless/pig-deploy.git
cd pig-deploy/examples/aws

The example pins the cloud module to the same release and declares its Terraform and provider requirements. Preserve the module pin and commit the provider lock file generated by terraform init to your infrastructure repository. Infrastructure module versions and PIG application versions are independent.

2. Configure and apply infrastructure

Confirm your account and cluster.

aws sts get-caller-identity
kubectl config current-context

Copy the example inputs.
Terminal window
```
cp terraform.tfvars.example terraform.tfvars
```
Set the AWS region, EKS cluster name and OIDC provider, VPC and database subnet IDs, and the analyzer workload security group. Use namespace pig, ServiceAccount pig-analyzer, database pig, and a dedicated trace prefix such as acme/traces.

Review database sizing, availability, backup retention, storage recovery, and deletion protection explicitly. Use private database access and private trace storage. Supply database credentials through your approved secrets workflow; keep secret values out of committed .tfvars files.
Initialize and review the plan. Configure an encrypted remote state backend with access control and locking using your platform’s Terraform workflow before applying.
Terminal window
```
terraform init
terraform validate
terraform plan -out=pig.tfplan
```
Review the dedicated database, storage, identity, and network bindings. Stop if the plan replaces your cluster, expands shared permissions, or destroys retained storage unexpectedly. Terraform state and saved plans can contain credentials; store them as secrets even when an output is marked sensitive.
Apply the reviewed plan.
Terminal window
```
terraform apply pig.tfplan
terraform output -json deployment_configuration > deployment-configuration.json
```
Keep this output for the Helm configuration. It contains database connection metadata, the native storage block, ServiceAccount annotations, and any required pod labels. It contains no credential values. Deliver the database DSN through your secret manager and install the provider’s CA bundle separately.

3. Connect the infrastructure to PIG

Use the module’s deployment_configuration output as the source of truth. It maps into the common installation as follows:

Output	Destination
`postgres` connection metadata	The DSN in `pig-credentials/postgres-dsn`, with provider-appropriate TLS verification.
`storage`	The single native object-storage block under `PIGDeployment.spec.storage`.
`service_account_annotations`	Annotations on ServiceAccount `pig/pig-analyzer`.
`pod_labels`	`PIGDeployment.spec.podLabels`.

For AWS, the ServiceAccount annotation is eks.amazonaws.com/role-arn. Its value resembles arn:aws:iam::123456789012:role/acme-pig-analyzer. Use the output’s actual identity; do not copy the illustrative value.

The role needs object access only to this deployment’s trace prefix, plus bucket metadata and encryption-key access required by the configuration. Keep RDS sizing, backup settings, and IAM changes in Terraform.

Use the provisioned bucket and prefix in the common Helm example:

s3:
  region: us-west-2
  bucket: REPLACE_TRACE_BUCKET
  prefix: acme/traces

The model is a separate choice. Select a supported endpoint from model providers; the storage backend does not select or provision it.

4. Bootstrap and verify

Continue with Install with Helm. Apply the ServiceAccount annotations, pod labels, native storage block, and database Secret from this guide before creating the PIGDeployment.

Keep the Helm bootstrap outside Terraform reconciliation. Do not add a helm_release resource for the self-updating supervisor or import its generated workloads into Terraform.

Finish with Verify your deployment. Confirm native storage writes and reads, a successful analysis, and visible Promptless Dashboard status for one exact session.

Maintain the infrastructure

Use Terraform for database resizing, IAM changes, networking, backup policy, and object retention. Review infrastructure module upgrades as separate plans; PIG’s stable application channel does not upgrade your Terraform modules.

If PIG reports a blocked release that requires an infrastructure change, apply that change through Terraform. PIG resumes once its live checks and any required release-specific confirmations pass. Keep backups and trace retention coordinated, and follow recovery guidance before replacing storage.

For cloud-specific identity setup, see IAM roles for service accounts.