Deploy on AWS

Overview

Use this guide to run PIG on an existing Amazon EKS cluster and have Terraform create its dedicated infrastructure. The Terraform example creates an Amazon RDS for PostgreSQL database, an Amazon S3 trace bucket, and an IAM role for the analyzer’s workload identity. You then continue with the common Helm installation. If you already have these resources, go directly to that guide.

The guide reuses your cluster and network. It creates no cluster and installs no ingress controller, and it works with your existing secret-delivery and certificate-management systems. After installation, Terraform keeps ownership of the cloud infrastructure, and PIG maintains its own application releases.

Before you begin

Complete deployment planning, including your Promptless registration, Instruction Hub, and model access.
Have Terraform 1.11 or later, the AWS CLI, Helm, kubectl, and jq. The 0.3.6 example requires Terraform >= 1.11.0, < 2.0.0.
Prepare an existing EKS cluster running Kubernetes 1.30 or later and its IAM OIDC provider. In its VPC, prepare two private database subnets in different availability zones and the security group used by analyzer pods. The analyzer reaches S3 through a gateway endpoint or approved egress.
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.

To hand the infrastructure work to a coding agent, copy this prompt. Set up PIG with a coding agent covers the whole setup.

Prepare AWS infrastructure for the PIG trace analyzer on our existing
EKS cluster with the versioned Terraform example. Follow
https://promptless.ai/docs/governance/deploy-the-worker/deploy-on-aws.md
and phase 5 of https://promptless.ai/docs/governance/agent-setup-guide.md

Outcome: an applied Terraform plan and the saved deployment_configuration
output.
Inputs (discover these before you ask me):
- AWS account and region: [for example, 123456789012, us-west-2]
- EKS cluster: [cluster name and kubectl context]
- VPC, database subnets, and workload security group: [IDs, or "discover them"]
- PIG release: [for example, 0.3.6 from the stable catalog]
- Terraform state backend: [our backend, or where our Terraform lives]

Show me the plan summary and wait for my approval before `terraform apply`.
Report the resources created and the next step.

1. Get the versioned Terraform example

Download and verify the release files as described in Select and verify a release. In the same shell, from that release directory, extract the Terraform example from the verified archive:

cd "$PIG_RELEASE_DIR"
tar -xzf "pig-deploy-${PIG_VERSION}.tar.gz"
cd "pig-deploy-${PIG_VERSION}/examples/aws"

The example references the AWS module in the same archive, so the module matches the release. The example also includes its provider lock file. Keep -lockfile=readonly in the commands below so Terraform uses those reviewed provider checksums.

To call the module from your own Terraform root instead, use git::https://github.com/Promptless/pig-deploy.git//modules/aws?ref=db79db5a2c8a0e882bc888a870d6b407e5d5e76e, the 0.3.6 source commit, and commit your own lock file.

2. Configure and apply infrastructure

Confirm your account and cluster.

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

Configure remote state. Use an existing private, versioned S3 bucket with encryption, and limit access to infrastructure operators. Terraform state stores the database password, so treat state and saved plans as secrets.
Terminal window
```
cp backend.tfbackend.example backend.tfbackend
```
Set bucket, key, region, and kms_key_id. The example enables encryption and S3 lock files (use_lockfile = true), so operators need permission to write the lock object as well as the state.
Set the example inputs.
Terminal window
```
cp terraform.tfvars.example terraform.tfvars
```
Set name, region, eks_cluster_name, oidc_provider_arn, vpc_id, two private database_subnet_ids in different availability zones, the analyzer’s workload_security_group_id, and a globally unique trace_bucket_name. Keep namespace = "pig" and service_account_name = "pig-analyzer", which the module binds to the analyzer role, and set a dedicated trace_prefix such as acme/traces.

The defaults create private PostgreSQL 16 on db.t4g.medium with Multi-AZ and deletion protection. Storage starts at 100 GiB and can grow to 200 GiB, with 14 days of backups. The bucket is versioned with 90 days of noncurrent-object recovery. Review these defaults in variables.tf against your workload and recovery requirements. Keep real .tfvars files out of Git.
Supply the database password from your secret manager, without writing it to a file:
Terminal window
```
export TF_VAR_postgres_password="$(your-secret-manager-command)"
```
Initialize and review the plan.
Terminal window
```
terraform init -backend-config=backend.tfbackend -lockfile=readonly
terraform validate
terraform plan -out=pig.tfplan
```
Review the database, bucket, IAM role, and security group rule. The analyzer role gets object read and write access under the trace prefix and, when you set kms_key_arn, use of that key. It gets no RDS or infrastructure permissions. Stop if the plan replaces existing resources, expands shared permissions, or destroys retained storage.
Apply the reviewed plan and save its output.
Terminal window
```
terraform apply pig.tfplan
terraform output -json deployment_configuration > "$PIG_RELEASE_DIR/deployment-configuration.json"
```
The output file sits next to the verified release files. It contains database connection metadata, the S3 storage block, the ServiceAccount annotation, and pod labels. It contains no credential values.

3. Connect the infrastructure to PIG

Return to the release directory. The deployment-configuration.json file there is the source of truth for the Kubernetes configuration in Install with Helm. Each output goes to one destination:

Output	Destination
`postgres`	The application connection string in `pig-credentials/postgres-dsn`.
`storage.s3`	The `s3` block under `PIGDeployment.spec.storage`.
`service_account_annotations`	Annotations on ServiceAccount `pig/pig-analyzer`, such as `eks.amazonaws.com/role-arn`.
`pod_labels`	`PIGDeployment.spec.podLabels`. It is empty on AWS.

Read the connection metadata and storage block:

cd "$PIG_RELEASE_DIR"
jq '.postgres | {host, port, database, username, sslmode}' deployment-configuration.json
jq '.storage' deployment-configuration.json

Build the connection string in your secret manager from those values and the database password, with sslmode=verify-full:

postgresql://USERNAME:URL_ENCODED_PASSWORD@HOST:5432/pig?sslmode=verify-full

Download the RDS CA bundle for your database’s region and deliver it as ConfigMap pig-postgres-ca with key ca.pem. The analyzer uses it to verify the RDS certificate and hostname. It rejects a connection string whose sslmode is anything other than verify-full, including require. To give the serving analyzer a role without schema ownership, see Separate the migration credential.

Choose the model separately. Select a supported endpoint from model providers. The Terraform module grants no model access, so to use Bedrock with aws_sigv4, grant the analyzer role access to the model through your own IAM change.

4. Prepare HTTPS ingress

Install the AWS Load Balancer Controller with its own IAM role, and request an ACM certificate for the analyzer hostname in the cluster’s region. The PIG Terraform module does not create these resources.

Use the AWS Application Load Balancer values in Bootstrap the supervisor and collector Ingress:

watchNamespace: pig
ingress:
  serviceName: acme-analyzer # Your PIGDeployment name plus -analyzer
  hostname: traces.acme.example
  ingressClassName: alb
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/certificate-arn: REPLACE_ACM_CERTIFICATE_ARN
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/healthcheck-path: /healthz

Omit tlsSecretName: the ALB uses the ACM certificate. Choose scheme: internal only when every enrolled host and cloud runner can reach the private endpoint. Claude Tag needs an internet-facing endpoint.

After the analyzer starts and the ALB’s targets are healthy, point the hostname’s DNS record at the ALB. Check HTTPS from the hosts’ network as described in Point DNS at the Ingress.

5. Bootstrap and verify

In $PIG_RELEASE_DIR, where the verified chart and deployment-configuration.json are, continue with Install with Helm from step 2. Apply the ServiceAccount annotation, Secrets, CA ConfigMap, and S3 storage block from this guide before you create the PIGDeployment.

Keep the Helm bootstrap outside Terraform reconciliation. Terraform must not manage the self-updating supervisor through a helm_release resource or import its generated workloads.

Finish with Verify your deployment for one real session.

Maintain the infrastructure

Use Terraform for database resizing, IAM changes, networking, backup policy, and object retention. PIG’s stable application channel updates only the application, so review each Terraform module upgrade as its own plan.

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.