# Enable Redpanda SQL on a BYOVPC Cluster on GCP > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt) --- title: Enable Redpanda SQL on a BYOVPC Cluster on GCP latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.104.0 latest-redpanda-tag: v26.2.1 docname: get-started/enable-sql-byovpc-gcp page-component-name: cloud-data-platform page-version: master page-component-version: master page-component-title: Cloud page-relative-src-path: get-started/enable-sql-byovpc-gcp.adoc page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/sql/pages/get-started/enable-sql-byovpc-gcp.adoc description: Provision SQL resources with the Redpanda BYOVPC Terraform module and enable Redpanda SQL on a new or existing BYOVPC cluster on GCP. page-topic-type: how-to personas: platform_admin learning-objective-1: Provision SQL-specific GCP resources using the Redpanda BYOVPC Terraform module learning-objective-2: Enable Redpanda SQL on a new or existing BYOVPC cluster by supplying customer-managed resources learning-objective-3: Verify that the SQL engine is running and ready to accept connections page-git-created-date: "2026-08-03" page-git-modified-date: "2026-08-06" --- > ❗ **IMPORTANT** > > BYOVPC/BYOVNet is an add-on feature that requires Premium support. To unlock this feature for your account, contact your Redpanda account team or [Redpanda Sales](https://www.redpanda.com/price-estimator). Enable Redpanda SQL on a Bring Your Own Virtual Private Cloud (BYOVPC) cluster on GCP so you can query streaming data in Redpanda topics using standard PostgreSQL syntax. You can enable SQL when creating a new BYOVPC cluster or on an existing one. Unlike standard BYOC clusters, Redpanda does not create resources in your GCP project for BYOVPC clusters. You must provision the SQL-specific GCP resources yourself and supply them to the cluster as customer-managed resources (CMRs) before enabling the SQL engine. You can enable SQL on an existing cluster from the Cloud Console, the Terraform provider, or the Cloud API. To enable SQL when you create a new cluster, use the Terraform provider or the Cloud API. After reading this page, you will be able to: - Provision SQL-specific GCP resources using the Redpanda BYOVPC Terraform module - Enable Redpanda SQL on a new or existing BYOVPC cluster by supplying customer-managed resources - Verify that the SQL engine is running and ready to accept connections ## [](#prerequisites)Prerequisites - For a new cluster: a BYOVPC network on GCP. For an existing cluster: a deployed [BYOVPC cluster on GCP](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/gcp/vpc-byo-gcp/). - The [Redpanda BYOVPC Terraform module](https://registry.terraform.io/modules/redpanda-data/redpanda-byovpc/gcp/latest) and [Terraform](https://developer.hashicorp.com/terraform) version 1.8.5 or later, to provision the SQL resources. - If you enable SQL with Terraform: the [Redpanda Terraform provider](https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs) version `2.2.0` or later, configured with valid credentials. - Admin permissions in your Redpanda Cloud organization on [usage-based billing](https://docs.redpanda.com/cloud-data-platform/billing/billing/). If using the Cloud API, a valid [bearer token](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#bearer-token) with permission to update clusters. See [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication). - To verify the engine after enabling it: `psql` version 16 or later on a host inside the cluster’s VPC. A BYOVPC cluster is private, so the SQL endpoint is not reachable from outside the VPC. ## [](#provision-sql-resources-with-terraform)Provision SQL resources with Terraform In your `redpanda-data/redpanda-byovpc/gcp` module configuration, set `enable_redpanda_sql = true`: ```hcl module "redpanda_gcp" { source = "redpanda-data/redpanda-byovpc/gcp" # ... existing configuration ... enable_redpanda_sql = true } ``` Apply the updated configuration: ```bash terraform apply ``` This creates the SQL-specific GCP resources that the base BYOVPC provisioning does not, and grants them the IAM roles and Workload Identity bindings that the SQL engine needs: - A GCP service account for the SQL compute nodes, which reads and writes the SQL data-storage bucket. - A GCP service account for the SQL API, which accesses Secret Manager secrets under the SQL prefix. - A GCS bucket for SQL data storage. - A Secret Manager prefix: a string namespace (not a resource) that reserves where Redpanda SQL Iceberg catalog credentials are stored. After applying, Terraform outputs the following values. Supply them to the cluster when you enable SQL. | Module output | Description | | --- | --- | | redpanda_sql_service_account_email | Email of the SQL compute-node service account | | redpanda_sql_api_service_account_email | Email of the SQL API service account | | redpanda_sql_storage_bucket_name | Name of the GCS bucket for SQL data storage | | redpanda_sql_secret_manager_prefix | Secret Manager prefix for SQL Iceberg catalog credentials | ## [](#enable-redpanda-sql)Enable Redpanda SQL Use the Cloud Console (existing clusters only), the Terraform provider, or the Cloud API to enable the SQL engine. The steps differ depending on whether you are creating a new cluster or updating an existing one. > ❗ **IMPORTANT** > > The SQL customer-managed resources (`rpsql_service_account`, `rpsql_api_service_account`, `rpsql_cloud_storage_bucket`, and `rpsql_secret_manager_prefix`) are immutable while SQL is enabled. To change any of them, you must first disable SQL. > 📝 **NOTE** > > Redpanda SQL deploys to a single [availability zone](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#availability-zone-az) (AZ), even when the cluster spans multiple AZs. In the `rpsql` block, set `zones` to one of the cluster’s zones. If you omit it, Redpanda uses the cluster’s first zone. The AZ is locked while Redpanda SQL is enabled. To move the SQL engine to a different AZ, disable and re-enable Redpanda SQL. ### [](#on-a-new-cluster)On a new cluster #### Terraform Creating a BYOVPC cluster with Redpanda SQL requires the Redpanda Terraform provider version `2.2.0` or later. Add the SQL customer-managed resource fields and the `rpsql` block to the `redpanda_cluster` resource in your BYOVPC Terraform configuration, mapping the module outputs to the customer-managed resource fields. For a complete `redpanda_cluster` and `redpanda_network` example, see the [GCP BYOVPC example](https://github.com/redpanda-data/terraform-provider-redpanda/blob/main/examples/byovpc/gcp/main.tf) in the Redpanda Terraform provider repository. ```hcl resource "redpanda_cluster" "cluster" { # ... existing BYOVPC cluster configuration ... customer_managed_resources = { gcp = { # ... existing BYOVPC customer-managed resources ... rpsql_service_account = { email = module.redpanda_gcp.redpanda_sql_service_account_email } rpsql_api_service_account = { email = module.redpanda_gcp.redpanda_sql_api_service_account_email } rpsql_cloud_storage_bucket = { name = module.redpanda_gcp.redpanda_sql_storage_bucket_name } rpsql_secret_manager_prefix = module.redpanda_gcp.redpanda_sql_secret_manager_prefix } } rpsql = { enabled = true replicas = 1 zones = [""] } } ``` Replace the placeholders with your own values: - `replicas`: Initial number of SQL compute nodes (minimum 1, maximum 9). - `` (optional): The availability zone for the SQL engine. Apply the configuration: ```bash terraform apply ``` #### Cloud API When creating a new BYOVPC cluster using the Cloud API, include the SQL customer-managed resource fields and the `rpsql` configuration in the [`POST /v1/clusters`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster) payload alongside your existing BYOVPC customer-managed resources. 1. [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication). 2. Make a [`POST /v1/clusters`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster) request. The following payload shows only the SQL-specific fields. Include them alongside the full set of BYOVPC customer-managed resources your cluster requires, or the request fails. For the complete set, see the [GCP BYOVPC example](https://github.com/redpanda-data/terraform-provider-redpanda/blob/main/examples/byovpc/gcp/main.tf). Replace the placeholder values with your own: ```bash curl -X POST "https://api.redpanda.com/v1/clusters" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cluster": { "name": "", "type": "TYPE_BYOC", "cloud_provider": "CLOUD_PROVIDER_GCP", "region": "", "zones": ["", "", ""], "network_id": "", "throughput_tier": "", "resource_group_id": "", "customer_managed_resources": { "gcp": { "rpsql_service_account": {"email": ""}, "rpsql_api_service_account": {"email": ""}, "rpsql_cloud_storage_bucket": {"name": ""}, "rpsql_secret_manager_prefix": "" } }, "rpsql": { "enabled": true, "replicas": , "zones": [""] } } }' ``` Replace the placeholders with your own values: - The four `rpsql_*` values: the service account emails, bucket name, and Secret Manager prefix from [Provision SQL resources with Terraform](#provision-sql-resources-with-terraform). - ``: Initial number of SQL compute nodes (minimum 1, maximum 9). - `` (optional): The availability zone for the SQL engine. 3. The request returns the ID of a long-running operation. Poll the [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint until the operation completes. ### [](#on-an-existing-cluster)On an existing cluster #### Terraform Enabling Redpanda SQL on an existing BYOVPC cluster with Terraform requires the Redpanda Terraform provider version `2.2.0` or later. On earlier versions, adding the SQL customer-managed resources replaces the cluster. Add the SQL customer-managed resource fields and the `rpsql` block to the `redpanda_cluster` resource in your BYOVPC Terraform configuration, mapping the module outputs to the customer-managed resource fields: ```hcl resource "redpanda_cluster" "cluster" { # ... existing BYOVPC cluster configuration ... customer_managed_resources = { gcp = { # ... existing BYOVPC customer-managed resources ... rpsql_service_account = { email = module.redpanda_gcp.redpanda_sql_service_account_email } rpsql_api_service_account = { email = module.redpanda_gcp.redpanda_sql_api_service_account_email } rpsql_cloud_storage_bucket = { name = module.redpanda_gcp.redpanda_sql_storage_bucket_name } rpsql_secret_manager_prefix = module.redpanda_gcp.redpanda_sql_secret_manager_prefix } } rpsql = { enabled = true replicas = 1 zones = [""] } } ``` Replace the placeholders with your own values: - `replicas`: Initial number of SQL compute nodes (minimum 1, maximum 9). - `` (optional): The availability zone for the SQL engine. Apply the configuration: ```bash terraform apply ``` #### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com) and open your BYOVPC cluster. 2. From the navigation menu, select **Dataplane settings**. 3. On the **Cluster** tab, find the **Redpanda SQL** row and click **Edit**. 4. In the dialog, enter the two service account emails, the GCS bucket name, and the Secret Manager prefix that you provisioned, then use the **RPU** slider to set the compute size. 5. Click **Enable Redpanda SQL engine**. #### Cloud API > ❗ **IMPORTANT** > > The `PATCH` request must use an explicit leaf-path `update_mask` that lists each field you set, including each SQL customer-managed resource. Redpanda silently ignores a grouped mask (for example, `customer_managed_resources`), so the operation returns `STATE_COMPLETED` but SQL stays disabled. 1. [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication) and obtain a bearer token. 2. Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request. Set the `update_mask` query parameter to the explicit leaf paths, and provide the `rpsql` block and the four SQL customer-managed resources in the body. Replace `{cluster.id}` and the placeholder values with your own: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.enabled,rpsql.replicas,rpsql.zones,customer_managed_resources.gcp.rpsql_service_account.email,customer_managed_resources.gcp.rpsql_api_service_account.email,customer_managed_resources.gcp.rpsql_cloud_storage_bucket.name,customer_managed_resources.gcp.rpsql_secret_manager_prefix" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer_managed_resources": { "gcp": { "rpsql_service_account": {"email": ""}, "rpsql_api_service_account": {"email": ""}, "rpsql_cloud_storage_bucket": {"name": ""}, "rpsql_secret_manager_prefix": "" } }, "rpsql": { "enabled": true, "replicas": , "zones": [""] } }' ``` Replace the placeholders with your own values: - ``: Initial number of SQL compute nodes (minimum 1, maximum 9). - `` (optional): The availability zone for the SQL engine. - The four `rpsql_*` values: the service account emails, bucket name, and Secret Manager prefix from [Provision SQL resources with Terraform](#provision-sql-resources-with-terraform). A successful enable request returns a long-running operation that stays `STATE_IN_PROGRESS` for roughly 15 to 30 minutes while the SQL node group provisions. 3. Poll the [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint until the operation completes: ```bash curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" ``` ## [](#verify-the-sql-engine-is-running)Verify the SQL engine is running After you enable Redpanda SQL, a **Redpanda SQL** tile appears in the cluster overview. The tile shows the engine status, active sessions, queries per minute, and node count. When the **Nodes** indicator shows all nodes as ready (for example, **1/1**), the engine is provisioned and accepting connections. Provisioning can take up to 30 minutes. For the API flow, poll the long-running operation until it returns `STATE_COMPLETED`. To verify the SQL engine is running, connect with `psql` version 16 or later, or another PostgreSQL client, using the connection details on the **SQL** tab under **Connection details**. Because a BYOVPC cluster is private, run the client from a host inside the cluster’s VPC. You can also query data directly using the [SQL editor](https://docs.redpanda.com/cloud-data-platform/sql/query-data/sql-editor/) in the navigation menu. ## [](#lakehouse-access-for-iceberg-queries)Lakehouse access for Iceberg queries To run [Iceberg queries](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-iceberg-topics/) against topics backed by a GCP Lakehouse (formerly BigLake) REST catalog, the SQL engine needs access to the catalog. On a BYOVPC cluster, the `redpanda-data/redpanda-byovpc/gcp` module grants this automatically when you enable Redpanda SQL (`enable_redpanda_sql = true`), so no additional IAM step is required. For the full Lakehouse catalog configuration, see [Use Iceberg Topics with GCP Lakehouse](https://docs.redpanda.com/cloud-data-platform/manage/iceberg/iceberg-topics-gcp-biglake/). ## [](#disable-redpanda-sql)Disable Redpanda SQL > ⚠️ **WARNING** > > Disabling Redpanda SQL tears down the SQL compute engine and clears its catalog state (catalog metadata, table mappings, and role/grant data). In-flight queries fail when SQL is disabled. If you disable Redpanda SQL, Redpanda topic data, Schema Registry subjects, and any Iceberg-committed history for Iceberg-enabled topics are not affected. The Redpanda cluster itself continues to run normally, and only the SQL engine and its associated state are removed. Re-enabling SQL on the same cluster provisions a fresh engine. Redpanda does not restore prior catalog state, table mappings, or grants. You must re-create catalogs, tables, and grants after re-enabling. Disable SQL from the Cloud Console, or with the Terraform provider or the Cloud API. ### Terraform Set `rpsql.enabled` to `false` in the `redpanda_cluster` resource, and remove the four SQL customer-managed resource fields (`rpsql_service_account`, `rpsql_api_service_account`, `rpsql_cloud_storage_bucket`, and `rpsql_secret_manager_prefix`) from `customer_managed_resources.gcp`. The control plane clears these resources when SQL is disabled, so leaving them in your configuration causes permanent drift. ```hcl resource "redpanda_cluster" "cluster" { # ... existing BYOVPC cluster configuration ... customer_managed_resources = { gcp = { # ... existing BYOVPC customer-managed resources ... # Remove the rpsql_* customer-managed resource fields. } } rpsql = { enabled = false } } ``` Apply the change: ```bash terraform apply ``` ### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com) and open your cluster. 2. From the navigation menu, select **Dataplane settings**. 3. On the **Cluster** tab, find the **Redpanda SQL** row and click **Edit**. 4. In the **Edit Redpanda SQL engine** dialog, click **Disable**. ### Cloud API Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request with `rpsql.enabled` set to `false`: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.enabled" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql": {"enabled": false}}' ``` Poll the [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint until the operation completes. Disabling SQL does not delete the SQL-specific GCP resources (service accounts and bucket). These resources remain in your project, and you can reuse them if you re-enable SQL. To remove them, first wait until the disable operation completes, then set `enable_redpanda_sql = false` in the Terraform module and run `terraform apply`, or run `terraform destroy` to remove all BYOVPC resources. Removing these resources while the cluster still references them can cause the apply to fail. ## [](#next-steps)Next steps - [Scale the SQL engine](https://docs.redpanda.com/cloud-data-platform/sql/get-started/deploy-sql-cluster/#scale-redpanda-sql): Adjust compute size after enabling SQL. - [Quickstart](https://docs.redpanda.com/cloud-data-platform/sql/get-started/sql-quickstart/): Connect to Redpanda SQL with `psql` and run your first query. - [Authenticate to Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/connect-to-sql/authenticate/): Connect with an OIDC bearer token, OIDC client credentials, or a SCRAM password.