Sign in|Get started
Navigation

Overview

The following guide will walk you through setting up a PlanetScale Managed cluster in your Amazon Web Services (AWS) organization. If you have any questions while working through this documentation, contact your PlanetScale Solutions Engineer for assistance.

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 AWS sub-account must be set up following this documentation to successfully bootstrap a new PlanetScale Managed cluster. An existing AWS organization is required to proceed with this guide.

Dedicated sub-account

PlanetScale Managed requires the use of a standalone sub-account in Amazon Web Services. This account should not have any existing resources running within it.

The creating a member account in your organization document covers how to create a new sub-account in an existing AWS organization. The document also includes the required permissions to create a sub-account in your AWS organization.

Modification of accounts

Once the sub-account is handed over to PlanetScale via granting IAM permissions, it should not be modified. Issues caused by modifications of the sub-account or its resources void the PlanetScale Managed SLA. Contact support@planetscale.com to discuss configuration changes or customization.

Recommendations

During the initial provisioning process, PlanetScale applies the following recommendations to the AWS sub-account but still recommends that a customer enable them once the sub-account has been created:

PCI Compliance

Customers of PlanetScale Managed should ensure the following additional configurations are applied and maintained to ensure that the customer environment remains PCI-compliant for the storage and protection of cardholder data:

Local Authentication Parameters

PlanetScale does not set specific authentication parameters for accessing the customer database during initial provisioning. To maintain compliance with PCI requirements 8.2 and 8.3, it is the customer's responsibility to set the following authentication parameters in line with the respective requirements set by the PCI Data Security Standards:

Log Level Configuration

The PlanetScale-controlled AWS sub-account will be pre-configured by PlanetScale with AWS CloudTrail enabled and configured to emit logging events from the customer application. As PlanetScale does not retain access to these logs after the account is configured, to maintain compliance with PCI requirement 10.2.1.1 (audit logs capture all individual user access to cardholder data), it is the customer’s responsibility to ensure this logging remains enabled and to regularly review and verify the following events:

As a best practice, it is recommended that these logs be captured and continuously analyzed by a Security Information & Event Management (SIEM) platform.

Step 2: Cross-account key management

PlanetScale supports using Amazon Web Services Key Management Service with cross-account IAM permissions. This enables the isolation of keys so the infrastructure operated by PlanetScale has limited access to symmetric keys. AWS Elastic Block Storage and S3 are the services used with the key in question.

In the KMS key's account, apply the baseline key policy:

{
  "Sid": "Allow PlanetScale Managed to use this key",
  "Effect": "Allow",
  "Principal": {
    "AWS": ["[PlanetScale Managed sub-account ID]"]
  },
  "Action": ["kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey"],
  "Resource": "*"
}

Additional key policy is required to allow the sub-account to create persistent resources with the KMS key:

{
  "Sid": "Allow attachment of persistent resources for PlanetScale Managed",
  "Effect": "Allow",
  "Principal": {
    "AWS": "[PlanetScale Managed sub-account ID]"
  },
  "Action": ["kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant"],
  "Resource": "*",
  "Condition": {
    "Bool": {
      "kms:GrantIsForAWSResource": "true"
    }
  }
}

Once these policies are attached to the key, provide PlanetScale with the full ARN of the KMS key. PlanetScale will attach relevant IAM policies to roles that require using the key.

Step 3: Bootstrap with CloudFormation

We've created a CloudFormation template to complete the setup of required permissions in your AWS sub-account.

Save the following as planetscale-bootstrap.json:

{
  "Resources": {
    "GrantTerraformRunnerAccess": {
      "Type": "AWS::IAM::Role",
      "DeletionPolicy": "Retain",
      "Properties": {
        "RoleName": "TerraformRunner",
        "ManagedPolicyArns": ["arn:aws:iam::aws:policy/AdministratorAccess"],
        "AssumeRolePolicyDocument": {
          "Statement": [
            {
              "Effect": "Allow",
              "Principal": {
                "AWS": [
                  "arn:aws:iam::313573332105:role/aws-reserved/sso.amazonaws.com/AWSReservedSSO_Ops_feec88bc3aad314d"
                ]
              },
              "Action": ["sts:AssumeRole"]
            }
          ]
        }
      }
    },
    "GrantOpsAccess": {
      "Type": "AWS::IAM::Role",
      "DeletionPolicy": "Retain",
      "Properties": {
        "RoleName": "PlanetscaleOps",
        "ManagedPolicyArns": ["arn:aws:iam::aws:policy/AdministratorAccess"],
        "AssumeRolePolicyDocument": {
          "Statement": [
            {
              "Effect": "Allow",
              "Principal": {
                "AWS": [
                  "arn:aws:iam::867309876077:role/aws-reserved/sso.amazonaws.com/AWSReservedSSO_Ops_f1d00b216d43a785"
                ]
              },
              "Action": ["sts:AssumeRole"]
            }
          ]
        }
      }
    }
  }
}

Next, apply the CloudFormation template as a new stack:

aws cloudformation create-stack --stack-name planetscale-bootstrap \
  --template-body file://planetscale-bootstrap.json \
  --capabilities CAPABILITY_NAMED_IAM

Let your Solutions Engineer know once the new stack reaches the CREATED state in AWS.

Step 4: Requesting an initial quota increase

By default, AWS may provision new sub-accounts with EC2 On-Demand quotas that may be too small for:

Although the PlanetScale Support and Operations teams will have the ability to request quota increases on your behalf after you give us access to the AWS sub-account, we recommend that you review the following quotas and request increases as necessary, as requesting quota increases later will delay the process:

You can read more about how to request a quota increase in the AWS requesting a quota increase documentation.

If you have AWS Enterprise Support, you can contact your account manager to expedite quota requests; otherwise, quota requests above your current limit can take at least one business day. There is also a limit on how often you can make quota requests. A quota request can only be made once every 6 hours.

Step 5: Initiating the provisioning process

Once the CloudFormation stack has returned as CREATED, notify your Solutions Engineer, providing them the following information:

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.

Optionally, PlanetScale can connect you to your databases via AWS PrivateLink with PlanetScale Managed. See the AWS PrivateLink documentation for more information on establishing a PrivateLink connection.