Skip to main content
You don’t need rvn-eks-cluster to use Kubernetes with Ravion. rvn-eks-web, rvn-eks-worker, rvn-eks-chart, and rvn-eks-addons can deploy to an EKS cluster you already run. Instead of picking a Ravion cluster in the Cluster field, enter the cluster’s details yourself.
Ravion doesn’t manage the lifecycle of a cluster you connect this way. Control plane version upgrades and managed node groups stay with whoever manages the cluster today. To hand those over to Ravion, either create a new cluster with rvn-eks-cluster, or import the existing cluster into an rvn-eks-cluster module’s Terraform state. Importing adopts the cluster without recreating it, and you then select that module in the Cluster field instead of following this guide.

​
Prerequisites

​
An IAM role with an EKS access entry

The Ravion deploy runner and Terraform assume an IAM role to get a token for the cluster’s Kubernetes API. rvn-eks-cluster creates this role for clusters it manages. For a cluster you bring, create it yourself:
  1. Create an IAM role in the cluster’s AWS account. rvn-eks-cluster names it <cluster-name>-ravion-runner and trusts the account, limited with an aws:PrincipalArn condition to the Ravion runner roles (arn:aws:iam::<account-id>:role/rvn-ci/rvn-ci-*).
  2. Give the role eks:DescribeCluster on the cluster. Getting a cluster token needs no other IAM permissions.
  3. Add an EKS access entry for the role, and associate AmazonEKSClusterAdminPolicy with cluster scope. The cluster’s authentication mode must allow access entries (API or API_AND_CONFIG_MAP).
You enter this role’s ARN as the Ravion Runner role ARN.

​
The EKS Pod Identity Agent

The add-ons and the IAM roles of web services and workers get AWS credentials through EKS Pod Identity. rvn-eks-cluster installs the eks-pod-identity-agent add-on. On a cluster you bring, check that it’s installed, and install it if it isn’t:

​
Networking for a private API endpoint

The deploy runner runs inside your AWS account. If the cluster’s API endpoint is private:
  • Choose a Terraform execution environment in the cluster’s VPC.
  • Create a security group for the runner, and allow HTTPS (port 443) from it to the cluster security group. Enter it as the Ravion Runner security group ID.
For a public endpoint, you can leave the runner security group blank.

​
Enter the cluster’s details

When you add an rvn-eks-web, rvn-eks-worker, rvn-eks-chart, or rvn-eks-addons module, open the Cluster field and choose Enter values manually. Then fill in: You can get the endpoint and CA data with:
rvn-eks-web also requires an EKS add-ons reference, which supplies the shared load balancer listeners. Set up rvn-eks-addons on the cluster first, then select it. In rvn-eks-worker, the add-ons reference is optional. rvn-eks-addons asks for the cluster name, runner role, and runner security group, plus these fields:
  • Cluster security group ID: used by Karpenter nodes and shared load balancers. Required when the default NodePool or any shared load balancer is enabled.
  • Node subnet IDs: where the default Karpenter NodePool launches nodes. Internal shared load balancers use them too.
  • Public subnet IDs: for internet-facing shared load balancers.

​
Operate the cluster with add-ons

Add rvn-eks-addons to an existing cluster to install Karpenter, External Secrets, KEDA, cert-manager, the AWS Load Balancer Controller, and logs, metrics, and traces. If the cluster already has a gp3 StorageClass that rvn-eks-addons doesn’t manage, turn off Default gp3 storage class. Otherwise the installation fails. Leave Ravion EKS Management on to register the cluster with Ravion and install the Operator agent. The agent reports workloads, pods, Kubernetes events, and crash logs to the dashboard, and runs in-cluster deploys. After that, you deploy to the cluster the same way as to a cluster created with rvn-eks-cluster. See Deploy.