Upgrade an instance to the new network architecture


This page describes how to upgrade your Cloud SQL instances from the old network architecture to the new network architecture.

This Cloud SQL network architecture upgrade page applies only to some Cloud SQL instances. If your Cloud SQL instances use a Virtual Private Cloud (VPC) network project that was created before August 2021, then you need to upgrade the Cloud SQL network architecture for your instances.

Overview

The following table shows the benefits of new network architecture compared to the old network architecture:

Capability Old network architecture New network architecture
Migrating from Cloud SQL to AlloyDB for PostgreSQL using Database Migration Service Requires that you configure a private IP address for the migration No additional network configuration required.

For example, Cloud SQL to AlloyDB for PostgreSQL migration.
Connect your Cloud SQL instance by using private IP to private services such as Cloud Build or Vertex AI Not supported due to network peering intransitivity Supported
Instances that are compliant with Assured Workloads Not supported Supported
Managed Microsoft AD Not supported Supported
Private Service Connect Not supported Supported
IP address range usage Extra IP address ranges consumed for dedicated subnets for Cloud SQL for PostgreSQL private IP instances No extra IP address ranges consumed for Cloud SQL for PostgreSQL instances
Default Cloud SQL instance quota per project 100 1000

Plan your upgrade

Before you upgrade the network architecture of your Cloud SQL instances, plan the upgrade according to the following upgrade constraints:

  • If you upgrade your network architecture, then you can expect downtime on your instance of up to 4 minutes on average.

  • If there's an ongoing data migration, then you can't upgrade the source instance to the new architecture during the data migration.

  • If you connect to an instance from an external source, then verify that all peering connections are updated to enable the export of custom routes.

  • If you're using service perimeters, then verify that Shared VPC host project is included. If this project isn't included, then the migration fails.

  • You can't upgrade the network architecture of instances on a network with more than 300 Cloud SQL instances.

  • If your network includes two or more instances that use private IP addresses in the same region, then Cloud SQL must use an additional /24 range (or ranges) from your allocated private services access IP address range to host the instances in the new network architecture. This additional consumption is temporary, and is removed during a subsequent Cloud SQL maintenance event.

Plan to upgrade all Cloud SQL instances in a network project

Your Cloud SQL instances can reside either in the same project as the VPC network or in a separate project. The project hosting the VPC network is the network project.

A network project can operate in dual stack mode, meaning that it can host Cloud SQL instances simultaneously, using both the old and new network architectures. This occurs when at least one instance within the project uses the old architecture. As a result, Cloud SQL can't upgrade the project to the new architecture.

To query the network architecture for all instances within a project, you can use gcloud CLI or the API.

Considerations for dual stack projects

When using dual stack projects, keep in mind the following considerations:

  • Upgrade an instance implicitly: When you modify an instance's private network or enable the private IP address within a dual stack project, Cloud SQL might upgrade the instance to the new network architecture implicity.
  • No architecture downgrades: Network changes never downgrade an instance's network architecture.
  • Reject requests: If a network change needs a downgrade to complete, then Cloud SQL rejects the request.

To avoid potential conflicts and to ensure a smooth network upgrade, we recommend that you plan to upgrade all instances in the project to the new architecture.

Upgrade your Cloud SQL network architecture

To upgrade the network architecture of your Cloud SQL instance, do the following:

  1. Check the network architecture of either a single Cloud SQL instance or multiple Cloud SQL instances.
  2. Upgrade the network architecture of a Cloud SQL instance.

Check the network architecture of a single Cloud SQL instance

To check the current network architecture of a single instance, use the gcloud sql instances describe command or the instances.get method.

gcloud

For information about installing and getting started with the gcloud CLI, see Install the gcloud CLI. For information about starting Cloud Shell, see Use Cloud Shell.

To check the network architecture of a single instance, run the following command: 

   gcloud sql instances describe INSTANCE_NAME

If the instance uses the old network architecture, then the response is similar to the following:

   name: INSTANCE_NAME
   project: PROJECT_ID
   ...
   sqlNetworkArchitecture: OLD_NETWORK_ARCHITECTURE

If the instance uses the new network architecture, then the response is similar to the following:

   name: INSTANCE_NAME
   project: PROJECT_ID
   ...
   sqlNetworkArchitecture: NEW_NETWORK_ARCHITECTURE

The sqlNetworkArchitecture parameter indicates whether your instance uses the old network architecture (OLD_NETWORK_ARCHITECTURE) or the new network architecture (NEW_NETWORK_ARCHITECTURE).

REST v1

To check the network architecture of an instance, use the instances.get method of the Cloud SQL Admin API.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • INSTANCE_NAME: The instance name.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

REST v1beta4

To check the network architecture of an instance, use the instances.get method of the Cloud SQL Admin API.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • INSTANCE_NAME: The instance name.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

GET https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

Check the network architecture of multiple Cloud SQL instances

To check the network architecture of multiple instances in a project, use the gcloud sql instances list command or the instance.list method.

gcloud

To check the network architecture of multiple instances in a project, run the following command: 

gcloud sql instances list --show-sql-network-architecture

The output looks similar to the following.

NAME        DATABASE_VERSION LOCATION   ...     SQL_NETWORK_ARCHITECTURE
instance_1  POSTGRES_13      asia-northeast1-b  OLD_NETWORK_ARCHITECTURE
instance_2  MYSQL_5_7        europe-west1-d     NEW_NETWORK_ARCHITECTURE
...

REST v1

To check the network architecture of multiple instances in a project, use the instance.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

LIST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

REST v1beta4

To check the network architecture of multiple instances in a project, use the instance.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

LIST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance
  "name": INSTANCE_NAME
  "project": PROJECT_ID
  "sqlNetworkArchitecture": enum (SqlNetworkArchitecture)
  ...
}

Upgrade the network architecture of a single Cloud SQL instance

To upgrade the network architecture for a single instance, use the gcloud sql instances patch command, the instance.update method, or the instance.patch method.

gcloud

To upgrade the network architecture of an instance, run the following command: 

gcloud sql instances patch INSTANCE_NAME --upgrade-sql-network-architecture

The upgrade operation takes a few minutes.

During the upgrade, a long-running operation starts, and an operation token is returned:

operation_id

REST v1

To upgrade the network architecture of an instance, use the instance.update or the instance.patch method of the Cloud SQL Admin API.

When you upgrade the Cloud SQL network architecture, no additional updates to the instance are allowed in the request. The request body contains an instance of the DatabaseInstance object, with sqlNetworkArchitecture set to NEW_NETWORK_ARCHITECTURE.

During the upgrade, a long-running operation starts, and an operation token is returned:

operation_id

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • INSTANCE_NAME: The instance name.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance,
  "targetLink": string,
  "status": enum (SqlOperationStatus),
  "name": string,
  "insertTime": string,
  "startTime": string,
  "endTime": string
  ...
}

If the upgrade of your instance fails, then retry the upgrade operation.

REST v1beta4

To upgrade the network architecture of an instance, use the instance.update method or the instance.patch method of the Cloud SQL Admin API.

When you upgrade the Cloud SQL network architecture, no additional updates to the instance are allowed in the request. The request body contains an instance of the DatabaseInstance object, with sqlNetworkArchitecture set to NEW_NETWORK_ARCHITECTURE.

During the upgrade, a long running operation starts, and the following operation token is returned:

operation_id

Before using any of the request data, make the following replacements:

  • PROJECT_ID: The project ID.
  • INSTANCE_NAME: The instance name.
  • NETWORK_ARCHITECTURE_TYPE: The network architecture type is defined as follows:
    • OLD_NETWORK_ARCHITECTURE: The instance uses the old network architecture.
    • NEW_NETWORK_ARCHITECTURE: The instance uses the new network architecture.

HTTP method and URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Request JSON body: 

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": sql#instance,
  "targetLink": string,
  "status": enum (SqlOperationStatus),
  "name": string,
  "insertTime": string,
  "startTime": string,
  "endTime": string
  ...
}

If the upgrade of your instance fails for any reason, you can retry the upgrade operation.

Frequently asked questions

This section provides answers to frequently asked questions about upgrading your Cloud SQL network architecture.

What's the impact of the upgrade on my Cloud SQL instance?

When upgrading your network architecture, the Cloud SQL instance has a MAINTENANCE state. In this state, the instance experiences up to four minutes of downtime, on average. Any additional changes to the instance aren't allowed until the upgrade is complete. Other instances in your project or network aren't affected by the upgrade.

Do all features work the same after the upgrade?

All features of your Cloud SQL instance work the same on the new architecture as they did on the old architecture. After you upgrade an instance to use the new network architecture, if you want to switch the network of that instance, then make sure that all instances in the destination network are also upgraded to the new network architecture.

Which instances use the old network architecture?

Any new projects that were created after August, 2021 automatically use the new network architecture. Existing projects can contain Cloud SQL instances that are older than two years and still use the old network architecture. Therefore, all instances within an existing project must be upgraded before any new instances in that project can start using the new network architecture.

Are all new Cloud SQL instances created on the new network architecture?

By default, new Cloud SQL instances created in projects created after August 2021 use the new network architecture.

If you want to create an instance in a project created before August 2021 and use the new network architecture, then you must update all of your existing instances in that project to the new network architecture. If you're using Shared VPC, then you must update all instances in the projects that are participating in the Shared VPC.

After you've updated all the existing instances in your project, wait several hours before you create any instances in the project. New instances that you create in the project use the new network architecture.

Is it possible to update all instances in a project with a single command?

No, the upgrade to the new network architecture is based on each instance.

Does the replica automatically get upgraded if I upgrade the primary?

No, the upgrade to the new network architecture is based on each individual instance. Each replica is treated as a separate instance and must be upgraded separately. This means that if the primary is upgraded and the replica is using the old network architecture, the replica isn't affected. The opposite is also true. If you upgrade a replica, the primary won't be affected.

I received a notification that the network architecture of my Cloud SQL instances will be upgraded. What do I need to do?

No action is required by you.

For some instances, when the automatic upgrade occurs on a private network, the request is temporarily rejected. As a workaround, you can upgrade the network architecture of your instance yourself by following the procedure in Upgrade the network architecture of a single Cloud SQL instance.

When I attempt to upgrade my instance, I receive the error "outside the reserved IP address range". What do I need to do?

To use Cloud SQL instances in a VPC network with private IP, allocate IP address ranges when you set up private services access for the VPC network.

For example, if an IP allocated address range is changed or deleted, then you might encounter an error similar to the following:

Network architecture upgrade not allowed for private-ip instance PROJECT_ID:INSTANCE_NAME
whose IP address range 10.0.0.0/24 is outside the reserved IP address range for
private services access. Re-allocate the IP address range for private services access and retry.

In this example, the original allocated IP address range has the name google-managed-services-VPC_NETWORK_NAME, and the original allocated IP address range is 10.0.0.0/16. Then you create an instance with a private IP address of 10.0.0.1. If the IP address range of google-managed-services-VPC_NETWORK_NAME is deleted, or is updated to refer to a range of 10.1.0.0/16 this range doesn't cover the instance's private IP address 10.0.0.1. Afterwards, when you try to upgrade the network architecture of your instance, you encounter the outside the reserved IP address range error.

To resolve this issue, follow the procedure in Configure private services access for Cloud SQL. Re-allocate an IP address range that includes the IP address of your instance into the ranges allocated for private services access. At the least, you can allocate the IP address range reported in your error message (in the previous example, 10.0.0.0/24.)

Then retry the network architecture upgrade.

What's next