Networking and ingress

Two network paths matter for an Icebreaker deployment:

• Outbound from your cluster — the Icebreaker Agent’s WebSocket connection to the Icebreaker control plane.
• Inbound to your cluster — SQL clients connecting to Data Server endpoints.

The Icebreaker Agent makes a single outbound WebSocket connection to the Icebreaker control plane. No inbound connection from Icebreaker to your cluster is required.

If your cluster has an egress network policy, you must allow the Icebreaker Agent pod to reach console.icebreakerdata.com on port 443. The Agent pod runs in the namespace specified by agent.workloadNamespace (default eyrie-compute) under the ServiceAccount created by the Helm chart.

Before installing the Agent, confirm the control plane endpoint is reachable from inside your cluster:

kubectl run -it --rm conn-test --image=curlimages/curl --restart=Never -n eyrie-compute -- curl -sv https://console.icebreakerdata.com

A TLS handshake followed by any HTTP response (including 4xx) confirms that DNS resolution and outbound TCP 443 are working. If you see connection refused, no route to host, or a DNS failure, check your cluster’s egress NetworkPolicy and your VPC security group outbound rules.

SQL clients connect to Data Server endpoints over Arrow Flight SQL (gRPC). Icebreaker supports two ingress modes; you choose one at install time and configure it via Helm values. See Icebreaker Agent configuration for the Helm values reference.

One AWS Application Load Balancer is provisioned per Data Server by the AWS Load Balancer Controller.

Requirements:

• The AWS Load Balancer Controller must be installed in your cluster. On EKS Auto Mode it is built in; on standard EKS it is a separate install.
• One ACM certificate covering the hostname(s) you will expose. The certificate ARN is passed to the Helm chart as agent.albCertificateArn.
• The ALB security group (managed by the Load Balancer Controller) must allow inbound traffic on port 50051 from your SQL clients’ source IPs or security groups.

Connection URL format:

grpc+tls://{elb-hostname}:50051

The ELB hostname is auto-generated by AWS (e.g. k8s-eyrieco-xxxxxxx.us-east-1.elb.amazonaws.com) and is shown in the Data Server info modal in the Admin console.

TLS hostname caveat:

The ACM certificate you provide is attached to the ALB listener, but the auto-generated ELB hostname will not match most certificates. SQL clients connecting to the raw ELB hostname will fail TLS hostname verification unless you either:

• Configure your SQL client to skip TLS hostname verification (acceptable for evaluation; not recommended for production).
• Create a CNAME from a hostname your certificate covers to the ELB hostname, and use the CNAME as the connection host. Update the connection URL manually — the Admin console shows the raw ELB hostname and does not auto-reflect CNAMEs.

Idle timeout and cold starts:

The ALB’s default idle timeout is 60 seconds. If a query triggers a cold start — for example, Karpenter provisioning a new node for a capacity policy with no warm capacity, which is common on Spot — the connection can sit idle longer than that while the query executor comes up, and the ALB will close it before the query returns. SQL clients see this as a bare UNAVAILABLE error with no further detail.

Raise the ALB’s idle timeout to comfortably exceed your worst-case cold-start time: EC2 console → Load Balancers → select the Data Server’s ALB → Attributes → Idle timeout (AWS allows up to 4000 seconds).

EKS Auto Mode note: On EKS Auto Mode, the built-in ALB controller is already installed and satisfies this requirement. It creates one ALB per Ingress and does not support merging multiple Data Servers onto a shared ALB — one ALB per Data Server is the fixed behavior. On standard EKS with Managed Node Groups, install the AWS Load Balancer Controller separately before using ALB ingress mode.

Cost note: Each Data Server gets its own ALB. This is the lower-friction option for evaluation but cost grows linearly with Data Server count.

All Data Servers share one nginx Ingress controller. Each Data Server is reachable at a unique subdomain of a wildcard base domain you control.

Requirements:

• The ingress-nginx controller must be installed in your cluster and expose a LoadBalancer Service.
• A wildcard DNS record (*.{your-ingress-domain}) pointing at the nginx controller’s LoadBalancer IP or hostname. This must be in place before Data Servers are created, or connection URLs will not resolve.
• A wildcard TLS certificate for *.{your-ingress-domain}, stored as a kubernetes.io/tls Secret in the workload namespace (eyrie-compute by default). The Secret name is passed to the Helm chart as agent.ingressTlsSecret.

Connection URL format:

grpc+tls://{data_server_id}.{ingress-domain}:443   # with TLS
grpc://{data_server_id}.{ingress-domain}:80         # without TLS

Without agent.ingressTlsSecret set, Ingresses are created without a TLS block and connection URLs use plain grpc:// on port 80. Set the secret to enable TLS.

Cost note: One LoadBalancer regardless of Data Server count. Better economics at scale.

• All Icebreaker workloads run in the eyrie-compute namespace (or whatever you set agent.workloadNamespace to). Namespace-scoped network policies apply to both Data Server pods and query executor pods in that namespace.
• Query executor pods read Parquet files directly from S3. If your cluster uses a VPC endpoint for S3, ensure query executor pods can reach it. If they go through the public internet, they need a NAT gateway or equivalent egress path.
• The Iceberg catalog endpoint must be reachable from within eyrie-compute. If your catalog is inside the VPC (e.g. Lakekeeper on EKS), confirm your internal DNS and security groups allow access from that namespace.
• No traffic passes between the Icebreaker control plane and your source data or results. The control plane endpoint handles only control messages and metrics over the Agent WebSocket.