Skip to main content

​
Executive summary

To run LILT in your own AWS account, LILT’s deployment automation provisions a standard set of AWS resources — a managed Amazon EKS cluster with EKS-managed node groups, an S3 bucket, an RDS MySQL database, an optional SQS queue, the supporting network, and the encryption keys that protect them — and then runs the LILT platform on that cluster. AWS manages the Kubernetes control plane and the worker-node instance lifecycle; this is not a self-managed cluster running on hand-operated virtual machines. This document is the access request: it lists exactly what your security team needs to grant, why each item is needed, how it is scoped, and how long it is required. There are two grants:

1 · Deployment role

One IAM role, used only while creating or updating infrastructure. Grant it the deployment permissions below. It can be disabled or removed between deployments — it is not needed for day-to-day operation.

2 · Runtime roles

A set of narrowly-scoped roles the deployment creates for you and that the cluster’s workloads assume at runtime. Your team’s role here is to review and approve them — see runtime roles.

​
What you are granting, at a glance

​
Security posture

What your team can rely on when granting this:
  • Least privilege. Every policy lists only the actions the component needs. Runtime roles are additionally scoped to the specific resource LILT owns (its bucket, queue, key, or DNS zone) — they cannot touch anything else in the account.
  • No long-lived keys. Access is brokered by short-lived, federated credentials (EKS Pod Identity for workloads; your choice of federation for the deployment role). LILT does not require static IAM access keys.
  • Time-boxed deployment access. The broad create/delete permissions live on the deployment role, which is only needed during install or upgrade and can be detached the rest of the time.
  • Encryption by default. S3 and RDS are encrypted with dedicated KMS keys; the RDS database is private (no public endpoint) and reachable only from within the VPC. The DB master password is managed by AWS Secrets Manager (manage_master_user_password) — no password is stored in Terraform state. Application workloads retrieve it via the External Secrets Operator or directly from Secrets Manager.
  • Auditable. The runtime policies are fixed and enumerated in this document, so a granted deployment produces a known, reviewable set of standing roles.
Placeholders. The policies below use <ACCOUNT_ID>, <REGION>, <CLUSTER_NAME>, <PREFIX> (an environment name prefix, e.g. prod), and the <*_ARN> / <HOSTED_ZONE_ID> values — substitute the ones for your environment. This request assumes a single-region deployment; multi-region follows the same model per region.

​
Grant 1 · Deployment role

Create one IAM role for LILT’s deployment identity and attach the permissions below. This is the complete set of create, describe, modify, tag, and delete actions required to stand up and later tear down the resources LILT manages. It is needed only while provisioning; you may detach it between changes. Why each service is needed:
The statements are split into four documents purely to stay under the AWS 6,144-character managed-policy size limit — attach all four to the same role.
For an EKS managed node group cluster like LILT’s reference deployment:
  • The eks:*PodIdentityAssociation actions (EKSPodIdentity) are required — LILT binds every workload to its IAM role via EKS Pod Identity, so the deployment creates these associations. Do not drop them.
  • EventBridgeRules and the EKS-service ssm:GetParameter read are only needed for node auto-provisioning (Karpenter); they can be dropped here.
  • The instance-lifecycle actions in EC2Extended — ec2:RunInstances, ec2:TerminateInstances, ec2:StopInstances, ec2:StartInstances — are only needed for self-managed nodes or Karpenter. With EKS-managed node groups the EKS service manages instance lifecycle, so the deployment role does not use them; the remaining EC2Extended network-interface / ACL / volume actions are still required.

​
Grant 2 · Runtime roles

These roles are created for you by the deployment (using Grant 1) and are assumed by the cluster and its workloads at runtime. You do not hand-craft them; they are enumerated here so your team can review the standing access that will exist in the account after install.

​
EKS service roles (AWS-managed policies)

The cluster and its worker nodes use roles built entirely from AWS’s own managed policies — AWS’s least-privilege definitions for these service roles. No custom permissions are involved.
LILT’s reference cluster also attaches the legacy AmazonEKSServicePolicy to the cluster role. On EKS 1.24+ its permissions are folded into AmazonEKSClusterPolicy, so it is optional on new clusters.
LILT runs on EKS-managed node groups: the worker and GPU nodes are EC2 instances whose lifecycle Amazon EKS manages for you (creation, replacement, and scaling via the node group’s min/max/desired config). There are no self-managed EC2 instances or Auto Scaling groups to operate. As a result the Cluster Autoscaler and Karpenter roles below, and the “auto-provisioning” node-role variant above (AmazonSSMManagedInstanceCore), are not enabled by default — Karpenter is a future release; they are documented here for deployments that opt into node auto-provisioning.

​
Application & add-on roles (custom, least-privilege)

Each of these is a role with a small inline policy, scoped to the specific resource LILT owns and assumed by one named Kubernetes workload via short-lived federated credentials (EKS IRSA or Pod Identity). None of them can access resources outside the ones LILT created.
The core LILT platform. Reads/writes objects in the LILT bucket, uses that bucket’s KMS key, and consumes/produces on the LILT SQS queue — nothing else.
The SQS queue is always provisioned by the module. The AllowSQSAccess statement shown above is always present in the app workload role — it is not optional. The queue ARN is surfaced as the queue_arn output.
Keeps DNS records in sync for the application endpoints, scoped to LILT’s hosted zone.
Proves domain control for automated TLS certificates, scoped to LILT’s hosted zone.
Only present if the cluster scales via managed node groups. Scaling actions are gated on the cluster-ownership tag.
Optional — disabled by default; available in a future release. Launches and terminates nodes for the LILT cluster; every mutating action is gated on the cluster tag and region. This is the upstream Karpenter controller policy.
Abbreviated to the core statements. The full policy additionally scopes ec2:CreateFleet / RunInstances / CreateLaunchTemplate / CreateTags / TerminateInstances and the iam:*InstanceProfile actions by the kubernetes.io/cluster/<CLUSTER_NAME>: owned and karpenter.sh/nodepool tags — use the current published Karpenter controller policy for your Karpenter version.
Provisions the ALB/NLB load balancers for the application’s public endpoints. Management actions are gated on the controller’s ownership tag.
Condensed for readability. Deploy the exact, tag-condition-complete policy from the AWS Load Balancer Controller install guide matching your controller version.
Optional — when the External Secrets Operator is enabled, this role allows it to pull any secret whose name begins with the environment prefix — scoped to <PREFIX>/* in Secrets Manager. It cannot read secrets outside that prefix. Assumed by the external-secrets-sa service account in the external-secrets namespace via EKS Pod Identity.
Optional — disabled by default. Harbor requires access to the S3 bucket that backs its image registry and the KMS key used to encrypt that bucket. The module provisions Pod Identity associations for three Harbor service accounts (harbor-core, harbor-registry, harbor-jobservice) in the harbor namespace — all three assume the same role.
Harbor support is included in the module for organizations that run a self-hosted registry. For most deployments, ECR is the recommended path — no additional infrastructure is needed and images are pulled directly by node groups that already hold AmazonEC2ContainerRegistryReadOnly.
Optional — disabled by default. Creates a private ECR repository and grants the app_workload role push and pull permissions scoped to that repository. Node groups always receive AmazonEC2ContainerRegistryReadOnly (pull-only) regardless of this toggle.
Optional — present when the bastion is enabled. An EC2 instance role that lets operators run aws eks describe-cluster / update-kubeconfig against this one cluster and reach the private bastion over AWS Systems Manager Session Manager (no public IP or open SSH port required). It attaches the AWS-managed AmazonSSMManagedInstanceCore policy plus the inline statement below.

​
Cluster service account & Pod Identity wiring

The runtime roles above are not attached to pods directly. Each is bound to a named Kubernetes service account (SA), and an EKS Pod Identity association maps that SA to the IAM role. This section describes how LILT’s terraform sets that up so your team can see exactly which in-cluster identity receives which AWS permissions.

​
The LILT application service accounts

LILT’s application runs under one or more service accounts in the lilt namespace. The module variable app_workload_service_accounts (default: ["app-workload-sa"]) controls which service accounts receive Pod Identity associations to the app workload IAM role. Each named SA gets its own aws_eks_pod_identity_association. The service accounts themselves are created by your cluster’s application deployment (e.g. Helm chart), not by this Terraform module — the Pod Identity association is the AWS-side binding only.

​
How the pieces fit together

Three objects have to agree for a pod to receive AWS permissions:
  1. The Kubernetes service account — the identity the pod runs as (namespace + name).
  2. The IAM role — carries the least-privilege policy (e.g. the S3 + KMS permissions) and has a trust policy that allows pods.eks.amazonaws.com to assume it (sts:AssumeRole + sts:TagSession). This is what makes it a Pod Identity role (sts:AssumeRole + sts:TagSession from pods.eks.amazonaws.com). Under IRSA (iam_auth_method = "irsa"), the trust policy uses sts:AssumeRoleWithWebIdentity with a service-account-scoped condition against the cluster OIDC provider instead.
  3. The Pod Identity association (Pod Identity mode only) — the AWS-side record that says “SA namespace/name on this cluster may assume this role.” Under IRSA, the Kubernetes SA carries an eks.amazonaws.com/role-arn annotation in place of this association.
At runtime the EKS Pod Identity Agent (installed as a cluster add-on) sees a pod running under that service account, matches it to the association, and hands the pod short-lived, automatically-rotated credentials for the mapped role. No static keys are involved in either mode.
Because the association is keyed on namespace + service account name, those must match on both sides. If the SA is renamed, moved to another namespace, or recreated in a different namespace without updating the association, the pod loses its AWS access. Some add-on service accounts additionally have fixed names required by their controllers — e.g. the EBS CSI driver expects ebs-csi-controller-sa and the External Secrets Operator expects external-secrets-sa — and cannot be renamed.

​
Service-account-to-role map

The LILT cluster service account also carries in-cluster RBAC (Kubernetes Role/RoleBindings for the application and Argo Workflows components). That RBAC governs access to the Kubernetes API inside the cluster and is entirely separate from the AWS IAM permissions granted through the Pod Identity association described here — the same SA simply serves both roles.

​
How access is brokered

No component uses a long-lived IAM access key. Each principal obtains short-lived credentials via a federated trust:
LILT’s reference Terraform module supports two IAM authentication modes, selected via iam_auth_method:
  • pod_identity (default, recommended) — all workload roles use EKS Pod Identity. No OIDC provider is provisioned. Every role trusts pods.eks.amazonaws.com via sts:AssumeRole + sts:TagSession. Pod Identity associations wire each Kubernetes service account to its role on the AWS side.
  • irsa (backward compat) — an OIDC identity provider is provisioned for the cluster, and each role uses sts:AssumeRoleWithWebIdentity with a service-account-scoped condition. Use this for environments already running IRSA that are not yet ready to migrate.
The deployment role’s trust policy is yours to define — this document does not prescribe who may assume it. Grant the Grant 1 permissions to whichever identity your team authorizes to run the deployment, following your federation and access-control standards.

​
Helm chart sourcing for constrained environments

By default, LILT’s deployment pulls community Helm charts from their upstream HTTPS repositories (Artifact Hub, kubernetes-sigs, aws.github.io, etc.). In environments with restricted egress, two variables let you redirect chart sources without changing any other module configuration. Mirror all charts to a private OCI registry (e.g. Amazon ECR) and point the module at the base URL. All add-ons pull from that registry; no public internet access is required. The ECR VPC endpoint is included when VPC endpoints are enabled.

​
Option B — per-chart OCI override

Override individual charts while leaving others at their defaults (or at the helm_chart_registry base). Useful when only a subset of charts has been mirrored.
Valid keys: cluster-autoscaler, metrics-server, prometheus-node-exporter, external-dns, cert-manager, kube-state-metrics, datadog-operator, aws-load-balancer-controller, external-secrets.

​
Option C — break-the-glass (local .tgz, no network)

For fully isolated environments where even ECR is unreachable. Pre-fetch chart tarballs onto the machine running terraform apply, then reference them by absolute path. Setting repository = null tells the Helm provider to skip all registry lookups.
Local .tgz paths must exist on the machine running terraform apply. This option is not portable across runners unless all paths are pre-populated. Options A and B are preferred for reproducible deployments.