Configuring external masters for first generation

This page describes how to configure an external master that replicates to First Generation replicas.

An External master (or Primary Server) is a MySQL instance that is external to Cloud SQL and serves as the master (primary) First Generation instance. MySQL servers running on Compute Engine are considered to be external to Cloud SQL.

About the external master configuration

The Cloud SQL external master configuration enables you to create a Cloud SQL First Generation instance that replicates from a master instance that is external to Cloud SQL. The Cloud SQL replica is not accessible to applications; it can be promoted to become a standalone First Generation instance, or it can serve as an up-to-date copy of the data on the master.

This configuration requires a Cloud SQL instance, called the internal master instance, which is shown in Cloud SQL as the master for the Cloud SQL replicas. The internal master instance and the external instance together make up the master instance for the Cloud SQL replica.

Diagram of the external master configuration

Data is replicated directly from the external master to the Cloud SQL replicas; the internal master instance is not involved with data replication. Although the internal master instance appears to be a standard Cloud SQL instance, you are not charged for the internal master instance. You cannot administer the internal master instance directly.

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 Admin API.

    Enable the API

External master configuration requirements

  • The internal master instance and the Cloud SQL replicas must be First Generation instances.
  • The external master instance and the Cloud SQL replicas must use the same version of MySQL (5.5 or 5.6).
  • Binary logging must be enabled on the external master. Learn more.
  • The server-id option must be set to a value of 2 or larger. Learn more.
  • If the external master is on a Compute Engine instance, it must have an assigned public IP address.
  • The external master must be accessible to public IP addresses.
  • The dump file you create of the master, which will be used to provide a starting image for the internal master, must conform to the requirements for dump files for Cloud SQL. Learn more.
  • You must configure a replication user account on the external master with the REPLICATION SLAVE privilege.

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:

    gcloud auth login
    ACCESS_TOKEN="$(gcloud auth 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]",
                  "caCertificate": "[SOURCE_SERVER_CA]",
                  "clientCertificate": "[CLIENT_CERT]",
                  "clientKey": "[PRIVATE_KEY]"}},
              "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.

    The SSL/TLS information is optional, but highly recommended for security.

    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/TLS, you should, at a minimum, update your replication user to allow access only from the replicas. Learn more.

What's next

Learn about managing replicas.