Ephemeral Environments on EKS for Agent Pull Requests: Step-by-Step Setup

Key points:

• qovery cluster install is interactive. It registers your EKS cluster in Qovery, writes a values-<cluster>.yaml Helm values file and prints the helm commands. You run those commands against the cluster.
• Prerequisites on the EKS side: Kubernetes 1.24 or later, kubectl with cluster-admin, Helm 3.15 or later, load balancer support, the EBS CSI driver and metrics-server.
• Ephemeral environments come from a blueprint. You clone a working environment, point it at your base branch and switch on Turn on Preview Environments. Every PR against that branch then gets its own environment, and merge or close deletes it.
• Agents fit in through the pull request. Claude Code, Cursor and Codex can each end a task with a PR, and that PR is what triggers the environment.
• The Helm install takes 5 to 10 minutes according to the Qovery docs. The blueprint part depends on how long your stack takes to build and deploy once.
• All of it fits in Qovery Free: 1 cluster of your own, 3 users, unlimited AI agents, 1,000 deployment minutes a month.

You already run EKS. Your coding agents already open pull requests. What's missing is the step in between: a running copy of the stack per PR, so a reviewer can click a URL instead of reading a diff and hoping. This tutorial sets that up on the cluster you have, without a new cluster, an Argo CD ApplicationSet or a Terraform workspace per PR.

The 2024 version of this tutorial used a local cluster. This one uses a real EKS cluster and current CLI output.

Before you start

On the cluster side, the Qovery BYOK docs list these requirements (Qovery docs), with the EKS-specific ones from the EKS integration page:

• EKS running Kubernetes 1.24 or later
• kubectl access with cluster-admin permissions
• Load balancer support
• A default storage class, and the EBS CSI driver for volumes
• metrics-server
• Outbound HTTPS from the cluster to api.qovery.com, your container registry and GitHub, GitLab or Bitbucket

On your machine: kubectl pointed at the cluster, and Helm 3.15 or later. The install commands use --rollback-on-failure, which replaced --atomic in Helm 3.15.

kubectl config current-context
kubectl get nodes
helm version --short

On the Qovery side: an organization (sign up on Qovery Free, no credit card) with your Git provider connected, which happens on first sign-in.

Use a cluster that isn't running production if you can. The Qovery docs recommend a separate cluster for preview environments, and on Free you get one cluster, so a staging or dev EKS cluster is the natural choice.

Step 1: Install the CLI and sign in

curl -s https://get.qovery.com | bash
# or on macOS:
brew tap Qovery/qovery-cli && brew install qovery-cli

qovery auth

qovery auth opens a browser for the OAuth flow. On a machine without a browser, use qovery auth --headless and follow the device-code prompt.

Step 2: Generate the Helm values with qovery cluster install

qovery cluster install

The command walks through these prompts:

1. Select where you want to install Qovery on: choose Your AWS EKS cluster.
2. Organization: pick your Qovery organization.
3. Reuse or create: if the organization already has self-managed clusters, you can reuse one. Otherwise, give the new cluster a name, for example eks-previews.
4. Cluster region: the AWS region your EKS cluster runs in, for example eu-west-3.
5. Container registry credentials: "A container registry is necessary to build and mirror the images deployed on your cluster." Select existing AWS credentials or create new ones.
6. Let's Encrypt email: the address that receives certificate expiry notifications.
7. File path to save Helm Values to: defaults to ./values-eks-previews.yaml.

It then prints a block titled "Follow these instructions to install your cluster". The CLI generates these commands for your file, so run what it prints. At the time of writing they look like this:

helm repo add qovery https://helm.qovery.com
helm repo update

# Pre-apply Gateway API and Envoy CRDs before the main Helm release
helm pull qovery/qovery --untar --untardir /tmp/qovery-helm-chart
helm template qovery-gateway-crds /tmp/qovery-helm-chart/qovery/charts/gateway-crds-helm \
  --set crds.gatewayAPI.enabled=true \
  --set crds.gatewayAPI.channel=standard \
  --set crds.envoyGateway.enabled=true | kubectl apply --server-side -f -
kubectl wait --for=condition=Established --timeout=180s crd/gateways.gateway.networking.k8s.io
kubectl wait --for=condition=Established --timeout=180s crd/envoyproxies.gateway.envoyproxy.io

Followed by two helm upgrade --install passes of the qovery/qovery chart into the qovery namespace. The first pass leaves out the components that depend on others (cert-manager configs, the gateway, the Qovery engine, agent and operator) to avoid circular dependencies, and the second pass installs the rest with --wait.

Open the values file before you run them. It is the place to adjust what Qovery installs next to your workloads. Per the BYOK docs, the core components are the Qovery agent and shell agent, and the chart can also bring ingress, cert-manager, external-DNS and metrics-server if they're missing. On a self-managed cluster those dependencies are yours to maintain afterwards.

Step 3: Check the cluster

kubectl get pods -n qovery

When the pods are running, the cluster appears in the Qovery console under your organization's clusters, and you can deploy to it.

Step 4: Deploy your stack once

Create a project and an environment on the new cluster in the console and add your services: the applications from your GitHub repository, plus the databases they need. If you'd rather have an agent do it, install Qovery Skills and ask Claude Code or Cursor to deploy the repo:

curl -fsSL https://skill.qovery.com/install.sh | bash

Then, in Claude Code: Deploy my application with Qovery. The deploy skill analyzes the codebase, creates a Dockerfile if one is missing, and provisions what the app needs.

Get this environment working end to end before going further. Every preview will be a copy of it, including its mistakes.

Step 5: Turn it into a blueprint and enable preview environments

1. On the working environment, choose Clone and name the copy blueprint.
2. In each application of the blueprint, set the Git branch to your base branch: the branch agent PRs will target, usually main.
3. Deploy the blueprint once to validate it, then stop it and switch auto-deploy off.
4. Open the blueprint's Settings > Preview environments. Switch on Turn on Preview Environments, select the services under Create Preview for PR opened on those services, and save.

Two optional settings worth deciding now:

• Create on demand: previews are created only when someone comments /qovery preview on the PR. Good when agents open many small PRs and only some need a running environment.
• Seeding: databases are cloned without their data. Add a lifecycle job that runs your seed script on the environment START event, following the database seeding guide.

To keep idle previews from holding EKS nodes overnight, add a deployment rule with the pattern [PR]* that stops preview environments in the evening and starts them in the morning (deployment rules).

Step 6: Test with a PR opened by an agent

Any agent that ends with a pull request against main works. With Claude Code locally:

Create a branch called feat/health-version, make GET /health return the
git commit SHA in a "version" field, commit, push, and open a pull request
against main with gh.

Or comment @claude on an issue if you use the Claude Code GitHub Action. It pushes a branch and gives you a prefilled PR link to open, as covered in the Claude Code + GitHub Actions tutorial. Cursor cloud agents can open the PR themselves, and Codex cloud tasks can create one from the task view.

When the PR is open:

• The Qovery bot comments on the PR with a link to follow the deployment, then the links to each service once it's deployed.
• The new environment appears in the console's Ephemeral table, cloned from the blueprint.
• Each new push to the branch redeploys it.

Check the change against the running environment:

curl -s https://<preview-api-url>/health

Then merge or close the PR. Qovery deletes the preview environment.

How long this takes

The Qovery docs put the Helm installation at 5 to 10 minutes. The prompts in Step 2 take a couple of minutes. Steps 4 and 5 take as long as your stack takes to build and deploy, twice: once for the working environment and once to validate the blueprint. Once the blueprint exists, there is nothing to set up per PR.

Running it on Qovery Free

Free covers exactly this setup: 1 cluster of your own (EKS here), 3 users, unlimited AI agents, preview environments and environment cloning, and 1,000 deployment minutes a month. A deployment minute is one minute of build and deploy time, so an idle preview costs none, and when the monthly allowance runs out deployments stop until next month or an upgrade. EKS nodes and load balancers stay on your AWS bill, as they already are.

Paid plans add Qovery-managed clusters, more users and minutes, and support in Slack or Microsoft Teams (pricing). For the options beyond Qovery, including Argo CD's PR generator and Vercel previews, see the preview environments guide for coding agents, and for agent deploys past preview, AI CI/CD. Teams still on ECS can keep production there and run previews on EKS, as explained in the ECS limits AWS won't raise.