Configuring External Masters

This page describes how to configure an external master that replicates to Cloud SQL replicas.

External masters are MySQL instances that are external to Cloud SQL and serve as masters to a Cloud SQL instance.

For more information about the external master configuration, see Requirements and Tips for Configuring Replication.

Before you begin

  • You must have an external instance that meets the requirements for an external master instance.
  • You must have the external IP address and port of the external master instance, and the username and password information for the replication user on the master instance.
  • Enable the Cloud SQL Administration API.

    Enable the API

Preparing the data

To prepare your data for use in an external master configuration you create a mysqldump file containing the data from the master instance and upload the dump file to Cloud Storage.

  1. Create a Cloud Storage bucket.

    You will use the bucket to hold your dump file for import into the replica. For more information, see Creating storage buckets.

  2. Create a mysqldump file from the master instance, following the external replication instructions in Creating a SQL dump file.

  3. Upload the file to the Cloud Storage bucket.

    For more information, see Uploading data to a bucket.

Creating the external master configuration

  1. Create the internal master instance, using the region where you want your replicas to reside and the external IP address and port of the external master instance:

    ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"
    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"name": "[INTERNAL_MASTER_INSTANCE_NAME]",
              "region": "[REGION_NAME]",
              "databaseVersion": "[EXTERNAL_MASTER_DATABASE_VERSION]",
              "onPremisesConfiguration": {"hostPort": "[IP_ADDRESS:PORT]"}}' \
     -X POST \[PROJECT-ID]/instances

    The internal master instance is created, with the IP address and port of the external master showing as its IP address.

  2. After the internal master instance finishes initializing, create a replica, providing the replication user account information from the external master, and the location of the data you prepared previously:

    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{"replicaConfiguration":
                 {"username": "[REPLICATION_USER]", "password": "[REPLICATION_USER_PASSWORD]",
                  "dumpFilePath": "[BUCKET_LOCATION]" }},
              "settings": {"tier": "[TIER]","activationPolicy": "ALWAYS"},
              "databaseVersion": "[EXTERNAL_MASTER_DATABASE_VERSION]",
              "masterInstanceName": "[INTERNAL_MASTER_INSTANCE_NAME]",
              "name": "[REPLICA_NAME]", "region": "[REGION_NAME]"}' \
     -X POST \[PROJECT-ID]/instances

    In the request body, the dumpFile, username, and password fields are mandatory. The dumpFile field is of the form gs://bucket-location/filename. You must use a First Generation tier, such as D4. For databaseVersion, provide the MySQL version of the master instance: MYSQL_5_5 or MYSQL_5_6. The region field must be the same as the master.

    When the replica is first created, it is behind the master, but replication should catch up over time if the replica is properly sized for the workload.

  3. (Optional) Repeat the previous step to create additional replicas.

  4. If you have not configured your master instance to use SSL, you should, at a minimum, update your replication user to allow access only from the replicas. Learn more.

What's next

Learn about requirements and best practices for the external master configuration.

Send feedback about...

Cloud SQL for MySQL