Amazon Web Services

Ensure all of the following are configured in your AWS account before linking it to Onehouse.

Networking

VPC

Create a VPC with a /16 CIDR block (e.g. 10.0.0.0/16) and DNS support enabled. A /16 provides ample headroom as the cluster scales; size up only if your estimated OCU allocation and networking model call for more (see Pod networking and IP consumption below).

Subnets

Type	Count	Size	Purpose
Private	At least 2, across two AZs	/20 each (~4,096 IPs)	EKS nodes and pods run here
Public	At least 2, across two AZs	/24 each is sufficient	Only the NAT Gateway and load balancers — no workload IPs required

Pod networking and IP consumption

Onehouse supports two pod-networking models on AWS. Your choice determines how many VPC IPv4 addresses the cluster consumes:

Option	How pods get IPs	VPC IP consumption	When to choose
AWS VPC CNI — no overlay (default)	Each pod receives an IP directly from your VPC subnet	Scales with pod count — size subnets with headroom	Standard EKS behavior; simplest and consistent with existing AWS/EKS fleets
Calico — overlay	Pods receive virtual IPs from an internal overlay network; only the EC2 nodes draw IPs from your VPC subnet	Scales with node count — consumes far fewer VPC IPs	Best when VPC IPv4 space is constrained

Sizing

The /16 VPC and /20 private subnets above are a sound baseline for most deployments. For large-scale or IP-constrained workloads, size based on your estimated OCU (Onehouse Compute Unit) allocation and your chosen networking model — with Calico overlay, VPC IP consumption scales with node count rather than pod count, so a tighter allocation is viable. Reach out to your Onehouse account team to estimate the OCUs — and the resulting IP capacity — for your workload.

caution

EKS subnets must span at least two Availability Zones. Once the cluster is provisioned, you cannot add subnets in a new AZ — only within the AZs selected at onboarding time.

Internet Gateway

Attach an Internet Gateway to your VPC. The public subnets route through this gateway for NAT Gateway egress.

NAT Gateway

Deploy a NAT Gateway in a public subnet. For most deployments a single NAT Gateway is sufficient. For higher fault tolerance, deploy one per AZ.

All outbound traffic from EKS nodes routes through the NAT Gateway to reach the Onehouse control plane over port 443. No inbound ports need to be opened.

See AWS docs.

S3 VPC Gateway Endpoint

Create an S3 VPC Gateway Endpoint so that all EKS-to-S3 traffic stays inside the AWS network and does not route through the NAT Gateway.

This is required for two reasons:

• Cost: NAT Gateway charges per GB. Large data volumes without an S3 endpoint will generate significant NAT costs.
• Performance: S3 traffic over the private endpoint bypasses internet routing entirely.

See AWS docs.

S3 Gateway Endpoint Policy

Add this policy to the endpoint to allow access to container image registries (Docker, Quay, k8s registry) and your Onehouse/lakehouse buckets:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowContainerImageRegistries",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "*",
      "Resource": [
        "arn:aws:s3:::docker-images-prod/*",
        "arn:aws:s3:::prod-<AWS_REGION>-starport-layer-bucket/*",
        "arn:aws:s3:::quayio-production-s3/*",
        "arn:aws:s3:::prod-registry-k8s-io*"
      ]
    },
    {
      "Sid": "AllowOnehouseAndLakehouseBuckets",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::onehouse-customer-bucket-XXXX",
        "arn:aws:s3:::onehouse-customer-bucket-XXXX/*",
        "arn:aws:s3:::<lake-bucket>",
        "arn:aws:s3:::<lake-bucket>/*",
        "arn:aws:s3:::s3-datasource-metadata-<ONEHOUSE_REQUEST_ID>",
        "arn:aws:s3:::s3-datasource-metadata-<ONEHOUSE_REQUEST_ID>/*"
      ]
    }
  ]
}

EKS Cluster Endpoint Access

The EKS cluster API endpoint is private. The Onehouse control plane connects to it from its NAT IPs — you must ensure these are not blocked by your security groups or NACLs:

• 54.153.81.1/32
• 184.169.135.156/32

You cannot kubectl directly to the cluster from outside your VPC. Cluster access for support and diagnostics is provided through the bastion host, deployed into your private subnet and reachable via AWS SSM Session Manager — which is why the bastion host is mandatory.

How bastion access is controlled

The bastion has no inbound ports and no public IP; Onehouse reaches it only through AWS SSM Session Manager — no SSH keys, no RDP. Access uses cross-account IAM role assumption with your request ID enforced as the STS ExternalId, and all SSM sessions are logged to your onehouse-customer-bucket-<RequestIdPrefix>. Onehouse does not open SSH/RDP, store SSH keys, or retain standing access to the host outside supported operations. If your team needs direct access, you can grant SSM permissions to your own IAM roles scoped to the bastion instance.

Egress Mode

Choose one of the following egress configurations:

Public/Private (default)

Outbound traffic from the EKS cluster routes through the NAT Gateway over the public internet to reach the Onehouse control plane. Egress is restricted to approved Onehouse IP ranges. This is the standard configuration for most deployments.

Private Only (PrivateLink)

For environments with strict compliance requirements (no public internet traversal), Onehouse supports AWS PrivateLink. In this mode, all control plane traffic stays within the AWS network — no internet routing is involved.

To enable PrivateLink, set privateLink: true in the customer stack configuration. You must also specify PrivateLink subnets. Onehouse will create:

• Two Interface VPC Endpoints (for control plane ingress and external ingress)
• A Route53 Private Hosted Zone for onehouse.ai DNS resolution within your VPC

VPC Peering

If your data sources (Kafka clusters, databases) live in a separate VPC, configure VPC peering between that VPC and your Onehouse VPC so the EKS cluster can reach them. See AWS docs.

Domain Allowlist

Required only if your environment has an egress firewall. The Required set below is shared across all clouds (image registries, tooling, control plane) plus a small AWS-specific group; the Conditional set is only needed when the corresponding feature or connector is enabled.

Required — allowlist for every AWS deployment

Shared across all clouds (image registries, tooling, control plane):

• .onehouse.ai — control plane APIs, gateway, telemetry, image distribution
• .docker.io — Docker Hub registry
• production.cloudflare.docker.com — Docker Hub blob CDN (Cloudflare)
• production.cloudfront.docker.com — Docker Hub blob CDN (AWS CloudFront)
• docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com
• docker-registry-production.d24a988e385e0074d717b6bdaea58f0d.r2.cloudflarestorage.com
• auth.docker.io.cdn.cloudflare.net
• .cloudfront.net — registry / image blob delivery
• .gcr.io — Google Container Registry image pulls
• .pkg.dev — Google Artifact Registry image pulls
• .googleapis.com — gcr.io / pkg.dev blob storage backend
• .k8s.io — Kubernetes registry (registry.k8s.io)
• ghcr.io — spark-operator and flink-operator images
• .quay.io — Strimzi, Prometheus, and Calico images
• registry.terraform.io — Terraform provider/module registry
• releases.hashicorp.com — Terraform binaries
• get.helm.sh — Helm binary downloads
• github.com — Terraform providers and modules
• .github.com
• .githubusercontent.com
• .github.io
• .strimzi.io — Strimzi Kafka operator
• .pagerduty.com — Onehouse operational alerting

AWS-specific:

• .amazonaws.com — AWS APIs, S3, STS, ECR
• .ecr.aws — Onehouse ECR image pulls (public.ecr.aws)

Conditional — only if the corresponding feature or connector is enabled

• .confluent.cloud — Confluent / Kafka sources
• .jupyter.org — notebooks
• .debezium.io — Debezium CDC connectors
• datadoghq.com — Datadog telemetry (site-specific, e.g. us5.datadoghq.com)
• docker.elastic.co — Elasticsearch images
• docker-auth.elastic.co
• .snowflakecomputing.com — Snowflake source/sink
• .databricks.com — Databricks source/sink
• .splunkcloud.com — Splunk log sink
• .slack.com — Slack notifications
• api.honeycomb.io — Honeycomb telemetry
• .openai.com — AI features
• apachesuperset.docker.scarf.sh — Superset dashboards image

IAM Service Roles

Ensure these AWS-managed service-linked roles exist in your account before deploying. These are standard AWS roles required to create and manage EKS clusters — they are not Onehouse-specific.

Role	Purpose
AWSServiceRoleForAmazonEKS	Allows EKS to manage cluster-level AWS resources
AWSServiceRoleForAmazonEKSNodegroup	Allows EKS to manage node groups and EC2 instances
AWSServiceRoleForAutoScaling	Allows EC2 Auto Scaling to manage instances within the cluster

How to create these roles if they don't exist

• EKS role: IAM → Create role → EKS service → EKS - Service
• EKS Node Group role: IAM → Create role → EKS service → EKS - Nodegroup
• EC2 Auto Scaling role: IAM → Create role → EC2 Auto Scaling service → EC2 Auto Scaling

Storage

Terraform State Bucket

Create an S3 bucket named onehouse-customer-bucket-<RequestIdPrefix> in the same region as your deployment. This bucket stores Terraform state and Onehouse configuration artifacts.

Lakehouse Bucket

Create an S3 bucket for your data lakehouse in the same region as your deployment. Cross-region buckets will incur data transfer costs.

Encryption

By default, S3 SSE encryption is applied automatically and requires no additional setup.

Enable S3 Bucket Keys on any SSE-KMS bucket

If your lakehouse bucket uses SSE-KMS (an AWS-managed or customer-managed KMS key), you must enable S3 Bucket Keys on it.

Onehouse performs frequent metadata operations on your bucket. Without Bucket Keys, S3 makes a separate KMS API call for every object operation, which can lead to a large, unexpected KMS bill. Bucket Keys let S3 cache the data key and cut KMS request costs by up to 99%.

Enable it in S3 → your bucket → Properties → Default encryption → Edit → Bucket Key = Enable. It applies to newly written objects; existing objects re-encrypt as data is rewritten over time.

Buckets using SSE-S3 (AES256) are unaffected — they make no KMS calls.

If your organisation requires KMS customer managed keys:

KMS setup (complete after onboarding)

1. Create a KMS key in AWS KMS.
2. Add onehouse-customer-eks-node-role-XXXX and onehouse-customer-core-role-XXXX as key users. These roles are created during the customer stack deployment.
3. Update the customer stack: set s3KmsKeys to the KMS key ARN(s) and re-apply Terraform.
4. In your S3 bucket → Default encryption → select SSE-KMS → choose your key → enable bucket key.

tip

Enabling the S3 bucket key reduces KMS API request costs by up to 99%.

Service Control Policies (SCPs)

If your AWS organisation enforces Service Control Policies, ensure the following actions are not denied for the Onehouse IAM roles (onehouse-customer-*):

• ec2:* (describe, manage instances, security groups, VPCs — scoped to tagged resources)
• eks:* (create, describe, manage clusters and node groups)
• iam:CreateRole, iam:AttachRolePolicy, iam:PassRole
• s3:GetObject, s3:PutObject, s3:ListBucket (on Onehouse and lakehouse buckets)
• cloudwatch:PutMetricData, logs:CreateLogGroup, logs:PutLogEvents
• sts:AssumeRole (for cross-account access from Onehouse control plane)

If your organisation uses a permissions boundary, set the permissions_boundary variable in the customer stack to the ARN of your boundary policy. All Onehouse IAM roles will be created with this boundary applied.

Custom Tags

If your organisation requires all AWS resources to carry specific tags (for cost allocation, compliance, or access control), set the customTags variable in the customer stack:

customTags = {
  "CostCenter"  = "data-platform"
  "Environment" = "production"
  "Owner"       = "data-eng"
}

These tags are applied to all resources created by the Onehouse Terraform module, including IAM roles, EC2 instances, and EKS resources.

Validate Your AWS Setup

Before deploying the customer stack, run the validation scripts below to catch any networking or permissions issues early.

Download: aws_permissions_check.sh and uris.txt — place both files in the same directory.

chmod +x aws_permissions_check.sh
./aws_permissions_check.sh <VPC-ID> <AWS_REGION> <ONEHOUSE_REQUEST_ID>

The script validates VPC configuration, subnet layout, IAM service roles, S3 endpoint access, and domain reachability. Fix any reported issues before proceeding to deployment.