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:

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 sql instances describe INSTANCE_NAME
   

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

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

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

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

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

{
  "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 sql instances list --show-sql-network-architecture

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

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X LIST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method LIST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

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

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X LIST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method LIST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

{
  "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 sql instances patch INSTANCE_NAME --upgrade-sql-network-architecture

operation_id

operation_id

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

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

operation_id

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

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

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

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?
• Do all features work the same after the upgrade?
• Which instances use the old network architecture?
• Are all new Cloud SQL instances created on the new network architecture?
• Is it possible to update all instances in a project with a single command?
• Does the replica automatically get upgraded if I upgrade the primary?
• I received a notification that the network architecture of my Cloud SQL instances will be upgraded. What do I need to do?
• When I attempt to upgrade my instance, I receive the error "outside the reserved IP address range". What do I need to do?

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

• Read more about Private Service Connect
• Read more about Assured Workloads
• Read more about Configure private service access for Cloud SQL
• Read more about Database migration service to AlloyDB for PostgreSQL