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

# 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

<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. Go to **Clusters** tab
    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://setup.qovery.com/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.
    </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`

    <Frame>
      <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="Open Google Cloud Shell" width="1564" height="722" data-path="images/gcp-credentials/cloud-shell.png" />
    </Frame>
  </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>

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

    The installation script automatically assigns the minimum required roles to the service account.
  </Accordion>

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

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

### Create the Cluster

<Steps>
  <Step title="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](/getting-started/installation/gcp#connect-your-gcp-account).

    To confirm, click `Next`.
  </Step>

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

    <Warning>
      These options can only be configured during cluster creation and cannot be modified later.
    </Warning>

    <Tabs>
      <Tab title="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 Nats
        * Static IPs
        * Routers

        Once set up, here is the procedure to find your static IP addresses on `GCP`:

        * On your GCP account, select the IP addresses service.
        * In the list you will find your static IP used by your cluster router.

        <Info>
          If you work in a sensitive business area such as financial technology, enabling the **Static IP** feature can help fulfil the security requirements of some of the external services you use, therefore making it easier for you to get whitelisted by them.
        </Info>
      </Tab>

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

        <Info>
          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.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="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](/configuration/clusters#logs)
  </Step>
</Steps>

## Managing your Cluster Settings

To manage the settings of an existing cluster:

<Steps>
  <Step title="Open Qovery Console">
    Open your [Qovery Console](https://console.qovery.com).
  </Step>

  <Step title="Navigate to Cluster Page">
    On your organization overview, go on the Clusters page.
  </Step>

  <Step title="Access Cluster Settings">
    To access your cluster settings, click on your cluster card and then go on Settings tab.
  </Step>
</Steps>

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](/installation/gcp#connect-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](/configuration/clusters#updating-a-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](/configuration/deployment/image-mirroring) for more information.

### Network

The `Network` tab in your cluster settings allows you to check if the [**Static IP**](#static-ip), [**Deploy on existing VPC**](#use-existing-vpc) features are enabled on your cluster. The enabled features cannot be changed after the creation of the cluster.