Qovery-Managed GKE

Learn how to configure your GCP Kubernetes clusters on Qovery

Creating a GCP GKE Cluster

Connect Your GCP Account

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. Go to Clusters tab
   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://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

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.

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:

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

Create the Cluster

1. Select GCP as Hosting Mode

   Click on GCP as hosting mode and then Qovery Managed option.

   In the Create Cluster window enter:

   • Cluster name: enter the name of your choice for your cluster.
   • Description: enter a description to identify better your cluster.
   • Production cluster: select this option if your cluster will be used for production.
   • Region: select the geographical area in which you want your cluster to be hosted.
   • Credentials: select one of the existing cloud provider credentials or create new credentials.

   To confirm, click Next.

2. Configure Network

   In the Network step, select the network mode you want to enable on your cluster.

   If you want to manage the network layer of your cluster by yourself, you can switch VPC mode to Deploy on my existing VPC to use your own VPC instead of the one provided by Qovery.

   These options can only be configured during cluster creation and cannot be modified later.

   VPC managed by Qovery

   Static IP

   The Static IP feature is currently only available to clusters deployed with a VPC managed by Qovery and can only be enabled at cluster creation.

   By default, when your cluster is created, its worker nodes are allocated public IP addresses, which are used for external communication. For improved security and control, the Static IP feature allows you to ensure that outbound traffic from your cluster uses specific IP addresses.

   Here is what will be deployed on your cluster:

   • Cloud Routers
   • Cloud NAT gateways
   • Auto-allocated Cloud NAT IPs (default) or two reserved external IPs per cluster (opt-in, see below)

   Default behavior: auto-allocated Cloud NAT IPs

   By default, the Cloud NAT gateways provisioned by Qovery use auto-allocated public IPs managed by GCP. These IPs can rotate over time (for example after maintenance, scaling events, or NAT reconfiguration) and are therefore not suitable for whitelisting with third-party services that require a fixed source IP.

   Opt-in: stable egress IPs via the NAT Gateway feature

   To get stable egress IPs that you can safely allowlist with services like Stripe, payment gateways, or partner APIs, enable static Cloud NAT IPs on the cluster’s NAT Gateway feature. When configuring the NAT Gateway feature on your GKE cluster, set the staticIpsEnabled option to true (default false). When enabled, the engine reserves two static external IPs (google_compute_address) per cluster and binds them to the Cloud NAT in MANUAL_ONLY mode. These IPs remain stable for the entire lifetime of the cluster.

   This option is configured alongside the other NAT Gateway parameters via the cluster’s NAT Gateway configuration in the Console, API, or Terraform provider. On the API and Terraform sides the field is named staticIpsEnabled on NatGatewayParameters (serialized as static_ips_enabled on the JSON wire format).

   Enabling on an existing cluster: turning on staticIpsEnabled on a cluster that was previously running with auto-allocated NAT IPs triggers a one-time NAT IP swap on the next infrastructure apply. Egress traffic is briefly interrupted (seconds to a couple of minutes) while Cloud NAT switches from AUTO_ONLY to MANUAL_ONLY. Pods, nodes, services, and the router are not recreated. Plan to refresh any IP allowlists with your third-party providers right after that apply.

   Things to know before enabling:

   • Cost: each reserved external IP is billed by GCP at about $0.005/hour (~$3.65 per IP per month), so two IPs add roughly $7.30/month to your GCP bill per cluster.
   • GCP quota: GCP enforces a default quota of 8 reserved external IPs per region. Make sure your project quota can accommodate 2 IPs per GKE cluster region before enabling.
   • Connection capacity: with MANUAL_ONLY, GCP can no longer scale NAT IPs automatically. Simultaneous outbound connections are hard-capped at 2 × 64512 / min_ports_per_vm. For most clusters this is well within the budget, but very high-traffic or multi-tenant clusters should validate.

   Finding the reserved IPs once enabled

   Once staticIpsEnabled is on and the cluster has been applied, here is the procedure to find the IPs in the GCP console:

   1. Select the project that hosts your Qovery cluster.
   2. Go to VPC network then External IP addresses.
   3. Filter by the region where your cluster is deployed.
   4. Look for the two reserved addresses named ${vpc_name}-nat-1 and ${vpc_name}-nat-2, with type External and status In use by your Cloud NAT gateway.

   You can also list them from the command line:

   gcloud compute addresses list \
     --project <your-gcp-project> \
     --filter="name~^.*-nat-"
   

   Use those two IPs as the source addresses to allowlist with your third-party providers.

   On AWS, NAT Gateways always require Elastic IPs (this is the only mode AWS supports), so Qovery-managed EKS clusters have stable egress IPs by default. You can find them in the AWS console under VPC then Elastic IP addresses. See Static IP on EKS for details.

   Use your existing VPC

   Use existing VPC

   You can opt to use your own VPC instead of the one provided by Qovery by switching VPC mode to Deploy on my existing VPC.

   In GCP you have two VPC modes: Automatic or Custom.

   If you are using an automatic or a custom VPC, you have to set:

   • Your VPC Name
   • External project id (optional): by default, the project id used is the one specified in the credentials file. But if your VPC is defined in another GCP project, you have to specify the Project id.

   In addition if you are using a custom VPC, you have to set:

   • Your Subnet range name (https://console.cloud.google.com/networking/networks/details/<your-vpc>?project=<your-project>&pageTab=SUBNETS)

   You can also specify (optional):

   • Pod ipv4 address range name
   • Additional cluster pod ipv4 ranges names (separated with a comma)
   • Ipv4 service range name

   For these ranges, you have to create Secondary IPv4 ranges inside your subnet.

3. Create and Install

   In the Ready to install your cluster window, check that the services needed to install your cluster are correct.

   You can now press the Create and Install button.

   Your cluster is now displayed in your organization settings, featuring the Installing... status (orange status). Once your cluster is properly installed, its status turns to green and you will be able to deploy your applications on it.

   You can follow the execution of the action via the cluster status and/or by accessing the Cluster Logs

Managing your Cluster Settings

To manage the settings of an existing cluster:

1. Open Qovery Console

   Open your Qovery Console.

2. Navigate to Cluster Page

   On your organization overview, go on the Clusters page.

3. Access Cluster Settings

   To access your cluster settings, click on your cluster card and then go on Settings tab.

Below you can find a description of each section

General

The General tab allows you to define high-level information on your cluster:

Item	Description
Cluster Name	To edit the name of your cluster.
Description	To enter or edit the description of your cluster.
Production Cluster	To enter or edit the production flag of your cluster.

Credentials

Here you can manage here the cloud provider credentials associated with your cluster.

If you need to change the credentials:

• generate a new set of credentials on your cloud provider (Procedure for GCP account)
• create the new credential on the Qovery by opening the drop-down and selecting “New Credentials”

Once created and associated, you need to update your cluster to apply the change.

Mirroring registry

In this tab, you will see that a container registry already exist (called registry-{$UIID}). This is your cloud provider container registry used by Qovery to manage the deployment of your applications by mirroring the docker images.

The credentials configured on this registry are the one used to create the cluster. But you can still update them if you prefer to manage them separately (dedicated pair of creds just to access the registry).

Check this link for more information.

Network

The Network tab in your cluster settings allows you to check if the Static IP, Deploy on existing VPC features are enabled on your cluster. The enabled features cannot be changed after the creation of the cluster.