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

本页面介绍如何将 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 会临时使用一个额外的 /24 范围在新架构上托管已升级的实例。在 Cloud SQL 升级网络和区域组合中的所有实例后，Cloud SQL 会释放该范围。

例如，如果您的网络包含两个实例，一个实例位于 us-east1，另一个实例位于 us-central1，那么无论是否启用了高可用性，您都可以升级这两个实例。但是，如果您的网络包含三个实例，一个位于 us-east1，另外两个位于 us-central1，则可以升级 us-central1 中启用了高可用性的实例。由于 us-east1 中的实例是该区域中的唯一实例，因此无论是否启用了高可用性，您都可以升级该实例。
将高可用性实例升级到新网络架构后，您无法对该实例停用高可用性。
如果您从外部来源连接到实例，请验证所有对等互连连接是否已更新，以启用自定义路由导出。

对于升级，不支持使用故障切换副本的旧版高可用性 (HA) 实例。
升级网络架构后，您无法为升级后的实例创建旧版高可用性故障切换副本。
如果您在 2023 年 8 月 11 日之后为 Cloud SQL 实例启用了时间点恢复 (PITR) 或复制，则无法升级实例。这是因为在 2023 年 8 月 11 日之后，PITR 日志存储在 Cloud Storage 中。

规划升级网络项目中的所有 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
   ...
   sql_network_architecture: OLD_NETWORK_ARCHITECTURE

如果实例使用新的网络架构，则响应类似于以下内容：

   name: INSTANCE_NAME
   project: PROJECT_ID
   ...
   sql_network_architecture: NEW_NETWORK_ARCHITECTURE

sql_network_architecture 参数指示您的实例使用的是旧网络架构 (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)

将请求正文保存在名为 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)

将请求正文保存在名为 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)

将请求正文保存在名为 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)

将请求正文保存在名为 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/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/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

PowerShell (Windows)

将请求正文保存在名为 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/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 实例的所有功能在新架构上的工作方式都与在旧架构上相同。将实例升级为使用新网络架构后，如果要切换该实例的网络，请确保目标网络中的所有实例也已升级到新网络架构。

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

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

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

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

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

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

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

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

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

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

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

后续步骤

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