Connect to EKS with kubectl

Overview

Connecting to your EKS cluster with kubectl gives you direct access to manage and debug your Kubernetes resources. Qovery provides two methods to connect to your EKS clusters:

Qovery CLI Method (Recommended) - Quick and easy access with automated configuration
AWS CLI Method (Traditional) - Manual setup for advanced users who need full control

Any manual operations on your cluster could conflict with Qovery’s management. Use with caution and understand the implications of direct cluster access.

Prerequisites

Before connecting to your EKS cluster, ensure you have:

Qovery CLI Method
AWS CLI Method

Qovery CLI installed
An existing EKS cluster managed by Qovery
kubectl installed (installation guide)
Access to the Qovery organization and cluster

Method 1: Using Qovery CLI (Recommended)

The Qovery CLI provides the fastest and easiest way to connect to your EKS cluster. It handles authentication and kubeconfig setup automatically.

Quick Access

The Qovery CLI offers two powerful commands for cluster access:

qovery cluster kubeconfig - Full Cluster Access

Downloads the kubeconfig file for complete cluster access. Use this when you need to:

Run kubectl commands directly
Deploy resources to multiple namespaces
Manage cluster-wide resources
Integrate with other tools (Helm, k9s, etc.)

qovery cluster debug-pod - Interactive Debug Shell

Opens an interactive debug pod with kubectl pre-configured. Use this when you need to:

Quick troubleshooting without local setup
Debug network connectivity from within the cluster
Test service discovery and DNS resolution
Run diagnostic commands in the cluster context

Option A: Get Kubeconfig File

This method downloads the kubeconfig file to your local machine for full kubectl access.

Authenticate with Qovery

qovery auth

Follow the browser authentication flow or use headless mode:

qovery auth --headless

List Available Clusters

Find your cluster ID:

qovery cluster list

Example output:

NAME           REGION        CLOUD     STATUS    VERSION
prod-us-east   us-east-1     AWS       Running   1.28
staging-eu     eu-west-1     AWS       Running   1.27

Download Kubeconfig

Get the kubeconfig for your cluster:

qovery cluster kubeconfig --cluster-id <cluster-id>

The command will:

Generate a kubeconfig file
Save it to your current directory
Display the file location

Configure kubectl

Set the KUBECONFIG environment variable:

export KUBECONFIG=<path-to-kubeconfig-file>

Or merge with your existing kubeconfig:

# Backup existing config
cp ~/.kube/config ~/.kube/config.backup

# Merge configs
KUBECONFIG=~/.kube/config:<path-to-kubeconfig-file> \
  kubectl config view --flatten > ~/.kube/config.new
mv ~/.kube/config.new ~/.kube/config

Verify Connection

Test your cluster access:

kubectl get nodes

You should see your cluster nodes listed.

Option B: Open Debug Pod

For quick troubleshooting without local setup, use the debug pod feature:

Open Debug Pod

Launch an interactive debug shell:

qovery cluster debug-pod \
  --organization-id <organization-id> \
  --cluster-id <cluster-id>

This opens a pod with:

kubectl pre-configured
Common debugging tools
Network access to cluster services

Run kubectl Commands

You can now run kubectl commands directly:

# List all namespaces
kubectl get namespaces

# View pods in a namespace
kubectl get pods -n <namespace>

# Check service endpoints
kubectl get endpoints -n <namespace>

Exit Debug Pod

When finished, exit the debug pod:

exit

The debug pod method is perfect for quick checks and doesn’t require any local configuration. It’s ideal for debugging connectivity issues or testing from within the cluster.

Method 2: Using AWS CLI (Traditional)

For users who need full control or want to use AWS IAM directly, you can configure kubectl using the AWS CLI. This method requires more manual setup but provides flexibility.

This method is recommended for advanced users who need custom IAM configurations or want to integrate with existing AWS tooling.

Setup IAM Permissions

Configure IAM Access

Add your IAM user to the cluster’s admin group. There are two ways to do this:Option A: AWS Console

Navigate to AWS IAM Console
Find the IAM user you’ll use for kubectl access
Add the user to the cluster’s “Admins” group created by Qovery

Option B: Enable SSO

Go to your Qovery cluster settings
Navigate to Advanced Settings
Enable SSO authentication for the cluster

Configure AWS CLI Credentials

Set up your AWS credentials:

aws configure

Enter your:

AWS Access Key ID
AWS Secret Access Key
Default region (match your cluster region)
Default output format (json recommended)

Verify AWS Access

Confirm AWS CLI is working:

aws sts get-caller-identity

This should return your IAM user information.

Configure kubectl

Download Kubeconfig with Qovery CLI

Even with AWS CLI method, use Qovery CLI to get the initial kubeconfig:

qovery cluster list
qovery cluster kubeconfig --cluster-id <cluster-id>

Set kubectl Context

Configure kubectl to use the downloaded config:

export KUBECONFIG=<path-to-kubeconfig-file>

Verify the context:

kubectl config current-context

Test Cluster Access

Verify you can access the cluster:

kubectl get nodes

If successful, you’ll see the list of nodes in your cluster.

Update kubeconfig with AWS CLI

If you need to regenerate the kubeconfig using AWS CLI directly:

aws eks update-kubeconfig \
  --region <region> \
  --name <cluster-name>

When using AWS CLI to generate kubeconfig, ensure the cluster name matches exactly as it appears in AWS EKS. Qovery-managed clusters follow a specific naming convention.

Working with Applications

Once connected, you can manage your applications directly with kubectl.

Find Your Application Namespace

Qovery creates a unique namespace for each environment:

List All Namespaces

kubectl get namespaces

Qovery namespaces start with ‘z’ followed by a unique identifier.

Identify Your Namespace

Find your namespace ID from the Qovery Console URL:

https://console.qovery.com/organization/<org-id>/project/<project-id>/environment/<environment-id>

Look for a namespace like: z<environment-id>

Set Default Namespace

Set the namespace as default for convenience:

kubectl config set-context --current --namespace=z<environment-id>

View Application Pods

List pods in your application namespace:

# List all pods
kubectl get pods --namespace <namespace>

# Get detailed pod information
kubectl get pods --namespace <namespace> -o wide

# Watch pod status in real-time
kubectl get pods --namespace <namespace> --watch

Access Application Logs

View logs from your application pods:

# View logs from a specific pod
kubectl logs <pod-name> --namespace <namespace>

# Follow logs in real-time
kubectl logs -f <pod-name> --namespace <namespace>

# View logs from all containers in a pod
kubectl logs <pod-name> --namespace <namespace> --all-containers

# View logs from previous container instance
kubectl logs <pod-name> --namespace <namespace> --previous

Shell into Application Container

Open an interactive shell in your application container:

# Open shell in pod
kubectl exec -ti --namespace <namespace> <pod-name> -- sh

# Or use bash if available
kubectl exec -ti --namespace <namespace> <pod-name> -- bash

# Execute a single command
kubectl exec --namespace <namespace> <pod-name> -- env

For multi-container pods, specify the container with -c <container-name>

Common Operations

Port Forwarding

Forward a local port to a pod port:

# Forward local port 8080 to pod port 80
kubectl port-forward --namespace <namespace> <pod-name> 8080:80

# Forward to a service
kubectl port-forward --namespace <namespace> service/<service-name> 8080:80

The Qovery CLI also provides a qovery port-forward command that can be easier to use. See qovery port-forward for details.

Describe Resources

Get detailed information about resources:

# Describe a pod
kubectl describe pod <pod-name> --namespace <namespace>

# Describe a service
kubectl describe service <service-name> --namespace <namespace>

# Describe a deployment
kubectl describe deployment <deployment-name> --namespace <namespace>

Check Resource Usage

Monitor resource consumption:

# Node resource usage
kubectl top nodes

# Pod resource usage
kubectl top pods --namespace <namespace>

# Specific pod resource usage
kubectl top pod <pod-name> --namespace <namespace>

View Events

Check cluster and namespace events:

# All events in namespace
kubectl get events --namespace <namespace>

# Watch events in real-time
kubectl get events --namespace <namespace> --watch

# Sort events by timestamp
kubectl get events --namespace <namespace> --sort-by='.lastTimestamp'

Troubleshooting

Connection Issues

Unable to Connect to Cluster

Symptoms: Unable to connect to the server errorSolutions:

Verify cluster is running: qovery cluster status --cluster <cluster-id>
Check your kubeconfig path: echo $KUBECONFIG
Ensure AWS credentials are valid: aws sts get-caller-identity
Regenerate kubeconfig: qovery cluster kubeconfig --cluster-id <cluster-id>

Authentication Failed

Symptoms: error: You must be logged in to the server (Unauthorized)Solutions:

Re-authenticate with Qovery: qovery auth
Verify IAM permissions for AWS CLI method
Check if your IAM user is in the cluster admin group
Ensure SSO is enabled if using SSO authentication

Forbidden Access

Symptoms: Error from server (Forbidden): <resource> is forbiddenSolutions:

Verify your IAM user has necessary permissions
Check RBAC roles: kubectl get rolebindings --namespace <namespace>
Ensure you’re using the correct namespace
Contact your organization admin for access

Namespace Not Found

Symptoms: Error from server (NotFound): namespaces "<namespace>" not foundSolutions:

List all namespaces: kubectl get namespaces
Verify environment ID from Qovery Console
Ensure environment is deployed
Check if namespace starts with ‘z’ prefix

Debug Commands

Useful commands for diagnosing issues:

# Check kubectl configuration
kubectl config view

# List available contexts
kubectl config get-contexts

# Switch context
kubectl config use-context <context-name>

# Verify cluster info
kubectl cluster-info

# Check API server health
kubectl get --raw='/readyz?verbose'

# Test DNS resolution
kubectl run -ti --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default

Security Best Practices

Direct cluster access bypasses Qovery’s safety mechanisms. Follow these best practices to avoid issues.

Do’s and Don’ts

DO

Use Qovery CLI method when possible
Read cluster resources for debugging
View logs and describe resources
Use debug pods for troubleshooting
Keep kubeconfig files secure

DON'T

Modify Qovery-managed resources directly
Delete resources created by Qovery
Change namespace labels or annotations
Modify ingress configurations
Edit service accounts or RBAC

Resource Management

Resources Safe to Modify

Application-specific ConfigMaps (not created by Qovery)
Application-specific Secrets (not created by Qovery)
Custom resources you deployed
Debug pods you created

Resources to Avoid Modifying

Deployments managed by Qovery
Services created by Qovery
Ingress resources
Qovery system namespaces (qovery, qovery-system, etc.)
Network policies
Resource quotas

Access Control

Use least-privilege IAM policies
Rotate credentials regularly
Store kubeconfig files securely (never commit to git)
Use separate IAM users for different team members
Enable AWS CloudTrail for audit logs
Consider using AWS SSO for temporary credentials

Comparison: Qovery CLI vs AWS CLI

Feature	Qovery CLI	AWS CLI
Setup Complexity	Low (1-2 commands)	Medium (IAM setup required)
Authentication	Qovery account	IAM credentials
Best For	Quick access, debugging	Advanced users, automation
Kubeconfig Management	Automatic	Manual
Debug Pod Access	Built-in	Not available
IAM Configuration	Not required	Required
Learning Curve	Minimal	Moderate
Flexibility	Standard access	Full AWS control

Next Steps

Qovery CLI Reference

Explore all Qovery CLI commands and features

Cluster Management

Learn more about managing clusters in Qovery

Deployment Logs

View deployment logs through Qovery Console

Port Forwarding

Use Qovery CLI port forwarding feature

Overview

Account & Organization

Clusters & Cloud

Source Control

Projects & Environments

Services

Deployment & CI/CD

Secrets & Monitoring

Notifications

Networking & Advanced

​Overview

​Prerequisites

​Method 1: Using Qovery CLI (Recommended)

​Quick Access

​Option A: Get Kubeconfig File

​Option B: Open Debug Pod

​Method 2: Using AWS CLI (Traditional)

​Setup IAM Permissions

​Configure kubectl

​Update kubeconfig with AWS CLI

​Working with Applications

​Find Your Application Namespace

​View Application Pods

​Access Application Logs

​Shell into Application Container

​Common Operations

​Port Forwarding

​Describe Resources

​Check Resource Usage

​View Events

​Troubleshooting

​Connection Issues

​Debug Commands

​Security Best Practices

​Do’s and Don’ts

DO

DON'T

​Resource Management

​Access Control

​Comparison: Qovery CLI vs AWS CLI

​Next Steps

Qovery CLI Reference

Cluster Management

Deployment Logs

Port Forwarding

​Related Resources

Overview

Prerequisites

Method 1: Using Qovery CLI (Recommended)

Quick Access

Option A: Get Kubeconfig File

Option B: Open Debug Pod

Method 2: Using AWS CLI (Traditional)

Setup IAM Permissions

Configure kubectl

Update kubeconfig with AWS CLI

Working with Applications

Find Your Application Namespace

View Application Pods

Access Application Logs

Shell into Application Container

Common Operations

Port Forwarding

Describe Resources

Check Resource Usage

View Events

Troubleshooting

Connection Issues

Debug Commands

Security Best Practices

Do’s and Don’ts

Resource Management

Access Control

Comparison: Qovery CLI vs AWS CLI

Next Steps

Related Resources