Connect to Your Cluster

Learn how to connect to your Kubernetes cluster using kubectl with Qovery CLI or AWS CLI

Overview

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

1. Qovery Console Shell (Easiest) - Browser-based terminal with no local setup: cluster-level (kubectl + k9s) or service-level (shell inside a running container)
2. Qovery CLI Method (Recommended) - Quick and easy access with automated configuration
3. 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.

Method 1: Using Qovery Console Shell (Easiest)

The Qovery Console provides the fastest way to access your cluster or a running service container, directly from your browser with no local setup required. No prerequisites needed - just your browser and Qovery Console access.

The Console Shell is available at two levels:

• Cluster level: a web terminal pre-configured with kubectl and k9s for full cluster access
• Service level: a web terminal that opens a session inside a running container of a specific service

Cluster-Level Shell

Use this when you need to inspect or manage Kubernetes resources across the entire cluster.

1. Navigate to Your Cluster

   Open your Qovery Console, go to Organization > Clusters, and select your cluster.

2. Open Cloud Shell

   Click the Cloud Shell tab to open an embedded browser-based terminal.

   
3. Use k9s or kubectl

   The shell opens with k9s by default, giving you a powerful terminal UI for Kubernetes. You can also use kubectl commands directly:

   # k9s is already running by default
   # Press 'q' to exit k9s if needed
   
   # Run kubectl commands
   kubectl get nodes
   kubectl get pods -A
   kubectl get namespaces
   

The cluster-level Cloud Shell comes pre-configured with: k9s for interactive Kubernetes cluster management, kubectl with cluster credentials automatically configured, and no local installation required.

Service-Level Shell

Use this when you need to inspect or debug a running container directly: run one-off commands, check environment variables, inspect files, or run a database migration.

1. Navigate to Your Service

   Open your Qovery Console, go to the relevant environment, and click on the service you want to connect to.

2. Open Cloud Shell

   Click the Cloud Shell tab. Qovery opens a terminal session inside a running container of that service.

3. Run Commands Inside the Container

   You now have a shell directly inside your container. Common use cases:

   # Inspect environment variables
   env
   
   # Check files on the filesystem
   ls -la /app
   
   # Run a database migration
   ./manage.py migrate
   
   # Inspect a running process
   ps aux
   

The service-level shell connects to an existing running container. If no container is running (e.g. the service is stopped), the shell will not be available.

Both shell options are perfect for quick debugging, running one-off commands, or when you don’t have local tools installed. No kubectl configuration or SSH access required.

Method 2: Using Qovery CLI (Recommended for Local Development)

Prerequisites

Before using Qovery CLI, ensure you have:

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

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.

1. Authenticate with Qovery

   Log in to your Qovery account:

   qovery auth
   

   Follow the browser authentication flow or use headless mode:

   qovery auth --headless
   
2. 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
   
3. 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
4. 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
   
5. 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:

1. 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
2. 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>
   
3. 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 3: Using AWS CLI (Advanced)

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.

Prerequisites

Before using AWS CLI method, ensure you have:

• AWS CLI installed
• kubectl installed
• Qovery CLI installed
• IAM user with appropriate permissions
• An existing EKS cluster managed by Qovery

Setup IAM Permissions

1. Configure IAM Access

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

   Option A: AWS Console

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

   Option B: Enable SSO

   1. Go to your Qovery cluster settings
   2. Navigate to Advanced Settings
   3. Enable SSO authentication for the cluster
2. 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)
3. Verify AWS Access

   Confirm AWS CLI is working:

   aws sts get-caller-identity
   

   This should return your IAM user information.

Configure kubectl

1. 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>
   
2. Set kubectl Context

   Configure kubectl to use the downloaded config:

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

   Verify the context:

   kubectl config current-context
   
3. 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:

1. List All Namespaces

   kubectl get namespaces
   

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

2. 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>

3. 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 error

Solutions:

• 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 forbidden

Solutions:

• 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 found

Solutions:

• 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 of Methods

Feature	Console Shell	Qovery CLI	AWS CLI
Setup Complexity	None (browser only)	Low (1-2 commands)	Medium (IAM setup required)
Local Installation	Not required	Qovery CLI + kubectl	AWS CLI + kubectl
Authentication	Automatic	Qovery account	IAM credentials
Best For	Quick debugging	Local development	Advanced users, automation
k9s Included	✅ Yes	❌ No	❌ No
kubectl Access	✅ Yes	✅ Yes	✅ Yes
Works Offline	❌ No	✅ Yes (once configured)	✅ Yes (once configured)
IAM Configuration	Not required	Not required	Required
Learning Curve	Minimal	Minimal	Moderate
Flexibility	Standard access	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

Related Resources

• kubectl Documentation
• AWS EKS User Guide
• Kubernetes RBAC
• AWS IAM Best Practices
• Qovery Kubernetes Changelog - Kubernetes cluster related updates