Prerequisites

An AWS account in a supported region is assumed. Your Icebreaker contact will confirm region availability during onboarding.

Onboarding is a brief exchange with your Icebreaker contact.

Provide to Icebreaker:

• Your AWS account ID — needed to scope cross-account ECR pull access to your account.
• Your target AWS region — your contact confirms region availability during onboarding.
• Email addresses for team members who need access to the Admin console (Google OAuth in the early-adopter phase).

Your contact provisions:

• Admin Console login for creating and managing Icebreaker Agents, Data Servers, and Data Catalogs.
• Container image pull access to Icebreaker’s private container registry, scoped to your AWS account.

You can continue with the remaining prerequisites in parallel — onboarding doesn’t block infrastructure setup.

Icebreaker reads source data from S3 and writes query results back to S3.

You’ll reference these buckets when you register tables in your Iceberg Catalog (step 6) and when you write the IAM policies in step 7.

Icebreaker runs in an EKS cluster within your private VPC. See How Icebreaker is delivered for differentiation between Icebreaker’s managed control plane and your private data plane.

You will need:

• An Amazon EKS cluster running Kubernetes 1.29 or later.

  EKS Auto Mode is recommended. Karpenter and the AWS Load Balancer Controller are pre-installed, removing two manual setup steps. Auto Mode works with both supported ingress modes — your ingress choice is a separate cost decision. See Set up an EKS Auto Mode cluster for a walkthrough and Ingress mode for the cost trade-offs.

• A system node pool large enough to run the Icebreaker Agent and Data Server pods (modest CPU and memory — typical defaults are sufficient). In EKS Auto Mode, the system and general-purpose NodePools are created automatically; no action required.

• Karpenter for node auto-provisioning. In EKS Auto Mode, Karpenter runs as part of the managed control plane — there are no pods to install or configure. On standard EKS, install Karpenter separately before installing Icebreaker.

• A namespace for Icebreaker workloads. The default chart value is eyrie-compute. The namespace must exist before you install the Icebreaker Agent.

The Icebreaker Agent is deployed as a Helm chart, so you need kubectl access to your cluster and helm 3.x on the machine you will run the install from.

Run the following to add the cluster to your kubeconfig:

aws eks update-kubeconfig --region <your-region> --name <your-cluster-name>

Verify access:

kubectl get nodes

If you get a ResourceNotFoundException, your CLI credentials may not match the account where the cluster lives. See step 2 of the EKS Auto Mode guide for troubleshooting, or use AWS CloudShell, which is pre-authenticated to your console session.

See the official helm installation guide for your operating system. Helm 3.x is required; Helm 2 is not supported.

Verify:

helm version

For an evaluation, the easy route is one domain and one certificate, reused everywhere. You need a domain name you control; request a single DNS-validated ACM certificate for it — see Provision an ACM certificate for the steps. A wildcard certificate (*.yourdomain.com) is the simplest choice, since it covers whatever subdomains you end up using.

You’ll reuse this one certificate in both of the following steps:

• Iceberg Catalog: if you evaluate with Lakekeeper (the recommended path), its browser-based UI and SQL query editor need it — plain HTTP breaks the query editor’s use of browser secure-context APIs.
• Ingress mode: ALB mode uses it for your Data Servers’ hostname; nginx mode uses it as the wildcard certificate every Data Server subdomain needs.

Optionally, you can request separate certificates instead of reusing one — for example, a dedicated certificate for Lakekeeper distinct from your Data Servers’ certificate. Request each where it’s actually used: Iceberg Catalog or Ingress mode.

Icebreaker requires:

• A running Iceberg-compatible catalog with at least one warehouse defined.
• One or more Iceberg tables registered so you have something to query.
• The catalog endpoint must be reachable from your EKS cluster — see Data Catalog not reachable for a reachability test.
• A credential — OIDC token, AWS IAM principal, or REST catalog credentials — that query pods can present. See Connecting your catalog for per-catalog credential details.

The catalog itself can run wherever you want (in-cluster, in your AWS account outside the cluster, or as an external SaaS) — see Where the catalog runs.

AWS Glue, Apache Polaris, Snowflake Open Catalog, and other Iceberg-REST-compatible catalogs are expected to work. See Catalog integration.

The Data Server Deployment and the per-query executor pods it dispatches both run under the colibri ServiceAccount in the workload namespace and share a single IAM role. This role has separate policies for S3 source-data reads, results writes, and the optional node cost monitor. The chart creates the colibri SA; you wire it to your IAM role via EKS Pod Identity (recommended) or IRSA.

See Query workload IAM role for the policy JSON and step-by-step setup.

Each Data Server needs a Kubernetes Ingress so SQL clients can reach it. You select ingress mode when you install the Icebreaker Agent via Helm — this section covers what to have ready beforehand.

The AWS Load Balancer Controller creates one ALB per Data Server automatically. On EKS Auto Mode it is pre-installed; on standard EKS, install it separately before proceeding.

What to have ready: the ACM certificate ARN from step 5, which you will pass as agent.albCertificateArn when you install the Icebreaker Agent Helm chart.

All Data Servers share one ingress-nginx controller. Each Data Server is reached at {data_server_id}.{your-ingress-domain}.

What to set up before installing:

• ingress-nginx controller installed in your cluster
• A wildcard DNS record pointing at the controller’s load balancer (*.{your-ingress-domain})
• The wildcard certificate from step 5, stored as a Kubernetes Secret in the eyrie-compute namespace

See Networking and ingress for the full configuration reference.

Icebreaker’s networking requirements are minimal — you do not need to open any new ports at the VPC or subnet level.

• Outbound from your cluster to Icebreaker’s control plane: TCP 443 to console.icebreakerdata.com over WebSocket (TLS). Default VPCs allow this; only restricted-egress setups need an explicit allow rule. The Agent connects to wss://console.icebreakerdata.com/ws/virtual-cluster — see Verify reachability for a pre-flight test.
• Inbound from SQL clients to Data Servers: handled by the load balancer’s own security group, provisioned automatically by the ingress mode you selected (ALB on 50051, or nginx on 443/80). Nothing to configure at the subnet level.

Icebreaker never initiates a connection into your cluster. All traffic is outbound from the Agent or inbound through the load balancer.

Once everything on this page is in place, continue to Install the Icebreaker Agent.