Deploy AKKO on Amazon EKS¶

AKKO runs on EKS 1.30+ with the AWS Load Balancer Controller (ALB), EBS CSI for block storage, and IAM Roles for Service Accounts (IRSA) for fine-grained AWS permissions.

Prerequisites¶

Requirement	Version
EKS	1.30+ (3 nodes, `m6i.large` minimum — bigger for OpenMetadata)
AWS Load Balancer Controller	2.9+ installed in the cluster
EBS CSI Driver	Installed (AWS addon)
cert-manager	1.16+ for TLS (or use ACM directly)
external-dns	optional, for automatic Route 53 records
`kubectl` + `aws` CLI	configured against the cluster
Helm	≥ 3.14

IAM / IRSA setup (one-time)¶

Create the IRSA policies for any component that needs AWS access. AKKO does not need any by default, but object storage → S3 mirror or EFS → akko-docs (optional) would.

# Example: grant S3 read to object storage sidecar
eksctl create iamserviceaccount \
  --cluster my-eks-cluster \
  --namespace akko \
  --name akko-minio \
  --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess \
  --approve

One-command install¶

AKKO_DOMAIN=akko.customer.example \
AKKO_VERSION=2026.04 \
AKKO_VALUES_EXTRA=helm/examples/values-eks.yaml \
  bash deploy-from-harbor.sh

EKS-specific notes¶

Storage¶

AKKO uses gp3-csi (SSD, RWO, cheaper than gp2). EFS CSI for RWX is not required by AKKO 2026.04 (all PVCs reconcile to RWO). If you want RWX for shared workloads later, install the aws-efs-csi-driver addon and flip akko-docs.persistence.accessMode: ReadWriteMany.

ALB Ingress Controller¶

AKKO 2026.04 injects these ALB annotations on every Ingress:

alb.ingress.kubernetes.io/scheme: "internet-facing"
alb.ingress.kubernetes.io/target-type: "ip"
alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]'
alb.ingress.kubernetes.io/ssl-redirect: "443"

For internal-only ALBs set ingressAnnotations."alb.ingress.kubernetes.io/scheme": internal.

Private ECR mirror¶

If your EKS cluster cannot reach harbor.akko-ai.com (VPC-isolated), mirror into ECR:

aws ecr create-repository --repository-name akko/akko-cockpit
for img in cockpit postgres spark notebook trino ai-service mlflow \
           airflow dbt mcp-trino mcp-openmetadata docs aden \
           catalog-manager; do
  aws ecr create-repository --repository-name akko/akko-${img} 2>/dev/null || true
  skopeo copy \
    docker://harbor.akko-ai.com/akko/akko-${img}:2026.04 \
    docker://<account>.dkr.ecr.<region>.amazonaws.com/akko/akko-${img}:2026.04
done

Then override:

global:
  image:
    registry: <account>.dkr.ecr.<region>.amazonaws.com

Cost knobs¶

gp3-csi instead of gp2 saves ~20 %
One ALB per Ingress is the default; group routes under a single ALB by sharing alb.ingress.kubernetes.io/group.name
Enable Cluster Autoscaler or Karpenter for bursty jobs (Spark, Airflow)

Verify¶

kubectl -n akko get pods
kubectl -n akko get ingress
aws elbv2 describe-load-balancers --region <region> --query 'LoadBalancers[*].DNSName'
kubectl -n akko exec svc/akko-trino -c trino -- trino --execute "SHOW CATALOGS"

Troubleshooting¶

Symptom	Cause	Fix
Ingress address empty	AWS LBC not installed / not in this namespace	`kubectl -n kube-system get deploy aws-load-balancer-controller`
PVC stays `Pending`	EBS CSI not installed	`aws eks describe-addon --addon-name aws-ebs-csi-driver`
Pod `Init:CreateContainerConfigError`	IRSA annotation malformed	`kubectl describe sa -n akko akko-<svc>`
503 via ALB	Target group unhealthy, readiness probe failing	`kubectl describe pod` + check readiness
Image pull `403 ECR`	IRSA missing `AmazonEC2ContainerRegistryReadOnly` on node role	`aws iam list-attached-role-policies --role-name <node-role>`