Install Qovery on GCP

Complete guide to installing Qovery on Google Cloud Platform with GKE Autopilot

Install Qovery on your GCP account and deploy a fully managed Kubernetes cluster (GKE Autopilot) in less than 20 minutes.

Overview

Qovery simplifies Google Kubernetes Engine (GKE) management by:

• Automating GKE Autopilot cluster creation and configuration
• Managing networking, load balancers, and DNS
• Providing built-in monitoring and logging
• Handling rolling updates and automatic scaling
• Securing your infrastructure with best practices

Fully Managed

Qovery creates and manages your GKE Autopilot cluster automatically

Production Ready

Best practices for security, networking, and reliability

Cost Optimized

Pay only for what you use with GKE Autopilot’s pod-based billing

Auto-Scaling

Automatic workload-based scaling built into Autopilot

Prerequisites

Before you begin, ensure you have:

GCP Account: Active Google Cloud account with billing enabled

GCP Project: A project created with billing linked

Qovery Account: Free account at console.qovery.com

Quotas: Minimum 4 CPUs and 8 GB memory available in your quotas

Required GCP Quotas

Verify you have sufficient quotas in your target region:

• CPUs (all regions): At least 4 vCPUs
• In-use IP addresses: At least 5-10 addresses
• Persistent Disk SSD: At least 100 GB

Check your quotas at: console.cloud.google.com/iam-admin/quotas

If you don’t have enough quota, request an increase through the GCP Console. Quota increases are usually approved within minutes for established accounts.

Step 1: Create GCP Credentials

Qovery needs credentials to manage resources in your GCP project. We use a secure service account approach with minimal required permissions.

Prepare Your GCP Project

1. Create or Select Project

   1. Go to Google Cloud Console
   2. Either create a new project or select an existing one
   3. Ensure billing is enabled for the project

   

   Use a dedicated project for Qovery to keep resources organized and costs trackable.

2. Note Your Project ID

   Copy your Project ID (not the project name) from the project selector.

   Example: my-company-production-123456

   You’ll need this Project ID in the next steps.

Generate Installation Command

1. Start Cluster Creation

   1. Go to Qovery Console
   2. Click Clusters in the left sidebar
   3. Click Create Cluster
   4. Select GCP as the cloud provider
2. Enter Project Details

   1. Enter your Project ID
   2. Click Next

   Qovery will generate a secure installation command for you.

3. Copy the Command

   Copy the generated command to your clipboard.

   The command will look like:

   curl https://hub.qovery.com/files/create_credentials_gcp.sh | bash -s -- YOUR_PROJECT_ID qovery_role qovery-service-account
   

   This script creates a service account with minimal required permissions. For a detailed breakdown of every permission and why it’s needed, see the GCP IAM Permissions Reference.

Run Installation Script

1. Open Google Cloud Shell

   1. In Google Cloud Console, click the Cloud Shell icon (terminal icon) in the top-right

   2. Wait for Cloud Shell to initialize

   3. Ensure you’re in the correct project: gcloud config get-value project

      
2. Run the Command

   1. Paste the command from Qovery into Cloud Shell
   2. Press Enter
   3. The script will:
      • Enable required GCP APIs (Container, Compute, Artifact Registry, Storage, Cloud Resource Manager, Cloud Run)
      • Create a service account named qovery-service-account
      • Assign necessary IAM roles
      • Generate and download a JSON key file (key.json)

   

   Example output:

   Activating services APIs
   Operation "operations/acf.p2-..." finished successfully.
   ...
   Creating service account qovery-service-account
   Created service account [qovery-service-account].
   ...
   created key [abc123...] of type [json] as [key.json]
   ✓ Credentials configured successfully
   
3. Download the Key File

   1. In Cloud Shell, click the More menu (three dots)
   2. Select Download
   3. Enter the file path: key.json
   4. Save the file securely

   

   Keep this JSON key file secure! It provides access to your GCP project. Never commit it to version control.

4. Upload to Qovery

   1. Return to Qovery Console
   2. Upload the key.json file when prompted
   3. Qovery will verify the credentials

   

   You can reuse these credentials for multiple clusters in the same GCP project.

Source: Content above is maintained in /snippets/gcp-credentials.mdx. Update snippet first, then copy to all usage locations.

Step 2: Configure Your Cluster

Now configure your GKE Autopilot cluster settings in the Qovery console.

Basic Configuration

1. Cluster Name

   Choose a descriptive name for your cluster:

   • production-gke
   • staging-gcp
   • dev-gke-uscentral1

   Use naming conventions that indicate environment and region for easier management.

2. Select Region

   Choose a GCP region closest to your users:

   North America:

   • us-central1 - Iowa
   • us-east1 - South Carolina
   • us-east4 - Virginia
   • us-west1 - Oregon
   • us-west2 - Los Angeles
   • us-west3 - Salt Lake City
   • us-west4 - Las Vegas

   Europe:

   • europe-west1 - Belgium
   • europe-west2 - London
   • europe-west3 - Frankfurt
   • europe-west4 - Netherlands
   • europe-west6 - Zurich
   • europe-north1 - Finland

   Asia Pacific:

   • asia-southeast1 - Singapore
   • asia-east1 - Taiwan
   • asia-northeast1 - Tokyo
   • asia-south1 - Mumbai
   • australia-southeast1 - Sydney

   Choose a region that complies with your data residency requirements and offers the lowest latency to your users.

3. Attach Credentials

   Select the GCP credentials you created in Step 1.

   If you need to create new credentials, click Add new credentials and repeat Step 1.

GKE Autopilot Configuration

GKE Autopilot automatically manages your cluster’s infrastructure, including node provisioning, scaling, and maintenance.

Understanding GKE Autopilot

What is GKE Autopilot?

GKE Autopilot is Google’s fully managed Kubernetes offering where:

• Google manages all nodes, node pools, and infrastructure
• You pay only for the resources your pods request (pod-based billing)
• Automatic scaling based on workload demands
• Built-in security and compliance best practices
• Regional clusters by default (high availability)

Compute Classes:

Autopilot automatically provisions the right machine types for your workloads:

• General Purpose (default): E2 machines for standard workloads
• Balanced: Higher CPU/memory capacity for demanding applications
• Scale-Out: Optimized for high-throughput, scale-out workloads
• Accelerator: GPU-enabled for ML/AI workloads

You don’t need to select machine types manually - Autopilot handles this automatically based on your pod resource requests.

Autopilot supports both x86_64 and ARM (Tau) architectures. Specify your architecture preference in pod annotations if needed.

Networking Configuration

Qovery automatically configures GCP networking:

What’s Created:

• Virtual Private Cloud (VPC) with custom subnet ranges
• Cloud NAT for outbound internet connectivity
• Cloud Router for dynamic routing
• Static external IP addresses
• Firewall rules for security
• Load balancers for ingress traffic

Advanced Networking Options

Qovery-Managed VPC (Default): Qovery creates a dedicated VPC for your cluster with optimal configuration.

Existing VPC: Deploy into your own VPC to connect with existing GCP resources.

Static IP: Enable static IP addresses at cluster creation (only available with Qovery-managed VPC).

VPC Peering: Configure VPC peering after deployment to connect to databases, Cloud SQL, or other services.

Step 3: Deploy Your Cluster

1. Review Configuration

   Review all your cluster settings:

   • Cluster name
   • GCP project
   • Region
   • Networking options
2. Create and Deploy

   Click Create and Deploy

   You can start configuring applications immediately! The cluster will be available once deployment completes.

3. Monitor Progress

   Watch the deployment progress in the Qovery console.

   Timeline:

   • 0-5 min: Enabling GCP APIs and creating service accounts
   • 5-10 min: Provisioning VPC, subnets, and networking
   • 10-15 min: Creating GKE Autopilot control plane
   • 15-20 min: Installing Qovery components (ingress, monitoring, etc.)

   Status indicators:

   • 🟡 Creating: Infrastructure provisioning in progress
   • 🟢 Running: Cluster is ready to use
   • 🔴 Error: Check logs for troubleshooting
4. Verify Installation

   Once complete, your cluster will appear in the cluster list with status Running.

What Gets Created

Qovery automatically provisions these GCP resources:

Core Infrastructure

• GKE Autopilot Cluster: Fully managed Kubernetes cluster
• Virtual Private Cloud: Isolated network for your cluster
• Subnets: Public and private subnets with IP ranges
• Cloud NAT: Outbound internet connectivity
• Cloud Router: Dynamic routing for VPC
• Firewall Rules: Security rules for traffic control

Networking

• Cloud Load Balancing: HTTP(S) and TCP/UDP load balancing
• External IP Addresses: Static IPs for ingress (optional)
• Cloud DNS: Automatic domain management
• Service Networking: Private service connections

Compute

• Autopilot-Managed Nodes: Automatically provisioned and scaled
• Persistent Disks: SSD storage for applications
• Container Registry: Artifact Registry for container images
• Compute Classes: E2, N2, C3 machines based on workload needs

Qovery Components

• NGINX Ingress Controller: HTTP/HTTPS routing
• Cert-Manager: Automatic SSL/TLS certificates
• Qovery Agent: Cluster management and monitoring
• Metrics Server: Resource usage metrics
• DNS Management: Automatic domain configuration

Post-Installation Steps

Once your cluster is running:

1. Deploy Your First Application

   Follow the Deploy Your First App guide

2. Configure Custom Domain

   Set up your own domain instead of the default Qovery domain

3. Set Up Monitoring

   Configure Cloud Monitoring or Datadog

4. Configure Backups

   Set up backup policies for persistent data

Troubleshooting

Credential Creation Failed

Error: “Failed to create service account” or “Permission denied”

Solutions:

• Verify you have Owner or Editor role in the GCP project
• Check that billing is enabled for the project
• Ensure the project ID is correct (use project ID, not project name)
• Try running the script again - API enablement can take a few minutes

Cluster Creation Stuck

Issue: Cluster stuck in “Creating” state for over 30 minutes

Solutions:

• Check GCP quotas for your project (vCPUs, IPs, disks)
• Verify the selected region has GKE availability
• Check GCP Status Dashboard for outages
• Contact Qovery support if issue persists

Insufficient Quota

Error: “Quota exceeded” or “ZONE_RESOURCE_POOL_EXHAUSTED”

Solutions:

1. Check your quotas: console.cloud.google.com/iam-admin/quotas
2. Request quota increase (usually approved instantly for established accounts)
3. Try a different region with more available capacity
4. Reduce your workload’s resource requests

Common quota limits:

• CPUs (all regions)
• In-use IP addresses
• Persistent Disk SSD (GB)
• NVIDIA GPUs (if using accelerators)

API Not Enabled

Error: “API not enabled” or “Service […] is not enabled”

Solutions:

• The installation script should enable all required APIs
• Manually enable missing APIs in API Library
• Required APIs:
  • Kubernetes Engine API
  • Compute Engine API
  • Artifact Registry API
  • Cloud Storage API
  • Cloud Resource Manager API
  • Cloud Run API

Network Configuration Issues

Issue: Applications can’t access external services or databases

Solutions:

• Verify Cloud NAT is properly configured
• Check firewall rules in VPC settings
• Ensure VPC peering is set up correctly (if using existing VPC)
• Test connectivity from a pod: kubectl run -it debug --image=nicolaka/netshoot --rm

Advanced Configuration

VPC Peering

Connect your GKE cluster to existing GCP resources:

1. Navigate to VPC Network Peering in GCP Console
2. Create peering connection from Qovery VPC to your VPC
3. Configure firewall rules for traffic
4. Update routes if necessary
5. Test connectivity

Using Existing VPC

Deploy Qovery into your own VPC:

When using an existing VPC, ensure it has:

• Sufficient IP address ranges for pods and services
• Proper subnet configuration
• Cloud NAT configured for internet access
• Required firewall rules

Spot Pods (Preemptible VMs)

Save up to 91% on compute costs:

1. Add node selector to your deployments:
   nodeSelector:
     cloud.google.com/gke-spot: "true"
   
2. Ensure your application handles interruptions gracefully
3. Use for stateless, fault-tolerant workloads only

Spot Pods can be terminated with 30 seconds notice. Not recommended for production databases or stateful services.

Best Practices

Use Spot Pods Wisely

Enable Spot Pods for dev/staging and fault-tolerant workloads to save up to 91%

Right-Size Resources

Set accurate resource requests - Autopilot bills based on requests, not usage

Enable Monitoring

Configure Cloud Monitoring or third-party observability from day one

Implement RBAC

Use Workload Identity and Kubernetes RBAC for access control

Regular Updates

GKE Autopilot auto-updates, but test your apps with new Kubernetes versions

Backup Strategy

Implement automated backups for persistent data and configurations

Next Steps

Deploy Your First App

Complete step-by-step deployment guide

Configure RBAC

Set up team access control

Set Up CI/CD

Automate deployments with GitHub Actions or GitLab CI

Monitor Your Cluster

Configure monitoring and alerting

Additional Resources

• GKE Autopilot Documentation
• GCP Pricing Calculator
• GCP Free Tier
• Qovery Status Page
• Qovery Kubernetes Changelog - Kubernetes cluster related updates