# Enable Redpanda SQL on a BYOVPC Cluster on AWS > 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 AWS 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-aws 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-aws.adoc page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/sql/pages/get-started/enable-sql-byovpc-aws.adoc description: Provision SQL-specific AWS resources with Terraform and enable the Redpanda SQL engine on a new or existing BYOVPC cluster on AWS. page-topic-type: how-to personas: platform_admin learning-objective-1: Provision SQL-specific AWS 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 AWS 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 AWS account for BYOVPC clusters. You must provision the SQL-specific AWS 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 AWS 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 AWS. For an existing cluster: a deployed [BYOVPC cluster on AWS](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/aws/vpc-byo-aws/). - The [Redpanda BYOVPC Terraform module](https://registry.terraform.io/modules/redpanda-data/redpanda-byovpc/aws/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/aws` module configuration, set `enable_redpanda_sql = true`: ```hcl module "redpanda_byovpc" { source = "redpanda-data/redpanda-byovpc/aws" # ... existing configuration ... enable_redpanda_sql = true } ``` Apply the updated configuration: ```bash terraform apply ``` This creates three SQL-specific resources in your AWS account: - An IAM role and instance profile for SQL compute nodes - An S3 bucket for SQL data storage (versioning disabled) - A security group for SQL nodes After applying, Terraform outputs the following values. Supply these ARNs to the cluster when you enable SQL. | Module output | Description | | --- | --- | | rpsql_node_group_instance_profile_arn | ARN of the IAM instance profile for SQL nodes | | rpsql_cloud_storage_bucket_arn | ARN of the S3 bucket for SQL data storage | | rpsql_security_group_arn | ARN of the security group for SQL nodes | If you plan to query Iceberg topics backed by AWS Glue, this module can also provide the Glue catalog policy that the SQL engine needs. See [Grant Glue access for Iceberg queries](#grant-glue-access). ## [](#enable-redpanda-sql)Enable Redpanda SQL Use the Terraform provider, Cloud API, or Cloud Console 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_node_group_instance_profile`, `rpsql_cloud_storage_bucket`, `rpsql_security_group`) are immutable while SQL is enabled. To change any of these resources, 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. For the base `redpanda_cluster` configuration, see [Create a BYOVPC Cluster on AWS](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/aws/vpc-byo-aws/). ```hcl resource "redpanda_cluster" "cluster" { # ... existing BYOVPC cluster configuration ... customer_managed_resources = { aws = { # ... existing BYOVPC customer-managed resources ... rpsql_node_group_instance_profile = { arn = module.redpanda_byovpc.rpsql_node_group_instance_profile_arn } rpsql_cloud_storage_bucket = { arn = module.redpanda_byovpc.rpsql_cloud_storage_bucket_arn } rpsql_security_group = { arn = module.redpanda_byovpc.rpsql_security_group_arn } } } 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 ARNs 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. Include your existing BYOVPC customer-managed resource fields (see [Create a BYOVPC Cluster on AWS](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/aws/vpc-byo-aws/)) and add the SQL customer-managed resource fields and `rpsql` block: ```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_AWS", "region": "", "zones": ["", "", ""], "network_id": "", "throughput_tier": "", "resource_group_id": "", "customer_managed_resources": { "aws": { "rpsql_node_group_instance_profile": {"arn": ""}, "rpsql_cloud_storage_bucket": {"arn": ""}, "rpsql_security_group": {"arn": ""} } }, "rpsql": { "enabled": true, "replicas": , "zones": [""] } } }' ``` Replace the placeholders with your own values: - ``, ``, ``: The corresponding outputs from the Terraform module. - ``: 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: ```bash curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" ``` When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. ### [](#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: ```hcl resource "redpanda_cluster" "cluster" { # ... existing BYOVPC cluster configuration ... customer_managed_resources = { aws = { # ... existing BYOVPC customer-managed resources ... rpsql_node_group_instance_profile = { arn = module.redpanda_byovpc.rpsql_node_group_instance_profile_arn } rpsql_cloud_storage_bucket = { arn = module.redpanda_byovpc.rpsql_cloud_storage_bucket_arn } rpsql_security_group = { arn = module.redpanda_byovpc.rpsql_security_group_arn } } } 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 ARNs from the Terraform module outputs, 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). 2. Locate the cluster ID in the **Details** section of the cluster overview in the Cloud Console. 3. 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 SQL customer-managed resources in the body. Replace `{cluster.id}` with your cluster ID: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.enabled,rpsql.replicas,rpsql.zones,customer_managed_resources.aws.rpsql_node_group_instance_profile.arn,customer_managed_resources.aws.rpsql_security_group.arn,customer_managed_resources.aws.rpsql_cloud_storage_bucket.arn" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer_managed_resources": { "aws": { "rpsql_node_group_instance_profile": {"arn": ""}, "rpsql_cloud_storage_bucket": {"arn": ""}, "rpsql_security_group": {"arn": ""} } }, "rpsql": { "enabled": true, "replicas": , "zones": [""] } }' ``` Replace the placeholders with your own values: - ``, ``, ``: The corresponding outputs from the Terraform module. - ``: Initial number of SQL compute nodes (minimum 1, maximum 9). - `` (optional): The availability zone for the SQL engine. 4. 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: ```bash curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" ``` When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. ## [](#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. ## [](#grant-glue-access)Grant Glue 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 an AWS Glue catalog, the SQL engine needs Glue permissions. On a BYOVPC cluster, the `redpanda-data/redpanda-byovpc/aws` module can’t attach these automatically, because the SQL engine’s IAM role doesn’t exist until the cluster is created. After the cluster is running: 1. Set `enable_glue_iceberg_catalog = true` on the `redpanda_byovpc` module. This widens the agent permissions boundary and exports a Glue policy as `glue_iceberg_policy_arn`. 2. Attach that policy to **both** of the following roles from the workspace that creates the cluster: - `redpanda-cloud-storage-manager-`: the broker role that writes topic data to the Glue catalog. Without this attachment, nothing is written to Glue, so there is nothing to query. - `redpanda--redpanda-oxla-cluster`: the SQL engine role that reads the catalog to run queries. ```hcl resource "aws_iam_role_policy_attachment" "glue_storage_manager" { role = "redpanda-cloud-storage-manager-${redpanda_cluster.cluster.id}" policy_arn = module.redpanda_byovpc.glue_iceberg_policy_arn } resource "aws_iam_role_policy_attachment" "glue_rpsql_engine" { role = "redpanda-${redpanda_cluster.cluster.id}-redpanda-oxla-cluster" policy_arn = module.redpanda_byovpc.glue_iceberg_policy_arn } ``` Without both attachments, `REFRESH` of the Glue-backed catalog fails with a permissions error. For the full AWS Glue catalog configuration, see [Query Iceberg Topics using AWS Glue](https://docs.redpanda.com/cloud-data-platform/manage/iceberg/iceberg-topics-aws-glue/). ## [](#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 three SQL customer-managed resource fields (`rpsql_node_group_instance_profile`, `rpsql_cloud_storage_bucket`, and `rpsql_security_group`) from `customer_managed_resources.aws`. 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 = { aws = { # ... 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`, using an explicit `update_mask`. Replace `{cluster.id}` with your cluster ID: ```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}}' ``` The request returns the ID of a long-running operation. Poll [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) until the operation completes. Disabling SQL does not delete the SQL-specific AWS resources (IAM instance profile, S3 bucket, and security group); they remain in your account, 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.