Install Qovery on GCP

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. Choose your preferred method:

Workload Identity Federation (Recommended)
Service Account JSON Key

Most secure method - Uses short-lived access tokens generated through GCP Workload Identity Federation (WIF). No downloadable service account JSON key is created or stored.

This mode is recommended if your organization disables service account key creation with constraints/iam.disableServiceAccountKeyCreation.

What the setup configures:

A GCP service account used by Qovery to manage your GKE resources
The Qovery custom IAM role, created or updated and bound to this service account
A Workload Identity Pool
An AWS Workload Identity Provider that trusts the Qovery AWS deployer identity used by q-core
A service account impersonation binding (roles/iam.workloadIdentityUser)
An organization policy entry allowing this service account to receive 4 hour access tokens

With this setup, Qovery does not receive a JSON private key. Instead, q-core exchanges the configured Qovery AWS deployer identity for a temporary GCP access token, then uses that token to create, update, or delete your GKE cluster.

Required Permissions

The account running the setup script must have enough permissions to configure both the GCP project and the GCP organization.At the project level, it must be able to:

enable GCP services;
create or reuse a service account;
create or update the Qovery custom IAM role and bind it to this service account;
create or update a Workload Identity Pool and Provider;
add roles/iam.workloadIdentityUser on the service account.

At the organization level, it must be able to update organization policies. Qovery requires 4 hour temporary tokens for GKE operations, so the script configures:constraints/iam.allowServiceAccountCredentialLifetimeExtensionfor the Qovery service account.For this last step, the account needs the Organization Policy Administrator role (roles/orgpolicy.policyAdmin) on the GCP organization, or an organization administrator must run this step for you.

Prepare Your GCP Project

Create or Select Project

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

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

Note Your Project ID

Copy your Project ID (not the project name) from the project selector.Example: my-company-production-123456

Generate the Workload Identity Federation Setup Command

Start Cluster Creation

Go to Qovery Console
Go to Clusters tab
Click Create Cluster
Select GCP as the cloud provider

Select Workload Identity Federation

Select Workload Identity Federation as the credential method.Qovery will generate a setup command for your GCP project. The command contains only your GCP setup values. The Qovery AWS account and principal to trust are embedded in the setup script, but no Qovery secret is embedded.

Copy the Command

Copy the generated command to your clipboard.The command will look like:

curl https://setup.qovery.com/create_credentials_gcp_wif.sh | bash -s -- \
  YOUR_PROJECT_ID \
  YOUR_SERVICE_ACCOUNT_NAME

The setup script creates or reuses the GCP service account named YOUR_SERVICE_ACCOUNT_NAME. Always provide this service account name explicitly.Qovery requires 4 hour temporary tokens for GKE operations. The setup script uses default Qovery resource names, resolves the GCP organization ID from YOUR_PROJECT_ID, and configures constraints/iam.allowServiceAccountCredentialLifetimeExtension for the Qovery service account.If your project is not directly attached to an organization, or if the script cannot resolve it, rerun the command with the organization ID as the last argument.

Run the Workload Identity Federation Setup Script

Open Google Cloud Shell

In Google Cloud Console, click the Cloud Shell icon in the top-right
Wait for Cloud Shell to initialize
Ensure you’re in the correct project: gcloud config get-value project

Run the Command

Paste the command from Qovery into Cloud Shell
Press Enter
The script will:
- Enable required GCP APIs
- Create or reuse the Qovery service account
- Create or update the Qovery custom IAM role
- Bind the Qovery custom IAM role to the service account
- Create or reuse the Workload Identity Pool
- Create or update the AWS Workload Identity Provider
- Allow the Qovery AWS identity to impersonate the GCP service account
- Allow this service account to receive 4 hour access tokens

Example output:

Operations completed.

Store these values in Qovery:

service_account_email=my-qovery-sa@my-company-production-123456.iam.gserviceaccount.com
workload_identity_provider_resource=projects/123456789012/locations/global/workloadIdentityPools/qovery-wif-pool/providers/qovery-aws

No JSON service account key was created.

Save Workload Identity Federation Credentials in Qovery

Return to Qovery Console and paste the values returned by the script:

Service account email
Workload Identity provider resource

Qovery will verify the configuration and save the credentials.

By default, GCP service account impersonation access tokens are limited to 1 hour.Qovery requires a 4 hour token lifetime for GKE operations, similar to the AWS EKS STS flow. To allow this, your GCP organization must allow the Qovery service account through constraints/iam.allowServiceAccountCredentialLifetimeExtension.If this policy is not configured, Workload Identity Federation credentials cannot be used for Qovery-managed GKE.

You can revoke Qovery’s access at any time by removing the roles/iam.workloadIdentityUser binding from the service account or deleting the Workload Identity Provider.

Why is this more secure than JSON keys?

Service account JSON keys are long-lived private keys. If they leak, they remain valid until you rotate or delete them.With Workload Identity Federation, Qovery receives short-lived access tokens only. No customer private key is downloaded, uploaded, or stored in Qovery.

What permissions does Qovery need?

The Qovery service account still needs the same GCP permissions required to manage GKE, Compute, networking, Cloud Storage, Artifact Registry, and Cloud Run resources.The same Workload Identity Federation credentials can also be used for GCP Artifact Registry in Qovery, as long as this service account has the required Artifact Registry permissions.For a detailed breakdown of every permission and why it is needed, see the GCP IAM Permissions Reference.

Can I reuse an existing service account?

Yes. Pass the existing service account name as YOUR_SERVICE_ACCOUNT_NAME. The script will reuse it, bind the Qovery custom role to it, allow the Qovery AWS deployer identity to impersonate it through roles/iam.workloadIdentityUser, and allow 4 hour access tokens for this service account.

Can I keep using JSON keys?

Yes. Service account JSON keys remain supported for existing installations and organizations that allow service account key creation.However, Workload Identity Federation is recommended for new GCP credentials.

Legacy method - Creates a downloadable service account JSON key and uploads it to Qovery.

Workload Identity Federation is recommended for new GCP credentials. Use JSON keys only if your organization allows service account key creation and you cannot use WIF yet.

Prepare Your GCP Project

Create or Select Project

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

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

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

Start Cluster Creation

Go to Qovery Console
Go to Clusters tab
Click Create Cluster
Select GCP as the cloud provider

Enter Project Details

Enter your Project ID
Click Next

Qovery will generate a secure installation command for you.

Copy the Command

Copy the generated command to your clipboard.The command will look like:

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

This script creates a service account with minimal required permissions.

If you enable static egress IPs for GCP NAT Gateway, the role must also include compute.addresses.create, compute.addresses.get, compute.addresses.list, and compute.addresses.delete. Typical Terraform failure when missing: Required 'compute.addresses.create' permission ... forbidden.

Run Installation Script

Open Google Cloud Shell

In Google Cloud Console, click the Cloud Shell icon (terminal icon) in the top-right
Wait for Cloud Shell to initialize
Ensure you’re in the correct project: gcloud config get-value project

Run the Command

Paste the command from Qovery into Cloud Shell
Press Enter
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

Download the Key File

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

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

Upload to Qovery

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

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

What permissions does Qovery need?

Qovery requires these GCP permissions to manage your infrastructure:

Compute Engine: Create and manage VMs, networks, and load balancers
Kubernetes Engine: Create and manage GKE clusters
VPC Networking: Configure networks, subnets, and firewall rules
Service Accounts: Manage service identities for workloads
Cloud Storage: Store Terraform state and logs
Artifact Registry: Store container images
Cloud Run: Manage serverless deployments (optional)

If static egress IPs are enabled on NAT Gateway, your role also needs compute.addresses.* permissions to reserve external IPs.The installation script automatically assigns the minimum required roles to the service account.

Can I use a custom service account?

Yes! You can create a service account manually with custom permissions. However, ensure it has all the roles required for managing GKE, Compute Engine, and networking resources. Contact support for the minimal permissions list.

How do I rotate credentials?

To rotate GCP credentials:

In GCP Console, go to IAM & Admin → Service Accounts
Find the qovery-service-account
Click Keys → Add Key → Create new key
Choose JSON format and download
Update credentials in Qovery Console
Wait 24 hours, then delete the old key in GCP

Step 2: Configure Your Cluster

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

Basic Configuration

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.

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.

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

Review Configuration

Review all your cluster settings:

Cluster name
GCP project
Region
Networking options

Create and Deploy

Click Create and Deploy

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

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

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:

Deploy Your First Application

Follow the Deploy Your First App guide

Configure Custom Domain

Set up your own domain instead of the default Qovery domain

Set Up Monitoring

Configure Cloud Monitoring or Datadog

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 minutesSolutions:

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:

Check your quotas: console.cloud.google.com/iam-admin/quotas
Request quota increase (usually approved instantly for established accounts)
Try a different region with more available capacity
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 databasesSolutions:

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:

Navigate to VPC Network Peering in GCP Console
Create peering connection from Qovery VPC to your VPC
Configure firewall rules for traffic
Update routes if necessary
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

You can also enable Private nodes during cluster creation to remove public IPs from GKE nodes and route node traffic through your gateway. This setting cannot be changed after the cluster is created.

Spot Pods (Preemptible VMs)

Save up to 91% on compute costs:

Add node selector to your deployments:

nodeSelector:
  cloud.google.com/gke-spot: "true"

Ensure your application handles interruptions gracefully
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

​Overview

Fully Managed

Production Ready

Cost Optimized

Auto-Scaling

​Prerequisites

​Required GCP Quotas

​Step 1: Create GCP Credentials

​Required Permissions

​Prepare Your GCP Project

​Generate the Workload Identity Federation Setup Command

​Run the Workload Identity Federation Setup Script

​Prepare Your GCP Project

​Generate Installation Command

​Run Installation Script

​Step 2: Configure Your Cluster

​Basic Configuration

​GKE Autopilot Configuration

​Networking Configuration

​Step 3: Deploy Your Cluster

​What Gets Created

​Post-Installation Steps

​Troubleshooting

​Advanced Configuration

​VPC Peering

​Using Existing VPC

​Spot Pods (Preemptible VMs)

​Best Practices

Use Spot Pods Wisely

Right-Size Resources

Enable Monitoring

Implement RBAC

Regular Updates

Backup Strategy

​Next Steps

Deploy Your First App

Configure RBAC

Set Up CI/CD

Monitor Your Cluster

​Additional Resources

Overview

Prerequisites

Required GCP Quotas

Step 1: Create GCP Credentials

Required Permissions

Prepare Your GCP Project

Generate the Workload Identity Federation Setup Command

Run the Workload Identity Federation Setup Script

Prepare Your GCP Project

Generate Installation Command

Run Installation Script

Step 2: Configure Your Cluster

Basic Configuration

GKE Autopilot Configuration

Networking Configuration

Step 3: Deploy Your Cluster

What Gets Created

Post-Installation Steps

Troubleshooting

Advanced Configuration

VPC Peering

Using Existing VPC

Spot Pods (Preemptible VMs)

Best Practices

Next Steps

Additional Resources