Architecture
The diagram below shows the architecture of the TrueFoundry compute plane.
Access Policies
The compute plane requires the following IAM policies to operate. These are created automatically during platform deployment.Required IAM policies
Required IAM policies
Requirements
Common requirements for setting up the compute plane:- Billing and STS must be enabled for the AWS account.
- Egress access to container registries —
public.ecr.aws,quay.io,ghcr.io,tfy.jfrog.io,docker.io/natsio,nvcr.io,registry.k8s.io— to pull images for ArgoCD, NATS, GPU Operator, Argo Rollouts, Argo Workflows, Istio, and Keda. - A domain mapped to the service endpoints, plus a certificate to encrypt traffic. A wildcard domain such as
*.services.example.comis preferred. TrueFoundry supports path-based routing (e.g.services.example.com/tfy/*), but many frontend applications do not. Create the certificate for your domain in AWS Certificate Manager (ACM) and keep the ARN ready (covered in the Get Domain and Certificate ARN step below). - Sufficient CPU/GPU/Inferentia quotas for your use case. Check and increase them at AWS EC2 service quotas.
- Sufficient permissions on the AWS account to create the compute-plane resources. See Permissions required to create the infrastructure for details.
Permissions required to create the infrastructure
Admin permission on the AWS account is the simplest. For the exact least-privilege set, the policy below is the base cluster policy plus the compute-plane (blob storage) delta. Substitute$REGION, $ACCOUNT_ID, and $CLUSTER_NAME with your values before attaching.
- New VPC and New EKS Cluster
- Existing VPC and New EKS Cluster
- Existing EKS Cluster
- The new VPC will have a CIDR range of /20 or larger, at least 2 availability zones, and private subnets with CIDR range of /24 or larger. This ensures capacity for ~250 instances and 4096 pods.
- If you are using custom networking, you need a CGNAT IP address in each AZ. CGNAT space and route tables will be set up in the VPC.
- A NAT gateway will be provisioned to provide internet access to the private subnets.
Setting up compute plane
TrueFoundry compute plane infrastructure is provisioned using OpenTofu/Terraform. You can download the OpenTofu/Terraform code for your exact account by filling up your account details and downloading a script that can be executed on your local machine.Enable Deployment Feature in the Platform (Optional)
- In the left hand navigation, go to
SettingsthenPlatform Feature VisibilityunderPreferences - Click on
Editbutton. Then enable the toggle forEnable Deployment

- Click on
Savebutton.

Choose to create a new cluster or attach an existing cluster
Clusters. You can click on Create New Cluster or Attach Existing Cluster depending on your use case. Read the requirements and if everything is satisfied, click on Continue.
Get Domain and Certificate ARN
*.services.example.com, you will create a DNS record for it later in Step 6. We recommend using AWS Certificate Manager (ACM) to create the certificate, since it manages and renews certificates automatically. To generate a certificate ARN, follow the steps below. If you are not using AWS Certificate Manager, skip this step and continue to the next one.Create the certificate in AWS Certificate Manager
Create the certificate in AWS Certificate Manager
- Navigate to AWS Certificate Manager in the AWS console.
- Request a public certificate.
- Specify your domain (e.g.
*.services.example.com). - Choose DNS validation (recommended).
- Add the CNAME records provided by ACM to your DNS provider. Follow the official AWS guide for DNS validation. For detailed steps on adding CNAME records, see the AWS documentation on DNS validation.
- Wait for the certificate to change to “Active” status (this may take 30 minutes or longer).
- Copy the certificate ARN for the next step (the format will be like
arn:aws:acm:region:account:certificate/certificate-id).
Fill up the form to generate the OpenTofu/Terraform code
Submit when done.- Create New Cluster
- Attach Existing Cluster
Cluster Name- A name for your cluster.Region- The region where you want to create the cluster.Network Configuration- Choose betweenNew VPCorExisting VPCdepending on your use case.Authentication- This is how you are authenticated to AWS on your local machine. It’s used to configure OpenTofu/Terraform to authenticate with AWS.S3 Bucket for OpenTofu/Terraform State- OpenTofu/Terraform state will be stored in this bucket. It can be a preexisting bucket or a new bucket name. The new bucket will automatically be created by our script.Load Balancer Configuration- This is to configure the load balancer for your cluster. You can choose betweenPublicorPrivateLoad Balancer, it defaults toPublic. You can also add certificate ARNs and domain names for the load balancer but these are optional.Platform Features- This is to decide which features like Blob Storage, Cluster Integration, Parameter Store, Docker Registry, and Secrets Manager will be enabled for your cluster. To read more on how these integrations are used in the platform, please refer to the platform features page.

Copy the curl command and execute it on your local machine
curl command to download and execute the script. The script will take care of installing the prerequisites, downloading OpenTofu/Terraform code, and running it on your local machine to create the cluster. This will take around 40-50 minutes to complete.
Verify the cluster is showing as connected in the platform
Create DNS Record
Base Domain URL section.
Start deploying workloads to your cluster
FAQ
How do I tag all the AWS resources (cost-center, environment, team, etc.)?
How do I tag all the AWS resources (cost-center, environment, team, etc.)?
tags variable in the generated OpenTofu/Terraform code to a map of your tags:tofu plan (or terraform plan) first and confirm the diff is tag-only before applying.How tagging works across all resources
Tags flow through three layers so every AWS resource — whether managed by Terraform or launched at runtime — gets consistent labels:Suppressing built-in TrueFoundry audit tags
By default, TrueFoundry modules addtruefoundry-managed, truefoundry-cluster-name, and truefoundry-terraform-module tags. To suppress these without affecting your own tags or the provider default_tags, set:Can I use cert-manager to add TLS to the load balancer and not use AWS Certificate Manager?
Can I use cert-manager to add TLS to the load balancer and not use AWS Certificate Manager?
Can I use my own certificate and key files to add TLS to the load balancer?
Can I use my own certificate and key files to add TLS to the load balancer?
-
Create a Kubernetes secret with your certificate and key, or create a self-signed certificate:
-
Once the secret is created, head over to the cluster page and navigate to the
tfy-istio-ingressadd-on. Add the secret name in thetfyGateway.spec.servers[1].tls.credentialNamesection and ensure thattfyGateway.spec.servers[1].port.protocolis set toHTTPS. Here we are usingexample-com-tlsas the secret name, which contains the certificate and key.
How to review the OpenTofu/Terraform code that is generated by the platform?
How to review the OpenTofu/Terraform code that is generated by the platform?
How do I set up custom networking in EKS?
How do I set up custom networking in EKS?
-
Attach a secondary CIDR to the VPC (e.g.
100.64.0.0/16per RFC 6598) and create new subnets with that CIDR in the same AZs as your primary subnets. - Ensure the secondary subnets are added to the route tables of your primary subnets (this typically happens automatically).
- Configure the AWS VPC CNI to use the secondary subnets. If you used TrueFoundry’s OpenTofu/Terraform code, add this to the EKS module:
- Create an
ENIConfigresource for each AZ where your EKS nodes run:
- Restart the nodes one by one to apply the changes. Pods will be rescheduled onto nodes with secondary IP addresses.
How to remove all AWS resources created with Terraform/OpenTofu?
How to remove all AWS resources created with Terraform/OpenTofu?
Connect to the EKS cluster
Delete LoadBalancer services
Delete Karpenter NodePools
From the folder with your generated OpenTofu/Terraform code
How to fix S3 'PutBucketPublicAccessBlock' AccessDenied error while running terraform/tofu apply?
How to fix S3 'PutBucketPublicAccessBlock' AccessDenied error while running terraform/tofu apply?
terraform apply (or tofu apply) fails with an error like:s3:PutBucketPublicAccessBlock, but the TrueFoundry module tries to set it on each bucket — so the call is denied and the apply fails.The fix: Set the variable below to false so the module skips this step. This is safe — your account already blocks public access, so the per-bucket setting is redundant.Control plane — add truefoundry_s3_attach_public_policy = false to the tfy-control-plane module:blob_storage_attach_public_policy = false to the tfy-platform-features module:true, so you must set them explicitly to false. Then re-run terraform apply (or tofu apply).Istio Ingress service stuck in pending state due to missing AWSServiceRoleForElasticLoadBalancing role
Istio Ingress service stuck in pending state due to missing AWSServiceRoleForElasticLoadBalancing role
Pending state and fail to receive an external IP when the AWS account is missing the Elastic Load Balancing service-linked role and the AWS Load Balancer Controller cannot create it.FailedDeployModel warning:Root Cause
The AWS account did not contain the required service-linked role:AWSServiceRoleForElasticLoadBalancing.When AWS Load Balancer Controller attempted to create a Network Load Balancer (NLB) for the Istio ingress Service, AWS tried to automatically create this service-linked role. The controller was running with an IAM role that was restricted by a permissions boundary, which prevented execution of iam:CreateServiceLinkedRole. As a result, AWS rejected the load balancer creation request and the Kubernetes Service remained in the Pending state.Verification
Verify whether the service-linked role exists:NoSuchEntity, the service-linked role is missing.Resolution
Create the AWS service-linked role
iam:CreateServiceLinkedRole permission to provision load balancers.Confirm the Service receives an external endpoint
EXTERNAL-IP column should show the NLB hostname instead of <pending>.How do I enable autoscaling for the CoreDNS addon in EKS?
How do I enable autoscaling for the CoreDNS addon in EKS?
cluster_addons_coredns_additional_configurations block to the EKS module:enabled— turns on CoreDNS autoscaling.minReplicas/maxReplicas— lower and upper bounds for the replica count. Tune these values based on your cluster size and DNS query volume.
terraform apply (or tofu apply) to apply the change.