Skip to main content
Version: Next (unreleased)

Installing on Amazon EKS

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

The v1.6.0 source-validation 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:

CRDEdgeMeaning
TargetGroupBinding (elbv2.k8s.aws)ROUTES_TO → ServiceWhich Service the ALB/NLB target group routes to
NodePool (karpenter.sh)USES_NODE_CLASS → EC2NodeClassWhich node template Karpenter provisions from
PodIdentityAssociation (eks.amazonaws.com)BINDS_PLATFORM_IDENTITY → ServiceAccountWhich 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.

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.6.0 \
      --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.