Installing on Amazon EKS

:::warning Integration guide, not a v1.6 support gate

The planned v1.6 production matrix covers vanilla Kubernetes 1.34–1.36. EKS is not a release-gating environment. This page preserves the optional EKS rule-pack integration and is not a claim of provider-specific production support.

:::

The chart and its read-only RBAC can be installed on EKS without asking KubeAtlas for AWS IAM access. What EKS adds is the optional eks rule pack: a Rego pack that models the custom resources EKS add-ons inject into the cluster.

What the eks rule pack does (and does not)

EKS add-ons — AWS Load Balancer Controller, Karpenter, the EKS Pod Identity Agent — install CRDs and create custom resources that sit inside the cluster. The eks pack derives the edges between those resources and the workloads they back:

CRD	Edge	Meaning
TargetGroupBinding (elbv2.k8s.aws)	ROUTES_TO → Service	Which Service the ALB/NLB target group routes to
NodePool (karpenter.sh)	USES_NODE_CLASS → EC2NodeClass	Which node template Karpenter provisions from
PodIdentityAssociation (eks.amazonaws.com)	BINDS_PLATFORM_IDENTITY → ServiceAccount	Which ServiceAccount receives the EKS Pod Identity role

ROUTES_TO is the same edge type the OpenShift pack emits for Route → Service: the semantics are isomorphic, and reusing it keeps the cluster-view legend small.

The pack models the Kubernetes view of the cluster. It does not model AWS cloud resources — there are no nodes for S3 buckets, RDS instances, IAM roles, SQS queues, or Lambda functions. ARNs that appear in CRD specs are carried as plain metadata properties; KubeAtlas never resolves them through the AWS SDK (invariant 2.7). If you need a cloud-control-plane graph, that is a different tool — KubeAtlas reflects what the API server knows.

Recommended add-on pairings

The pack is most useful on clusters that run these add-ons; install order does not matter, the pack derives edges from whatever CRs exist:

• AWS Load Balancer Controller — TargetGroupBinding → Service edges turn an opaque ALB into a traceable path from the load balancer to the Pods behind it. Pairs with the ALB Ingress page.
• Karpenter — NodePool → EC2NodeClass edges let blast-radius show which workloads land on which provisioning template.
• EKS Pod Identity Agent — PodIdentityAssociation → ServiceAccount edges show which workloads carry an AWS identity. (IRSA — the older eks.amazonaws.com/role-arn ServiceAccount annotation — is surfaced by a built-in extractor, not this pack.)

Install

1. Pick a storage tier. Tier 1 (in-memory) is fine for a first look. For a cluster you will keep watching, use Tier 2 so the graph survives Pod restarts and you get snapshots:

   helm repo add cloudnative-pg https://cloudnative-pg.io/charts
   helm repo update
   helm upgrade --install cnpg cloudnative-pg/cloudnative-pg \
     --version 0.29.0 \
     --namespace cnpg-system --create-namespace \
     --wait --timeout 5m
   
   helm install kubeatlas oci://ghcr.io/lithastra/charts/kubeatlas \
     --version 1.5.2 \
     --namespace kubeatlas --create-namespace \
     --set persistence.enabled=true \
     --set persistence.embedded.enabled=true \
     --set persistence.embedded.storageSize=4Gi \
     --set rulePacks.extras='{oci://ghcr.io/lithastra/rules/eks:0.1.0}'

   The eks pack is opt-in — it is never auto-detected or embedded (invariant 2.3). You load it explicitly through rulePacks.extras, the same OCI mechanism any third-party pack uses. Pinning a semver tag is mandatory; :latest trips the loader's anti-pattern guard.

2. Confirm the pack loaded:

   kubectl logs -n kubeatlas deploy/kubeatlas | grep 'rule pack loaded'
   kubectl exec -n kubeatlas deploy/kubeatlas -- \
     wget -qO- localhost:8080/metrics | grep kubeatlas_rego_modules_loaded

3. Smoke-test an edge. With AWS Load Balancer Controller running, find a TargetGroupBinding and walk its outgoing edges:

   kubectl port-forward -n kubeatlas deploy/kubeatlas 8080:8080 &
   curl -s "http://127.0.0.1:8080/api/v1/resources/<ns>/TargetGroupBinding/<name>/outgoing" | jq .

   The response carries a ROUTES_TO edge to the backing Service — that is the eks pack at work.

Fargate

The chart can run on Fargate-only EKS clusters without changes. The chart's Pod requests fit a 0.5 vCPU / 1 GB Fargate profile for Tier 1; Tier 2 with the external CloudNativePG operator needs profiles that admit both the operator and database Pods. Size the database profile from persistence.embedded.storageSize and the CNPG resource defaults.

Troubleshooting

The pack failed to load:

• rulePacks.extras entries must be semver-pinned OCI refs. A missing tag, a :latest tag, or an unreachable registry is fatal at startup by design — check kubectl describe pod.
• The eks pack declares kubeatlas: ">= 1.1.0". On an older KubeAtlas the loader refuses it. Upgrade the chart first.

An edge never appears:

• The pack derives edges only from CRs that exist. No TargetGroupBinding objects means no BINDS_TARGET edges — that is correct, not a bug.
• kubectl logs deploy/kubeatlas | grep rego — module evaluation errors are logged per resource.
• The CRD must be installed and discoverable. KubeAtlas picks up CRDs at startup; if you installed the add-on after KubeAtlas, restart the Pod with kubectl rollout restart deploy/kubeatlas -n kubeatlas.