> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Fully Managed" icon="wand-magic-sparkles">
    Qovery creates and manages your GKE Autopilot cluster automatically
  </Card>

  <Card title="Production Ready" icon="shield-check">
    Best practices for security, networking, and reliability
  </Card>

  <Card title="Cost Optimized" icon="dollar-sign">
    Pay only for what you use with GKE Autopilot's pod-based billing
  </Card>

  <Card title="Auto-Scaling" icon="arrows-maximize">
    Automatic workload-based scaling built into Autopilot
  </Card>
</CardGroup>

## Prerequisites

Before you begin, ensure you have:

<Check>**GCP Account**: Active Google Cloud account with billing enabled</Check>
<Check>**GCP Project**: A project created with billing linked</Check>
<Check>**Qovery Account**: Free account at [console.qovery.com](https://console.qovery.com/signup)</Check>
<Check>**Quotas**: Minimum 4 CPUs and 8 GB memory available in your quotas</Check>

### 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](https://console.cloud.google.com/iam-admin/quotas)

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

## 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

<Steps>
  <Step title="Create or Select Project">
    1. Go to [Google Cloud Console](https://console.cloud.google.com)
    2. Either create a new project or select an existing one
    3. Ensure billing is enabled for the project

    <Frame>
      <img src="https://mintcdn.com/qovery/fzGqCCT4DCwST-Oq/images/gcp-credentials/gcp_project.png?fit=max&auto=format&n=fzGqCCT4DCwST-Oq&q=85&s=0182ede68a0cb1c3634be3777334b4f1" alt="Select or create GCP project" width="830" height="507" data-path="images/gcp-credentials/gcp_project.png" />
    </Frame>

    <Tip>
      Use a dedicated project for Qovery to keep resources organized and costs trackable.
    </Tip>
  </Step>

  <Step title="Note Your Project ID">
    Copy your **Project ID** (not the project name) from the project selector.

    Example: `my-company-production-123456`

    <Info>
      You'll need this Project ID in the next steps.
    </Info>
  </Step>
</Steps>

### Generate Installation Command

<Steps>
  <Step title="Start Cluster Creation">
    1. Go to [Qovery Console](https://console.qovery.com)
    2. Click **Clusters** in the left sidebar
    3. Click **Create Cluster**
    4. Select **GCP** as the cloud provider
  </Step>

  <Step title="Enter Project Details">
    1. Enter your **Project ID**
    2. Click **Next**

    Qovery will generate a secure installation command for you.
  </Step>

  <Step title="Copy the Command">
    Copy the generated command to your clipboard.

    The command will look like:

    ```bash theme={null}
    curl https://hub.qovery.com/files/create_credentials_gcp.sh | bash -s -- YOUR_PROJECT_ID qovery_role qovery-service-account
    ```

    <Info>
      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](/getting-started/security-and-compliance/gcp-iam-permissions).
    </Info>
  </Step>
</Steps>

### Run Installation Script

<Steps>
  <Step title="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`

           <img src="https://mintcdn.com/qovery/DxdnY-k8BiVO4yTp/images/gcp-credentials/cloud-shell.png?fit=max&auto=format&n=DxdnY-k8BiVO4yTp&q=85&s=66b27249c0243c3fdb7303b108300d43" alt="Google Cloud Shell" width="1564" height="722" data-path="images/gcp-credentials/cloud-shell.png" />
  </Step>

  <Step title="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`)

    <Frame>
      <img src="https://mintcdn.com/qovery/fzGqCCT4DCwST-Oq/images/gcp-credentials/gcp_shell_1.png?fit=max&auto=format&n=fzGqCCT4DCwST-Oq&q=85&s=f163b50be0e6ce7dbda814434804fa94" alt="Run credential creation script" width="1564" height="722" data-path="images/gcp-credentials/gcp_shell_1.png" />
    </Frame>

    **Example output:**

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="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

    <Frame>
      <img src="https://mintcdn.com/qovery/fzGqCCT4DCwST-Oq/images/gcp-credentials/gcp_shell_5.png?fit=max&auto=format&n=fzGqCCT4DCwST-Oq&q=85&s=4bb3811ccaa3695223a90097ea1887d8" alt="Download key.json file from Cloud Shell" width="1105" height="622" data-path="images/gcp-credentials/gcp_shell_5.png" />
    </Frame>

    <Warning>
      **Keep this JSON key file secure!** It provides access to your GCP project. Never commit it to version control.
    </Warning>
  </Step>

  <Step title="Upload to Qovery">
    1. Return to Qovery Console
    2. Upload the `key.json` file when prompted
    3. Qovery will verify the credentials

    <Frame>
      <img src="https://mintcdn.com/qovery/fzGqCCT4DCwST-Oq/images/gcp-credentials/gcp_shell_6.png?fit=max&auto=format&n=fzGqCCT4DCwST-Oq&q=85&s=ee80ff2d58af380a6b1ebcf535bd0833" alt="Upload credentials to Qovery Console" width="1035" height="562" data-path="images/gcp-credentials/gcp_shell_6.png" />
    </Frame>

    <Tip>
      You can reuse these credentials for multiple clusters in the same GCP project.
    </Tip>
  </Step>
</Steps>

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

## Step 2: Configure Your Cluster

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

### Basic Configuration

<Steps>
  <Step title="Cluster Name">
    Choose a descriptive name for your cluster:

    * `production-gke`
    * `staging-gcp`
    * `dev-gke-uscentral1`

    <Tip>
      Use naming conventions that indicate environment and region for easier management.
    </Tip>
  </Step>

  <Step title="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

    <Info>
      Choose a region that complies with your data residency requirements and offers the lowest latency to your users.
    </Info>
  </Step>

  <Step title="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.
  </Step>
</Steps>

### GKE Autopilot Configuration

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

<Accordion title="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.

  <Tip>
    Autopilot supports both x86\_64 and ARM (Tau) architectures. Specify your architecture preference in pod annotations if needed.
  </Tip>
</Accordion>

### 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

<Accordion title="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.
</Accordion>

## Step 3: Deploy Your Cluster

<Steps>
  <Step title="Review Configuration">
    Review all your cluster settings:

    * Cluster name
    * GCP project
    * Region
    * Networking options
  </Step>

  <Step title="Create and Deploy">
    Click **Create and Deploy**

    <Info>
      You can start configuring applications immediately! The cluster will be available once deployment completes.
    </Info>
  </Step>

  <Step title="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
  </Step>

  <Step title="Verify Installation">
    Once complete, your cluster will appear in the cluster list with status **Running**.
  </Step>
</Steps>

## What Gets Created

Qovery automatically provisions these GCP resources:

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Post-Installation Steps

Once your cluster is running:

<Steps>
  <Step title="Deploy Your First Application">
    Follow the [Deploy Your First App](/guides/getting-started/deploy-your-first-application) guide
  </Step>

  <Step title="Configure Custom Domain">
    Set up your own domain instead of the default Qovery domain
  </Step>

  <Step title="Set Up Monitoring">
    Configure [Cloud Monitoring](/integrations/observability/overview) or [Datadog](/integrations/observability/datadog)
  </Step>

  <Step title="Configure Backups">
    Set up backup policies for persistent data
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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](https://status.cloud.google.com) for outages
    * Contact Qovery support if issue persists
  </Accordion>

  <Accordion title="Insufficient Quota">
    **Error**: "Quota exceeded" or "ZONE\_RESOURCE\_POOL\_EXHAUSTED"

    **Solutions:**

    1. Check your quotas: [console.cloud.google.com/iam-admin/quotas](https://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)
  </Accordion>

  <Accordion title="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](https://console.cloud.google.com/apis/library)
    * Required APIs:
      * Kubernetes Engine API
      * Compute Engine API
      * Artifact Registry API
      * Cloud Storage API
      * Cloud Resource Manager API
      * Cloud Run API
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

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

<Warning>
  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
</Warning>

### Spot Pods (Preemptible VMs)

Save up to 91% on compute costs:

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

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

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Spot Pods Wisely" icon="dollar-sign">
    Enable Spot Pods for dev/staging and fault-tolerant workloads to save up to 91%
  </Card>

  <Card title="Right-Size Resources" icon="gauge">
    Set accurate resource requests - Autopilot bills based on requests, not usage
  </Card>

  <Card title="Enable Monitoring" icon="chart-line">
    Configure Cloud Monitoring or third-party observability from day one
  </Card>

  <Card title="Implement RBAC" icon="shield">
    Use Workload Identity and Kubernetes RBAC for access control
  </Card>

  <Card title="Regular Updates" icon="arrows-rotate">
    GKE Autopilot auto-updates, but test your apps with new Kubernetes versions
  </Card>

  <Card title="Backup Strategy" icon="floppy-disk">
    Implement automated backups for persistent data and configurations
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy Your First App" icon="rocket" href="/getting-started/guides/getting-started/deploy-your-first-application">
    Complete step-by-step deployment guide
  </Card>

  <Card title="Configure RBAC" icon="users" href="/configuration/organization/members-rbac">
    Set up team access control
  </Card>

  <Card title="Set Up CI/CD" icon="code-branch" href="/configuration/integrations/ci-cd/github-actions">
    Automate deployments with GitHub Actions or GitLab CI
  </Card>

  <Card title="Monitor Your Cluster" icon="chart-line" href="/configuration/integrations/observability/qovery-observe">
    Configure monitoring and alerting
  </Card>
</CardGroup>

## Additional Resources

* [GKE Autopilot Documentation](https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-overview)
* [GCP Pricing Calculator](https://cloud.google.com/products/calculator)
* [GCP Free Tier](https://cloud.google.com/free)
* [Qovery Status Page](https://status.qovery.com)
* [Qovery Kubernetes Changelog](https://www.qovery.com/changelog---kubernetes) - Kubernetes cluster related updates