Set up PlanetScale Managed in GCP
(Updated )
Overview
The following guide will walk you through setting up a PlanetScale Managed cluster in your Google Cloud Platform (GCP) organization. If you have any questions while working through this documentation, contact your PlanetScale Solutions Engineer for assistance.
Note
This guide is only intended for PlanetScale Managed customers currently working with the PlanetScale team. You cannot set PlanetScale Managed up on your own without PlanetScale enabling it for your organization. If you are interested in PlanetScale Managed, please contact us.
Step 1: Account requirements
A new GCP project must be set up following this documentation to successfully bootstrap a new PlanetScale Managed cluster. To proceed with this guide, an existing GCP organization and an active Cloud Billing account are required.
Further information on creating GCP organizations can be found in the creating and managing organization resources documentation.
Dedicated GCP project
PlanetScale Managed requires the use of a standalone project in GCP. This project should not have any existing resources running within it, as PlanetScale will request a set of permissions as defined in step 2.
Modification of accounts
Once the GCP project is handed over to PlanetScale via granting IAM permissions, it should not be modified. Issues caused by modifications of the GCP project or its resources void the PlanetScale Managed SLA. Contact support@planetscale.com to discuss configuration changes or customization.
Step 2: Bootstrap GCP project
Before setting up the IAM roles, you must create a new GCP project, assign it to a GCP Billing Account, and enable the Compute Engine API.
Create a new GCP project
A new GCP project can be created via the command line if the gcloud SDK is installed and configured:
gcloud projects create <project-name>
Projects can also be created through the GCP console.
Further information on creating GCP projects is available in the Google Cloud Resource Manager documentation.
Assign the new project to a GCP Billing Account
Next, assign the new project to a GCP Billing Account inside your organization. The account to use will depend on your organization and its policies.
Note
If the user who created the project has the Billing Administrator role, the project may already have billing enabled. Please review the settings to ensure it is attached to the intended Billing Account.
Further information on assigning projects to Billing Accounts is available here.
Enable Compute Engine API
The Compute Engine API must be enabled on the new project. This can be done via the command line:
gcloud services enable compute.googleapis.com --project "<project-name>"
Further information on enabling an API is available here.
Assign IAM Roles
For PlanetScale to provision resources in the project, the following IAM roles must be granted to the following service accounts:
terraform-planner@planetscale-operations.iam.gserviceaccount.com
service account:roles/viewer
- Viewer
terraform-runner@planetscale-operations.iam.gserviceaccount.com
service account:roles/cloudkms.admin
- Cloud KMS Adminroles/compute.admin
- Compute Adminroles/container.admin
- Kubernetes Engine Adminroles/container.clusterAdmin
- Kubernetes Engine Cluster Adminroles/iam.roleAdmin
- IAM Role Adminroles/iam.securityAdmin
- Security Adminroles/iam.serviceAccountAdmin
- Service Account Adminroles/iam.serviceAccountKeyAdmin
- Service Account Key Adminroles/logging.admin
- Logging Adminroles/serviceusage.serviceUsageAdmin
- Service Usage Adminroles/storage.admin
- Storage Adminroles/viewer
- Viewer
These can be assigned using the gcloud
command line tool:
gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-planner@planetscale-operations.iam.gserviceaccount.com --role roles/viewer gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/cloudkms.admin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/compute.admin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/container.admin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/container.clusterAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/iam.roleAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/iam.securityAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/iam.serviceAccountAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/iam.serviceAccountKeyAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/logging.admin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/serviceusage.serviceUsageAdmin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/storage.admin gcloud projects add-iam-policy-binding "<project-name>" --member serviceAccount:terraform-runner@planetscale-operations.iam.gserviceaccount.com --role roles/viewer
Alternatively, they can be assigned through the GCP console under the project's "IAM & Admin > IAM" section of the GCP console.
Further information on assigning IAM roles to projects is available in the GCP IAM documentation.
Step 3: Requesting an initial quota increase
By default, GCP provides most new projects with quotas that are too small for PlanetScale's initial provisioning process.
Submit increase requests for the following quotas. This must be done for all regions in which PlanetScale will provision resources. Depending on your organization, the default quotas may already be at or above these levels:
compute.googleapis.com/ssd_total_storage
: 10000 GBcompute.googleapis.com/disks_total_storage
: 10000 GBcompute.googleapis.com/n2_cpus
: 256compute.googleapis.com/n2d_cpus
: 256compute.googleapis.com/cpus_all_regions
: 256compute.googleapis.com/instances
: 100
You can submit GCP quota increase requests via the project's "IAM & Admin > Quotas" section of the GCP console. Copy and paste the quota metrics from above into the table to search for them in the quota interface.
While PlanetScale does not immediately consume all requested resources, we recommend these values to ensure enough resources are available for auto-scaling, growth, and upgrades.
PlanetScale will request the quota increase if the customer does not but recommends that the customer initiate the request due to an unknown turnaround time for quota requests.
Further information on requesting and managing GCP quotas can be found in the Google Cloud Allocation quotas documentation.
Step 4: Initiating the provisioning process
Once the GCP project has been created, the IAM roles have been applied, and the quota increases have been granted, notify your Solutions Engineer, providing them the following information:
- The name of the organization that you have created on
app.planetscale.com
. - The GCP project name
- A confirmation of the region(s) that you have chosen for the deployment to reside in. The canonical list of regions can be found in the Google Cloud Regions and Zones documentation.
Once your Solutions Engineer receives this information, they will forward it to the team responsible for provisioning your deployment. Provisioning the deployment takes PlanetScale, on average, one business day.
Once the deployment has been provisioned, your Solutions Engineer will contact you to confirm that your team can start creating databases.
Note
Optionally, PlanetScale can connect you to your databases via GCP Private Service Connect with PlanetScale Managed. See the GCP Private Service Connect documentation for more information on establishing a Private Service Connect connection.
Need help?
Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.