将实例升级到新的网络架构

本页面介绍如何将 Cloud SQL 实例从旧网络架构升级到新网络架构。

此 Cloud SQL 网络架构升级页面仅适用于某些 Cloud SQL 实例。如果您的 Cloud SQL 实例使用 2021 年 8 月之前创建的 Virtual Private Cloud (VPC) 网络项目，则您需要升级实例的 Cloud SQL 网络架构。

概览

下表显示了新网络架构与旧网络架构相比的优势：

能力	旧网络架构	新网络架构
使用 Database Migration Service 从 Cloud SQL 迁移到 AlloyDB for PostgreSQL 以及从 AlloyDB for PostgreSQL 迁移到 Cloud SQL	要求您为迁移配置专用 IP 地址	无需额外网络配置。例如，从 Cloud SQL 迁移到 AlloyDB for PostgreSQL 或从 AlloyDB for PostgreSQL 迁移到 Cloud SQL。
使用专用 IP 将您的 Cloud SQL 实例连接到专用服务（如 Cloud Build 或 Vertex AI）	由于网络对等互连不传递性而不受支持	支持
符合 Assured Workloads 要求的实例	不支持	支持
托管式 Microsoft AD	不支持	支持
Private Service Connect	不支持	支持
每个项目的默认 Cloud SQL 实例配额	100	1000

规划升级

在升级 Cloud SQL 实例的网络架构之前，请根据以下升级限制条件规划升级：

如果您升级网络架构，则实例的停机时间平均长达 4 分钟。
如果存在正在进行的数据迁移，则无法在数据迁移期间将源实例升级到新架构。
如果您从外部来源连接到实例，请验证所有对等互连连接是否已更新，以便能够导出自定义路由。
您无法在 Cloud SQL 实例超过 300 个的网络上升级实例的网络架构。
如果您的网络在同一区域中包含两个或多个使用专用 IP 地址的实例，则 Cloud SQL 必须使用您分配的专用服务访问通道 IP 地址范围内的额外 /24 子网范围，以在新网络架构中托管这些实例。这是临时性占用，后续发生 Cloud SQL 维护事件期间会将其移除。

对于升级，不支持使用故障切换副本的旧版高可用性 (HA) 实例。
升级网络架构后，您无法为升级后的实例创建旧版高可用性故障切换副本。

规划升级网络项目中的所有 Cloud SQL 实例

您的 Cloud SQL 实例可以与 VPC 网络位于同一项目中，也可以托管在单独的项目中。托管 VPC 网络的项目是网络项目。

如果网络项目中至少有一个 Cloud SQL 实例使用旧网络架构，则整个项目都会使用旧网络架构。在这种情况下，您的项目不会完全升级到新网络架构。

您可以使用 gcloud CLI 或 Cloud SQL Admin API 来查询项目中所有 Cloud SQL 实例的网络架构。

如果您修改实例的专用网络或者为实例启用专用 IP，则无法在同一请求中修改网络架构。如果您这样做，请求将被拒绝。为避免这种情况，我们建议您在升级网络项目之前升级网络项目中的所有实例。

升级 Cloud SQL 网络架构

如需升级 Cloud SQL 实例的网络架构，请执行以下操作：

检查单个 Cloud SQL 实例或多个 Cloud SQL 实例的网络架构。
升级 Cloud SQL 实例的网络架构。

检查单个 Cloud SQL 实例的网络架构

如需检查单个实例的当前网络架构，请使用 gcloud sql instances describe 命令或 instances.get 方法。

gcloud

如需了解如何安装和开始使用 gcloud CLI，请参阅安装 gcloud CLI。如需了解如何启动 Cloud Shell，请参阅使用 Cloud Shell。

如需检查单个实例的网络架构，请运行以下命令：

   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

sqlNetworkArchitecture 参数指示您的实例使用的是旧网络架构 (OLD_NETWORK_ARCHITECTURE) 还是新网络架构 (NEW_NETWORK_ARCHITECTURE)。

REST v1

如需检查实例的网络架构，请使用 Cloud SQL Admin API 的 instances.get 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
INSTANCE_NAME：实例名称。
NETWORK_ARCHITECTURE_TYPE：网络架构类型定义如下：
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

REST v1beta4

如需检查实例的网络架构，请使用 Cloud SQL Admin API 的 instances.get 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
INSTANCE_NAME：实例名称。
NETWORK_ARCHITECTURE_TYPE：网络架构类型定义如下：
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

检查多个 Cloud SQL 实例的网络架构

如需检查项目中多个实例的网络架构，请使用 gcloud sql instances list 命令或 instance.list 方法。

gcloud

如需检查项目中多个实例的网络架构，请运行以下命令：

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

REST v1

如需检查项目中多个实例的网络架构，请使用 instance.list 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
NETWORK_ARCHITECTURE_TYPE：网络架构类型，如下所示：:
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

REST v1beta4

如需检查项目中多个实例的网络架构，请使用 instance.list 方法。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
NETWORK_ARCHITECTURE_TYPE：网络架构类型定义如下：
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

升级单个 Cloud SQL 实例的网络架构

如需升级单个实例的网络架构，请使用 gcloud sql instances patch 命令、instance.update 方法或 instance.patch 方法。

gcloud

如需升级实例的网络架构，请运行以下命令：

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

升级操作需要几分钟时间。

升级期间，会启动一个长时间运行的操作，并返回操作令牌：

operation_id

REST v1

如需升级实例的网络架构，请使用 Cloud SQL Admin API 的 instance.update 或 instance.patch 方法。

升级 Cloud SQL 网络架构时，请求中不允许对实例进行其他更新。请求正文包含 DatabaseInstance 对象的一个实例，其中 sqlNetworkArchitecture 设置为 NEW_NETWORK_ARCHITECTURE。

升级期间，会启动一个长时间运行的操作，并返回操作令牌：

operation_id

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
INSTANCE_NAME：实例名称。
NETWORK_ARCHITECTURE_TYPE：网络架构类型定义如下：
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

如果实例的升级失败，请重试升级操作。

REST v1beta4

如需升级实例的网络架构，请使用 Cloud SQL Admin API 的 instance.update method 或 instance.patch method。

升级期间，会启动一个长时间运行的操作，并返回以下操作令牌：

operation_id

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：项目 ID。
INSTANCE_NAME：实例名称。
NETWORK_ARCHITECTURE_TYPE：网络架构类型定义如下：
- OLD_NETWORK_ARCHITECTURE：实例使用旧网络架构。
- NEW_NETWORK_ARCHITECTURE：实例使用新网络架构。

HTTP 方法和网址：

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

请求 JSON 正文：

{
  "sqlNetworkArchitecture": "NETWORK_ARCHITECTURE_TYPE"
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

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"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$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

您应该收到类似以下内容的 JSON 响应：

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

如果实例升级因任何原因失败，您可以重试升级操作。

常见问题解答

本部分提供了有关升级 Cloud SQL 网络架构的常见问题解答。

升级对 Cloud SQL 实例有何影响？
升级后，所有功能是否都保持不变？
哪些实例使用旧网络架构？
是否所有新 Cloud SQL 实例都在新网络架构上创建？
能否使用一条命令更新项目中的所有实例？
如果我升级主实例，副本是否会自动升级？
我收到通知，Cloud SQL 实例的网络架构将升级。我需要做什么？
为什么我无法升级可用区级实例的网络架构？
当我尝试升级实例时，收到“outside the reserved IP address range”（超出预留的 IP 地址范围）错误。我需要做什么？

升级对 Cloud SQL 实例有何影响？

升级网络架构时，Cloud SQL 实例处于“维护”状态。在此状态下，实例平均会经历长达 4 分钟的停机时间。在升级完成之前，不允许对实例进行任何其他更改。您的项目或网络中的其他实例不会受升级的影响。

升级后，所有功能是否都保持不变？

Cloud SQL 实例的所有功能在新架构上的工作方式都与在旧架构上相同。将实例升级为使用新网络架构后，如果要切换该实例的网络，请确保目标网络中的所有实例也已升级到新网络架构。

哪些实例使用旧网络架构？

2021 年 8 月以后创建的所有新项目都会自动使用新网络架构。现有项目可以包含超过两年的 Cloud SQL 实例，并且这些实例仍使用旧网络架构。因此，现有项目中的所有实例都必须升级，然后该项目中的任何新实例才能开始使用新网络架构。

是否所有新 Cloud SQL 实例都在新网络架构上创建？

默认情况下，在 2021 年 8 月以后创建的项目中创建的新 Cloud SQL 实例都会使用新网络架构。如果要在 2021 年 8 月之前创建的项目中创建实例，并使用新网络架构，则必须执行以下操作：

将该项目中的所有现有实例更新为新网络架构。
如果您有 Google Cloud 支持合同，请创建支持请求，将项目的默认网络架构更改为新架构。
如果您没有支持合同，请创建实例，然后将其升级到新网络架构。

更改项目的默认值后，您可以使用该项目中的新网络架构创建实例。

如果您不更改项目的默认网络架构，则该项目中的所有新实例都将使用旧网络架构。然后，您必须将每个实例分别升级为新网络架构。

能否使用一条命令更新项目中的所有实例？

否，升级为新网络架构基于每个实例。

如果我升级主实例，副本是否会自动升级？

否，升级为新网络架构基于每个实例。每个副本均视为单独的实例，必须单独升级。这意味着，如果主实例升级并且副本使用旧网络架构，则副本不受影响。反之亦然。如果您升级副本，则主实例不会受到影响。

我收到通知，Cloud SQL 实例的网络架构将升级。我需要做什么？

您无需执行任何操作。

对于某些实例，当在专用网络上进行自动升级时，请求会暂时被拒绝。如需解决此问题，您可以按照升级单个 Cloud SQL 实例的网络架构中的过程自行升级实例的网络架构。

为什么我无法升级可用区级实例的网络架构？

如果实例配置了可用区级可用性，并且跳过了上次预定的维护事件，则实例可能不支持升级到新网络架构。如需解决此问题，请为实例启用高可用性，然后升级网络架构。升级后，您可以将实例配置更改回可用区级可用性。

当我尝试升级实例时，收到“outside the reserved IP address range”（超出预留的 IP 地址范围）错误。我需要做什么？

如需在具有专用 IP 的 VPC 网络中使用 Cloud SQL 实例，请在为该 VPC 网络设置专用服务访问通道时分配 IP 地址范围。

例如，如果分配的 IP 地址范围发生更改或被删除，您可能会遇到类似于以下内容的错误：

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.

在此示例中，原始分配的 IP 地址范围的名称为 google-managed-services-VPC_NETWORK_NAME，原始分配的 IP 地址范围为 10.0.0.0/16。然后，创建一个专用 IP 地址为 10.0.0.1 的实例。如果 IP 地址范围 google-managed-services-VPC_NETWORK_NAME 被删除，或者更新为引用范围 10.1.0.0/16，则此范围不涵盖实例的专用 IP 地址 10.0.0.1。之后，当您尝试升级实例的网络架构时，会遇到 outside the reserved IP address range 错误。

如需解决此问题，请按照为 Cloud SQL 配置专用服务访问通道中的过程操作。将包含实例 IP 地址的 IP 地址范围重新分配到为专用服务访问通道分配的范围。您至少可以分配错误消息中报告的 IP 地址范围（在上述示例中为 10.0.0.0/24）。

然后重试网络架构升级。

后续步骤

详细了解 Private Service Connect
详细了解 Assured Workloads
详细了解如何为 Cloud SQL 配置专用服务访问通道
详细了解如何将 Database Migration Service 迁移到 AlloyDB for PostgreSQL