Install Qovery on AWS

Get your first production-ready Kubernetes cluster running on AWS. This guide walks you through the entire setup from connecting AWS to deploying your cluster.

Already have a Kubernetes cluster? See the BYOK guide instead.

What You’ll Get

✅ Production-ready EKS cluster in ~30 minutes
✅ Karpenter auto-scaling - Save up to 60% on AWS costs
✅ Automatic load balancing with SSL certificates
✅ Spot instance support for cost optimization
✅ Monitoring and logging built-in
✅ Ready to deploy your applications

About Karpenter

Qovery uses Karpenter for intelligent node provisioning, which automatically selects the most cost-effective EC2 instances for your workloads: Key Benefits:

Cost optimization through spot instances and consolidation
Fast scaling - Provisions nodes in seconds (vs minutes with traditional auto-scaling)
Smart instance selection - Picks the best from your allowed instance types
Workload consolidation - Packs pods efficiently to minimize node count

How It Works: During setup, you select multiple instance types (e.g., t3.medium, t3.large, m5.xlarge, m6i.large). Karpenter then automatically chooses the best option based on:

Your application resource requirements
Spot vs on-demand availability
Cost optimization across your selected instance types
Current capacity and pricing

More instance types = better optimization! Select a variety of instance types (t3, m5, m6i families) to give Karpenter maximum flexibility for cost and availability optimization.

Prerequisites

You have a Qovery account

You have an AWS account

You can access the AWS Console

No AWS expertise required - we’ll guide you through everything!

Quick Demo

Watch this walkthrough to see the entire cluster creation process:

Create Your Cluster

Follow these steps to create your first Qovery cluster on AWS:

Open Cluster Creation

Log into Qovery Console
Go to Organization Settings → Clusters
Click Create Cluster
Select AWS as your cloud provider

Name Your Cluster

Cluster name: Choose a name like production or my-first-cluster
Region: Select the AWS region closest to your users (e.g., us-east-1)

Connect AWS Account

Choose how to connect your AWS account to Qovery:

Source: Content below is maintained in /snippets/aws-credentials-*.mdx. Update snippets first, then copy to all usage locations.

STS Assume Role (Recommended)
Static Credentials

Most secure method - Uses temporary credentials that auto-rotate. No access keys to manage.What gets created: A CloudFormation stack creates an IAM role with this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:*",
        "eks:*",
        "iam:*",
        "elasticloadbalancing:*",
        "autoscaling:*",
        "logs:*",
        "s3:*"
      ],
      "Resource": "*"
    }
  ]
}

Setup Steps:

In Qovery Console: Click the CloudFormation link shown
- This opens AWS CloudFormation in a new tab (you’re logged in automatically)
In AWS CloudFormation Console:
- Click Next (template is pre-filled with Qovery’s requirements)
- Stack name: Keep default qovery-iam-role or customize
- Click Next (skip stack options)
- Click Next again (skip tags)
- ✅ Important: Check “I acknowledge that AWS CloudFormation might create IAM resources”
- Click Create stack
Wait for completion (~1 minute):
- Status changes: CREATE_IN_PROGRESS → CREATE_COMPLETE
- Refresh page if needed
Get the Role ARN:
- Click on the Outputs tab
- Find RoleArn key
- Copy the value (looks like: arn:aws:iam::123456789012:role/qovery-role)
Complete in Qovery:
- Back in Qovery, paste the Role ARN
- Give it a name like AWS Production
- Click Save

Why this is recommended: The IAM role uses AWS STS (Security Token Service) to generate temporary credentials that automatically rotate. Qovery never has access to long-lived credentials, and you can revoke access instantly by deleting the CloudFormation stack.

What permissions does Qovery need?

Qovery requires these AWS permissions to manage your infrastructure:

EC2: Create VPCs, subnets, security groups, and instances
EKS: Create and manage Kubernetes clusters
IAM: Create service roles for EKS and EC2
ELB: Create load balancers for your applications
S3: Store Terraform state and logs
CloudWatch: Collect logs and metrics

You can review the full CloudFormation template before creating the stack.

Can I use a custom IAM policy?

Yes! For production environments, you can create a custom IAM policy with minimum required permissions. Contact support for the minimal policy template.

Select Instance Types

Select instance types that Karpenter can choose from for your workloads.

Karpenter automatically picks the best instance type from your selections based on:

Pod resource requirements (CPU/memory)
Current spot availability and pricing
Cost optimization
Workload constraints

More instance types = better optimization and flexibility!

How to Select: You can filter and select instances by:

Instance Family: t3, t3a, m5, m6i, c5, c6i, r5, r6i, etc.
Size: medium, large, xlarge, 2xlarge, etc.
Architecture: x86_64 or ARM (Graviton - t4g, m6g, c6g)
Generation: Latest generations (m6i, m7i, c6i, c7i) are more cost-effective

Tips for Selection:

Start broad: Select multiple families and sizes
Mix families: Combine general purpose (t3, m5), compute (c5), memory (r5)
Include multiple sizes: Give Karpenter flexibility to bin-pack efficiently
Consider Graviton: ARM-based instances offer better price/performance

Enable spot instances for cost optimization. Karpenter handles interruptions gracefully and automatically falls back to on-demand if needed.

Avoid selecting only one or two instance types as this limits Karpenter’s ability to optimize for cost and availability. Aim for 10-20 instance types.

You can adjust these selections later in cluster settings!

Review and Create

Review your settings and click Create and DeployYour cluster will now be created automatically!

What Qovery Creates for You

When you create a cluster, Qovery automatically provisions a complete, production-ready infrastructure:

Network Architecture

✅ Dedicated VPC - Multi-AZ VPC isolating your infrastructure
✅ Subnets & Routing - Public/private subnets across 3 availability zones with routing tables
✅ Internet Gateway - For outbound container connectivity
✅ Network Load Balancer - Redirects HTTPS traffic to Nginx Ingress
✅ NAT Gateways (Optional) - With Elastic IPs for static outbound addresses
✅ Database Networks - Dedicated security groups and subnets for:
- RDS (relational databases)
- DocumentDB (document storage)
- ElastiCache (cache layers)

Kubernetes Infrastructure

✅ EKS Cluster - Multi-AZ, latest stable Kubernetes version
✅ Managed Worker Nodes - AWS-managed EC2 instances with Karpenter
✅ Security Groups - Dual authentication for EKS remote access (TLS + IAM authenticator)
✅ IAM Components:
- EBS CSI driver access for persistent volumes
- IAM User Sync for Kubernetes authentication
- Cluster Autoscaler permissions
- EKS CNI and EC2 Container Registry policies

Installed Components

✅ Karpenter - Intelligent auto-scaling for cost optimization
✅ AWS Load Balancer Controller - Automatic ingress management
✅ EBS CSI Driver - Persistent volume support
✅ Metrics Server - Resource monitoring
✅ Qovery Agent - Observability and management

Storage & Logging

✅ KMS-Encrypted S3 Buckets - For:
- Application logs
- Kubeconfig storage (versioned, private)
✅ CloudWatch Log Groups - Cluster diagnostics and logging

Karpenter Auto-Scaling

Qovery uses Karpenter for intelligent node provisioning, which can save up to 60% on AWS costs:How Karpenter Works:

Automatically provisions optimal EC2 instances based on your workload requirements
Scales nodes up within seconds when pods need resources
Consolidates workloads onto fewer nodes to reduce costs
Handles spot instance interruptions gracefully

Default Configuration:

Stable Node Pool: For Qovery system components (single instance, on-demand)
Default Node Pool: For your applications (auto-scaling, mixed on-demand/spot)
Optional GPU Node Pool: For ML/AI workloads (if enabled)

Instance Type Selection: Karpenter can provision from a wide range of instance types:

General Purpose: t3, m5, m6i, m6g (Graviton ARM)
Compute Optimized: c5, c6i, c6g (Graviton ARM)
Memory Optimized: r5, r6i, r6g (Graviton ARM)
GPU Instances: g4dn, g5 (if GPU node pool enabled)

Cost Optimization with Spot Instances:

Enable spot instances for significant cost reduction
Karpenter automatically handles spot interruptions
Mix of spot and on-demand for reliability

You can configure Karpenter settings after cluster creation in Cluster Settings → Node Pools. Learn more in the Cluster Configuration guide.

Wait for Cluster to Be Ready

Cluster creation takes 20-30 minutes. Here’s what’s happening:

Step	Time	What’s Being Created
1. Networking	3-5 min	VPC, subnets, security groups
2. EKS Control Plane	10-15 min	Kubernetes master nodes
3. Worker Nodes	5-10 min	EC2 instances for your apps
4. Qovery Components	3-5 min	Ingress, monitoring, logging

You’ll receive an email when your cluster is ready! Feel free to close this page.

While you wait:

☕ Grab a coffee
📖 Learn about deploying your first app
👥 Invite your team
🔗 Connect Git

Next: Deploy Your First Application

Once your cluster shows Ready status:

Deploy Your First App

Step-by-step guide to deploy from Git

Connect Database

Add PostgreSQL, MySQL, MongoDB, or Redis

Configure Domain

Use your own domain name

Invite Team

Add team members with permissions

Troubleshooting

CloudFormation stack fails

Most common causes:

AWS account doesn’t have permissions to create IAM roles
AWS region doesn’t support EKS

Solution: Make sure you’re logged in as AWS admin or have IAM permissions.

Can't find the Role ARN

Go to AWS CloudFormation console
Find your stack (status should be CREATE_COMPLETE)
Click the Outputs tab
Copy the value next to “RoleArn”

Cluster creation is stuck

If your cluster stays in “Creating” status for more than 45 minutes:

Check AWS service quotas (especially EC2 instances)
Try a different AWS region
Contact support

Credentials not working

For STS Assume Role:

Verify CloudFormation stack created successfully
Check RoleArn is copied correctly (starts with arn:aws:iam::)
Ensure AWS account has permissions to create IAM roles

For Static Credentials:

Verify IAM user has AdministratorAccess policy
Check Access Key ID and Secret Access Key are correct
Ensure keys are not disabled or expired

Get Started

Platform Capabilities

How-to Guides

Tutorials

Troubleshooting

Useful Resources

Install Qovery on AWS

What You’ll Get

About Karpenter

Prerequisites

Quick Demo

Create Your Cluster

Network Architecture

Kubernetes Infrastructure

Installed Components

Storage & Logging

Karpenter Auto-Scaling

Wait for Cluster to Be Ready

Next: Deploy Your First Application

Deploy Your First App

Connect Database

Configure Domain

Invite Team

Troubleshooting

Get Started

Platform Capabilities

How-to Guides

Tutorials

Troubleshooting

Useful Resources

​What You’ll Get

​About Karpenter

​Prerequisites

​Quick Demo

​Create Your Cluster

​Network Architecture

​Kubernetes Infrastructure

​Installed Components

​Storage & Logging

​Karpenter Auto-Scaling

​Wait for Cluster to Be Ready

​Next: Deploy Your First Application

Deploy Your First App

Connect Database

Configure Domain

Invite Team

​Troubleshooting

What You’ll Get

About Karpenter

Prerequisites

Quick Demo

Create Your Cluster

Network Architecture

Kubernetes Infrastructure

Installed Components

Storage & Logging

Karpenter Auto-Scaling

Wait for Cluster to Be Ready

Next: Deploy Your First Application

Troubleshooting